Octocode - Agentic Research Platform

Evidence-first code research for AI agents and developers.

Octocode researches your local code and external code alike (GitHub repos, PRs, npm) with one toolset: ripgrep + AST search, trees, precise reads, and LSP. Use it as a CLI or MCP server, backed by a Rust engine for fast, token-efficient results across single files or mega-repos.

Table of Contents

• Quick Start

• Why Octocode

• Built for Research (Benchmarks)

• Tools

• MCP

• CLI

• Configuration

• Authentication Methods

• Security

• Language Support

• Skills

• Architecture

• Documentation

• Troubleshooting

• Agent Workflows

Related MCP server: CodeGraph CLI MCP Server

Quick Start

Prerequisites: Node.js 20.12+

1. Run the Octocode CLI with npx

npx octocode --help

2. Authenticate with GitHub - optional, but unlocks private repositories and higher API rate limits:

npx octocode auth login
npx octocode status       # verify the active token source

3. Choose your interface. Same tools and Rust engine on both. (Clone is on by default in the CLI, opt-in for MCP.)

🖥️ CLI - research straight from your terminal:

npx octocode

🤖 MCP - one-click install:

Claude Code:

claude mcp add-json octocode --scope user '{"command":"npx","type":"stdio","args":["octocode-mcp@latest"]}'

Any other client: npx octocode install

Use it as an MCP server

Add to your MCP client config (or use a one-click install above):

{
  "octocode": {
    "command": "npx",
    "type": "stdio",
    "args": ["octocode-mcp@latest"]
  }
}

Put a GitHub token and options under env (see Configuration).

Use it as an agentic-friendly CLI

Just run npx octocode, agents figure out the rest. The bare command prints built-in usage and the full tool catalog, so any coding agent knows how to drive it out of the box, no MCP client or extra wiring required.

npx octocode                                         # self-describing usage for agents
npx octocode tools                                   # list every tool
npx octocode tools localSearchCode --scheme          # inspect a tool's schema

Every MCP tool is also a plain command: JSON in, token-efficient YAML out. Local paths route to local tools; owner/repo[/path] routes to GitHub.

npx octocode tools localSearchCode \
  --queries '{"path":".","searchText":"authenticate","maxFiles":20}'

results:
  - id: localSearchCode-1
    data:
      files:
        - path: src/auth.ts
          matches:
            - line: 12
              value: "export async function authenticate(req: Request) {"

Learn more at octocode.ai.

Why Octocode

Agents code better from evidence than from guesses. Octocode researches two worlds with one flow, your local code and external code on GitHub and npm, and hands back compact, citable context before an agent changes, reviews, or explains code. Code is truth; context is the map.

Most tools do one slice (web search, or grep your repo) and hand back a fixed blob. Octocode covers the whole loop and lets the agent decide what data it needs next:

• Agent-driven, efficient flows. Instead of one-shot dumps, Octocode chains cheap steps into an optimized research flow: broad code search, then fetch only the exact matched lines/region, with smart pagination and out-of-the-box minification so the model never over-fetches. Every result carries next-step hints to the cheapest follow-up.

• Scales to monorepos. Spot a pattern in one repo, follow the PR that introduced it, then trace it across other repos and your own files, without leaving the chat. Clone any repo and study it locally.

• Smart GitHub flow. Parallel bulk queries across code, PRs, commits, issues, and repos, all with the same search-broad, read-narrow, trace-semantically discipline.

• Works without GitHub. Clone any repo and point the local tools (search, AST, LSP, content) at it, same evidence-first flow.

• Reads shape, not noise. On-the-fly minify/skeletonize across 70+ languages: a 100 KB file in a few hundred tokens, not walls of boilerplate.

• Fast, self-contained. Search, parsing, navigation, and redaction run in one prebuilt Rust engine: quick on a laptop or a mega-repo, nothing extra to install.

• Safe by default. Every byte to the model is scanned and secrets redacted first (see Security).

What you can do (whenever the next step needs proven context, not a guess):

