octopus

Octopus

AI-powered PR review tool. Multi-armed code analysis — no bug escapes.

Octopus analyzes pull and merge requests via GitHub, GitLab, and Bitbucket webhooks, creates code embeddings with vector search, reviews changes using Claude or OpenAI, and posts findings as inline comments with severity levels.

Features

• Automated PR & MR Reviews — AI-powered code review with severity indicators (🔴 Critical, 🟠 Major, 🟡 Minor, 🔵 Info, 💡 Suggestion)
• Codebase Indexing — Chunks and embeds your code into Qdrant for context-aware reviews
• Multi-Provider AI — Claude (Anthropic), OpenAI, Google, and Cohere models per organization, with Bring Your Own Keys (BYOK)
• GitHub, GitLab & Bitbucket — Native webhook integrations across all three platforms, including self-managed GitLab
• Knowledge Center — Org-level knowledge plus pinned documents that are always included in every review
• Repo Config Files — Honor .octopus.md, AGENTS.md, or CLAUDE.md as repo-scoped review rules, extracted in a sandboxed pass
• Slack Integration — Ask questions about your codebase directly from Slack
• Linear & Jira Integration — Create issues from review findings with one click
• CLI — @octp/cli for local review runs, plus a Claude Code skill for terminal workflows
• Review Output Language — Org-level setting for the prose language of summaries and findings (code stays in source language)
• Repository Graph — Structural and semantic edges across your codebase
• Real-time Updates — Live dashboard updates via WebSocket (Pubby)
• Usage & Cost Tracking — Per-org token usage tracking with monthly spend limits
• Team Management — Multi-org support with role-based access
• Free for Open Source — Public OSS repositories get free reviews via a separate community pipeline

Tech Stack

• Runtime: Bun
• Framework: Next.js 16 (App Router, React 19)
• Styling: Tailwind CSS 4 + shadcn/ui
• Database: PostgreSQL with Prisma
• Vector Store: Qdrant
• Auth: Better Auth (Google, GitHub OAuth, Magic Link)
• Monorepo: Turborepo

Project Structure

octopus/
├── apps/
│   ├── web/              # Next.js web application
│   └── cli/              # octp CLI (@octp/cli)
├── packages/
│   └── db/               # Prisma schema & shared DB client
└── tools/
    ├── tsconfig/         # Shared TypeScript configs
    └── eslint-config/    # Shared ESLint config

Getting Started

Prerequisites

• Bun (v1.3.4+)
• PostgreSQL
• Qdrant instance
• API keys for Claude (Anthropic) and/or OpenAI

Installation

# Clone the repository
git clone https://github.com/octopusreview/octopus.git
cd octopus

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Generate Prisma client
bun run db:generate

# Run database migrations
bun run db:migrate

# Start the development server
bun run dev

Commands

bun install              # Install dependencies
bun run dev              # Start all apps (Turborepo)
bun run build            # Build all packages
bun run lint             # Lint all packages
bun run typecheck        # Type-check all packages

# Database
bun run db:generate      # Generate Prisma client
bun run db:migrate       # Run migrations (dev)
bun run db:push          # Push schema to DB (no migration)
bun run db:studio        # Open Prisma Studio

Self-Hosting with Docker

# Clone and configure
git clone https://github.com/octopusreview/octopus.git
cd octopus
cp .env.example .env
# Edit .env with your API keys and configuration

# Pull the prebuilt public image + start all services (PostgreSQL, Qdrant, Web).
# The image bakes in email/password login for self-hosted instances — no build.
export OCTOPUS_VERSION=latest   # or a pinned release, e.g. 1.0.27
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d

# Run database migrations — from the checkout, not inside the container
# (the runtime image ships only the compiled app, no prisma/schema)
cd packages/db
DATABASE_URL=postgresql://octopus:octopus@localhost:43332/octopus bunx prisma migrate deploy
cd ../..

Octopus will be available at http://localhost:43300.

Prefer to build from source? Use docker-compose.yml with docker compose build --build-arg NEXT_PUBLIC_OCTOPUS_SELF_HOSTED=true. See docker-compose.selfhost.yml (pull) and docker-compose.yml (build) for service configuration.

How It Works

1. Webhook — GitHub, GitLab, or Bitbucket sends a PR/MR event to Octopus
2. Index — Octopus clones the repo, chunks the code, and creates vector embeddings in Qdrant
3. Analyze — The codebase is analyzed using AI with relevant code chunks, pinned docs, and org knowledge
4. Review — The diff is reviewed by the LLM, generating findings with severity levels and category-based thresholds
5. Comment — Findings are posted as inline comments on the PR/MR, with one-click Linear or Jira issue creation

Roadmap

See ROADMAP.md for what we're building and the Octopus Roadmap Project board for the live, sortable view.

Work flows through Proposed → Up Next → In Progress → Shipped. Anyone can propose an item by opening a roadmap proposal issue; maintainers promote it to Up Next once it has an owner. The CHANGELOG is the source of truth for what has actually shipped.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Security

Please see SECURITY.md for reporting vulnerabilities.

License

This project is licensed under the Modified MIT License.