Getting Started

Get Started with Octopus

AI-powered code reviews that understand your codebase. Connect your repo and get your first review in minutes.

What is Octopus?

Octopus is an AI-powered code review tool that indexes your entire codebase, learns your patterns and architecture, and reviews every pull request with deep context awareness. It catches real bugs, security issues, and code quality problems before they reach production.

Codebase-Aware

Indexes your code and understands your architecture, not just the diff.

Automatic Reviews

Every PR gets reviewed instantly with severity-rated inline comments.

Works With Your Tools

GitHub, GitLab, Bitbucket, Forgejo, Slack, Linear, Jira. Fits into your existing workflow.

Choose Your Path

Octopus comes two ways. Most teams use Cloud— fully hosted and set up in minutes. If you'd rather run everything on your own infrastructure, the source-available Self-Host path is free.

Recommended

Cloud · Free to start

Hosted for you

Connect your repository View pricing

Self-Host · Free

Run it yourself

Deploy Octopus with Docker on your own infrastructure. Free and source-available — you keep full control of your data.

Self-hosting guide

1. Connect Your Repository

Start by connecting your GitHub, GitLab, Bitbucket, or Forgejo account from the dashboard. Use the GitHub App, GitLab or Bitbucket OAuth, or a Forgejo personal access token. For Forgejo, add the signed webhook shown in Settings to each repository. See the Forgejo setup guide.

GitHub

Install the GitHub App and select repositories.

GitLab

Connect via OAuth on gitlab.com or a self-managed instance.

Bitbucket

Connect via OAuth and Octopus automatically manages webhooks.

Forgejo

Choose Cloud with public HTTPS, Cloud with a local connector for private LAN/VPN access, or self-hosted Octopus with direct access.

In the dashboard's first-review guide, choose a repository and confirm its readiness. Check repository sync and webhook setup in Settings → Integrations; authorization alone does not confirm event delivery. See the setup checks and recovery instructions.

2. Your First Review

Confirm Auto Review is enabled for the selected repository, then open a non-draft pull request or update an existing one. Connecting alone does not trigger reviews of already-open PRs. Follow progress in Review Logs.

Indexing and analysis run automatically when a review starts; manual preparation is optional. Permitted users can change Auto Review during preparation, and indexing preserves that saved setting. Preparation progress and errors appear in the repository panel and dashboard guide.

The first-review milestone completes after successful final publication, not merely after preparation or saving a report. It remains complete if a later rerun fails. Older reviews without a publication receipt do not complete this milestone. Completion confirms the review workflow finished; consult the report for coverage, and check optional notifications separately.

What happens behind the scenes

1Your code host sends a pull request webhook
2Octopus fetches the diff and searches your indexed codebase for relevant context
3AI reviews the changes with full codebase context and your organization's knowledge base
4Findings are posted as inline comments on the PR with severity levels

3. Understanding Findings

Every finding includes a severity level so you can prioritize what matters most. Critical issues block the PR with a REQUEST_CHANGES review, while suggestions are informational.

Critical

Security vulnerabilities, data loss risks, broken functionality. Blocks merge.

Major

Bugs, logic errors, performance issues, and missing error handling.

Minor

Code quality, maintainability, and best practice concerns.

Suggestion

Optional improvements, alternative approaches, and ideas.

Tip

Informational notes about the code, documentation, or conventions.

4. Use the CLI as an AI-Powered Dev Tool

Coding agents can use the Octopus CLI through their terminal tools. Follow the AI coding agents guide for Claude Code, Codex, OpenCode, Hermes Agent, OpenClaw, and Cursor. Install and authenticate the CLI in the environment where your agent executes commands, then check the connection before requesting a review.

octp chat

Start an interactive chat session about your codebase. Ask questions, explore architecture.

octp review --pr 42

Trigger an AI review on any pull request by number or URL.

octp repo index

Index your repository for code search and review context.

octp knowledge add docs/api.md

Add custom documents to your org's knowledge base for richer reviews.

You can also run a local agent on your machine to supercharge Octopus Chat with real-time code search. The agent searches your actual source code when someone asks a question in chat — giving much more precise answers than embeddings alone.

octp agent watch

Add the current repo to the agent's watch list. Detects the repo from the git remote URL.

octp agent serve

Start the local agent. Listens for search requests from Octopus Chat and responds with real-time code results.

Install with curl -fsSL https://octopus-review.ai/install.sh | bash and run octp login to get started. See the full CLI reference for all commands.

5. Customize Your Setup

Fine-tune how Octopus works for your team from the organization settings page.

AI Provider

Choose between Claude, OpenAI, Google Gemini, and Qwen, or bring your own API keys.

Knowledge Base

Upload architecture docs, coding guidelines, and API references so reviews understand your conventions.

.octopusignore

Exclude generated files, test fixtures, and vendor code from reviews and indexing.

Spend Limits

Set monthly token budgets and monitor usage per repository.

Notifications

Configure Slack notifications for review completions, indexing, and more.

Next Steps

Integrations

Connect GitHub, GitLab, Bitbucket, Forgejo, Slack, Linear, and Jira

CLI Reference

All commands and configuration options

Self-Hosting

Deploy Octopus on your own infrastructure

Skills

AI-powered automation workflows