Built for Research (Benchmarks)

A blind, head-to-head test on research-oriented flows — not simple lookups (multi-hop traces, dependency/call-graph chains, commit ranges, blast-radius, PR reviews across repos).

How it works: 30 GitHub questions × 3 passes; Octocode vs gh, gh+Headroom, and gh+RTK on identical questions (only the CLI differs). A blind judge (gpt-5.5) grades correctness; the metric is characters through the model, counted from instrumented logs (characters, not tokens). Result: at near-parity correctness, Octocode answers with ~2.0× fewer characters than plain gh, ~2.6× fewer than gh+Headroom, and ~3.2× fewer than gh+RTK in the local-build headline runs.

▶ Open the interactive report · run it / method · questions · all reports

Tools

17 tools in the full catalog. MCP registers 14 by default; the CLI exposes 15 because clone is enabled there by default. ghCloneRepo is opt-in on MCP (ENABLE_CLONE=true), while ghListReleases and ghSearchDiscussions are opt-in on both surfaces. Local tools default on for the CLI and off for the MCP server (ENABLE_LOCAL=true enables them on MCP; ENABLE_LOCAL=false disables on CLI). Flags: Configuration.

Token knobs. concise:true returns path/title-only lists. minify controls file read density: symbols = skeleton with line numbers, standard = comments/blanks stripped (default), none = exact bytes.

GitHub Tools

Local Tools

Package Search

LSP

Full schemas, fields, and examples for every tool live in docs/OCTOCODE_TOOLS.md (linked under Documentation).

MCP

The MCP server exposes the Octocode tool catalog directly to your AI assistant over stdio.

https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071

Manual Configuration

Add to your MCP client config, using octocode-mcp:

{
  "octocode": {
    "command": "npx",
    "type": "stdio",
    "args": [
      "octocode-mcp@latest"
    ]
  }
}

Add a GitHub token and options under env - see Authentication and Configuration.

CLI

Same research engine, no MCP client needed. Local paths route to local tools; owner/repo[/path] routes to GitHub. Authenticate once with npx octocode auth login (see Authentication); run npx octocode --help for full usage.

Commands

Tools

More commands

• Cache & clone - npx octocode clone, npx octocode cache fetch|status|clear

• Skills - npx octocode skill list|install|check|info|remove for bundled Octocode skills

• Language servers - npx octocode lsp-server list|install|status|uninstall|clean

• Setup & introspection - npx octocode install, npx octocode auth, npx octocode status, npx octocode context

Full syntax, flags, and exit codes: Octocode CLI Guide

Configuration

Everything is optional; Octocode runs on sensible defaults. Settings resolve from three sources, in priority order:

environment variables  >  <octocode-home>/.octocoderc  >  built-in defaults

1. MCP / environment variables (highest): per client or per project, set in your MCP config env or your shell.

2. Global config: <octocode-home>/.octocoderc, machine-wide defaults read by both the CLI and the MCP server.

3. Built-in defaults: used when neither is set.

Octocode home (<octocode-home>) holds the global config, encrypted credentials, sessions, stats, and tmp materialization caches. It defaults by platform and can be overridden with OCTOCODE_HOME:

Set values as MCP env entries (per client; these win over .octocoderc) or globally in <octocode-home>/.octocoderc (JSON with comments). Tokens never go in .octocoderc - use env or npx octocode auth login.

Common settings

Most-used settings (both CLI and MCP unless noted):

OCTOCODE_HOME, GitHub Enterprise (GITHUB_API_URL), MCP tool whitelisting (TOOLS_TO_RUN/ENABLE_TOOLS/DISABLE_TOOLS), and network timeouts/retries: see the Configuration Reference.

Example Configuration

~/.octocode/.octocoderc:

{
  "github": {
    "apiUrl": "https://api.github.com"
  },
  "local": {
    "enabled": true,
    "enableClone": true
  },
  "output": {
    "format": "yaml"
  }
}

Per-project overrides and custom LSP servers live in a workspace .octocode/ folder. For the full .octocoderc schema, a ready-to-copy example, clone-cache tuning, GitHub Enterprise setup, and precedence details, see the Configuration Reference.

Authentication Methods

GitHub-backed tools require authentication. Any one method is enough. Full details: Authentication Setup.

Option 1: Octocode CLI (Recommended)

npx octocode auth login
npx octocode status       # verify the active token source

Interactive login lets you choose Octocode browser OAuth or gh auth login. Octocode OAuth credentials are stored encrypted on disk.

Option 2: GitHub CLI (also supported)

gh auth login

Octocode reads the gh token automatically - no further config needed.

Option 3: Personal Access Token (also supported)

Set OCTOCODE_TOKEN, GH_TOKEN, or GITHUB_TOKEN in your shell. Required scopes: repo, read:user, read:org.

Create a token at github.com/settings/tokens.

Security tip: Never commit tokens to version control. Use environment variables or secure secret management.

Security

Every byte to the model is scanned and redacted first. All content (local files, GitHub/npm responses, errors, tool output) passes through the Rust engine's secret scanner on the way in and out, so secrets never reach the LLM. Identical under MCP and CLI.

• Secret redaction, in and out. 300+ provider credential patterns (AWS, Azure, GCP, GitHub, OpenAI, Anthropic, Stripe, Slack, 1Password, and more) plus generic JWTs, PEM/private keys, bearer tokens, database connection strings, and high-entropy strings. Masked values surface a redaction warning so the agent knows.

• Content sanitized at the source. Local reads (localGetFileContent, ripgrep, structural search, binary, file discovery, structure) and external fetches (GitHub code/files, npm) are scanned as they are read, not only at the boundary.

• Path safety. Relative inputs resolve from WORKSPACE_ROOT / config / cwd, then local reads are bounded to the engine's allowed roots (home by default, plus ALLOWED_PATHS and Octocode-registered roots). Symlinks are resolved and the real target is re-validated, so a link cannot escape into a blocked location.

• Sensitive files blocked by default. Reads of known secret-bearing files and folders return a redacted error instead of contents: keys/certs, .env*, .npmrc/.netrc, cloud/infra credentials (.aws/, .kube/, *.tfstate), .git/, browser logins, OS keychains, and wallets. Full list in SECURITY.md.

• Command safety. Normal local search runs in-process inside octocode-engine. External helpers are fixed per lane, command/argument allowlisted, and run via spawn with argument arrays: no shell strings, no injection.

• Schema validation runs before any tool executes; untrusted input size and shape are bounded.

• Credentials. GitHub auth via env tokens, AES-256-GCM-encrypted on-disk OAuth, or the gh CLI; tokens are never logged.

Full security model, pipeline, and threat coverage: SECURITY.md. Related: Configuration & Authentication · Credentials

Language Support

Four code-intelligence axes; three are native to the Rust engine and need no external tooling:

📋 Full support matrix: every extension with its exact AST, signature, LSP, and minify capability lives in the Full format support matrix.

Skills

Agent Skills are a lightweight, open format for extending AI agent capabilities. Browse and install on skills.sh/bgauryy/octocode-mcp

13 skills under skills/, bundled in the octocode package. Each is a lean SKILL.md that loads references only when needed, so they compose. Start with ⭐ Research for evidence-first code work.

npx octocode skill list
npx octocode skill install octocode-research --platform pi
npx octocode skill check --json
npx octocode skill help

Core Research & Extraction

Planning & Architecture

Evaluation & Review

Agent Orchestration

Web automation workflow: octocode-scraping performs the safe static pass first (fetch/crawl/extract → local corpus → graph v2). When the graph exposes dynamic actions or static output is blocked/thin, octocode-chrome-devtools validates live actionability, cookies/storage, network/HAR bodies, screenshots, or auth-gated state; discovered URLs/data/artifacts can be fed back into the scraping corpus for continued proof.

Architecture

A yarn-workspaces monorepo. The MCP server and the CLI are thin front-ends over one shared TypeScript tool core, which delegates every CPU-heavy path to a single Rust engine (compiled via napi-rs to prebuilt .node binaries). One tool catalog, one security layer, one response shaper, reached two ways.

graph LR
    CLI["octocode<br/>CLI"]
    MCP["octocode-mcp<br/>MCP server, stdio"]
    VSC["VS Code extension<br/>OAuth + install"]
    CORE["octocode-tools-core<br/>tools, GitHub client, auth, pagination, security bridge"]
    ENGINE["octocode-engine (Rust)<br/>secrets, minify, AST, signatures, ripgrep/diff/YAML, LSP"]
    EXT["GitHub API, local FS + ripgrep, language servers"]

    CLI --> CORE
    MCP --> CORE
    VSC -. starts .-> MCP
    CORE --> ENGINE
    CORE --> EXT
    ENGINE --> EXT

    style ENGINE fill:#1a1a2e,stroke:#e75d2a,color:#fff

Request flow is identical whether a call arrives over MCP or the CLI:

client → sanitize inputs (Rust) → run tool (GitHub / FS / LSP) → sanitize + YAML-serialize + paginate (Rust) → result + next-step hints

One Rust engine owns secret detection, sanitization, path/command validation, minification (70+ languages), signature extraction, structural AST search, ripgrep parsing, diff filtering, YAML serialization, and LSP, so the Node event loop stays unblocked and there is no duplicate native loader. It ships prebuilt for darwin (arm64/x64), linux (arm64/x64, gnu + musl), and win32-x64; no Rust toolchain is needed at runtime.

Packages

packages/octocode-benchmark (private, not published) holds benchmark methodology, evals, and run artifacts - see Documentation.

Documentation

Website: octocode.ai · Product docs: github.com/bgauryy/octocode/tree/main/docs. This section is the canonical documentation index; benchmark methodology, evals, and run artifacts live in packages/octocode-benchmark.

Troubleshooting

Node.js or Environment Issues? Run the built-in doctor command to check your environment:

npx node-doctor check --json

Common Pitfalls:

• GitHub Auth Failures: Ensure your Personal Access Token (PAT) has the repo and read:user scopes. If using the CLI, run npx octocode auth login to refresh.

• MCP Connection Issues: If your AI assistant (like Cursor or Windsurf) fails to connect, ensure you have run npx octocode auth login in your terminal first, or explicitly pass your OCTOCODE_TOKEN in the MCP env configuration.

• Native Engine Errors: Octocode uses a prebuilt Rust engine. If it fails to load on Linux, ensure your system has glibc or musl compatibility. On macOS/Windows, ensure you are on a supported architecture (x64 or arm64).

Agent Workflows

Recommended dev mode: Pi + Octocode

Pi is a fast, local-first coding agent whose stated philosophy is "CLI tools with READMEs (Skills) over MCP." Pairing it with Octocode gives a lean, evidence-driven dev loop - Pi edits, Octocode researches. Two routes, pick by how much surface you need:

• Skill route - recommended, leanest. Drop the octocode-research skill into Pi's global skills dir. It drives the Octocode CLI directly - no MCP transport, minimal token overhead - and Pi auto-discovers it:

  npx octocode skill install octocode-research --platform pi

• Adapter route - full tool surface. Install pi-mcp-adapter to expose Octocode MCP tools behind a single ~200-token proxy tool, so servers stay disconnected until a tool is actually called. Enable clone tools with ENABLE_CLONE=true.

Research-driven loop

Most agent failures happen before the edit: guessing who owns a behavior, trusting a snippet without reading the source, editing before proving blast radius. Run a cheaper loop instead: orient with trees, search, read exact evidence, use AST/LSP when identity matters, then patch and verify. The host edits, Octocode is the map, and skills encode the habit.

The Manifest

"Code is Truth, but Context is the Map." Read the Manifest of Octocode for Research Driven Development to understand the philosophy behind Octocode.