Octocode - Agentic Research Platform

Evidence-first code research for AI agents and developers.

Evidence from your local workspace and external sources (GitHub repos, PRs, npm). One toolset: ripgrep + AST search, trees, precise reads, and LSP - 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
• What You Can Do
• Built for Research (Benchmarks)
• Tools
• MCP
• CLI
• Configuration
• Authentication Methods
• Security
• Language Support
• Skills
• Architecture
• Documentation
• Troubleshooting

Quick Start

Prerequisites: Node.js v18+

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. The same engine and tools run identically either way.

🖥️ CLI - research straight from your terminal:

npx octocode

🤖 MCP - one-click install:

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

Any other client: npx octocode install

See it in action

Search your local codebase and see the minified, token-efficient output:

npx octocode tools localSearchCode --queries '{"query": "authenticate"}' --yaml

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

➡️ Learn more at octocode.ai.

Why Octocode

Agents write better code from evidence than from assumptions. Octocode turns guess-driven work into research-driven work. Before an agent changes, reviews, or explains code, it gathers real evidence from your local workspace and from GitHub repositories, pull requests, and npm packages, then hands it back as compact, citable context. Code is truth; context is the map.

Most tools cover one slice: searching the web, or grepping your repo. Octocode covers the whole research flow, end to end:

• Built for scale. In organizations with thousands of repositories and endless code, Octocode is the solution: spot a pattern in one repo, follow it through the pull request that introduced it, then trace the same shape across other repos and your own files without leaving the conversation. Clone any repo and study it locally, on any machine.
• Smart GitHub workflows. Parallel bulk queries and built-in next-step hints keep the agent on the cheapest path: search broadly, read narrowly, trace semantically. Each result points to the natural follow-up.
• No GitHub required. Even without GitHub, clone any repository locally and point Octocode's local tools (search, structural AST, LSP, content) at it for the same evidence-first research.
• Reads the shape, not the noise. Code is minified and skeletonized on the fly across 70+ languages, so an agent grasps a 100 KB file in a few hundred tokens instead of spending its context on boilerplate.
• Fast and self-contained. Search, parsing, semantic navigation, and redaction run in one prebuilt Rust engine: quick on a laptop or a mega-repo, with no extra toolchain to install.
• Safe by default. Every byte returned to the model is scanned and secrets redacted first (see Security).

What You Can Do

Octocode is useful whenever the next coding step depends on finding and proving context, not guessing it.

See Quick Start to install in your terminal or AI assistant.

Built for Research (Benchmarks)

Octocode is built for research - and it's measured on it. Across four independent, blind-graded runs against the leading GitHub-research CLIs (gh alone, gh + rtk, and gh + Headroom), the same runner model answered the same 17 real GitHub research questions with each tool. At equal or better correctness, Octocode pulled 1.4×–5.8× less context into the model - lower is better:

gh alone  (17 questions)
  octocode  ████████████████··············  152,710 chars
  gh        ██████████████████████████████  286,812 chars   → gh pulls 1.9× more

gh + rtk (by-hand pass)  (17 questions)
  octocode  █████████████████████·········  168,773 chars
  gh+rtk    ██████████████████████████████  242,691 chars   → gh+rtk pulls 1.4× more

gh + rtk (orchestrated: 2 blind runners + grader)  (17 questions)
  octocode  ███████████···················  395,644 chars
  gh+rtk    ██████████████████████████████  1,040,783 chars   → gh+rtk pulls 2.6× more

gh + Headroom compression (orchestrated)  (15 questions)
  octocode  █████·························  203,708 chars
  gh+hr     ██████████████████████████████  1,180,822 chars   → gh+hr pulls 5.8× more

Correctness was a tie or an Octocode edge in every run - gh 9.94/9.94, gh+rtk 10.0/10.0 (ties); orchestrated 9.18 → 9.38; Headroom 9.07 → 9.67.

Measured in characters of raw CLI output pulled into context (~4 chars ≈ 1 token) - the honest, measured number, not a self-report. Correctness graded first; leaner only wins at equal correctness.

Why it's leaner: gh and friends have no region read - to inspect one symbol they fetch the whole file, tree, or diff; Octocode reads the region that answers the question. Compression (Headroom) shrinks output only after it's fetched, so it can't offset over-fetching what you never needed.

A note on truncation: most context-shrinking tools truncate output blind to the question - for example, silently cutting a multi-file gh pr diff, hiding half the changes and forcing a full re-fetch. In research flows the answer often lives in those connections across files, so Octocode instead tries to fetch just what the request needs, rather than trimming after the fact.

Use the right tool for the job: for a quick check - a single small object, a flat list, a yes/no where you know where to look - gh's bare output is leaner, and the benchmark shows it. For actual research - multi-hop questions whose answers live inside large files, trees, and diffs - Octocode wins, because that's what it was built for.

📊 Full write-up - per-question visual charts, the three baselines, and honest caveats: Benchmark Summary. Every run is reproducible by hand via the octocode-benchmark skill - isolated runners, a blind grader, no harness.

Tools

13 always-on tools (same on MCP and CLI). Local tools on by default (ENABLE_LOCAL=false to disable). Three opt-ins: ghCloneRepo (MCP opt-in ENABLE_CLONE=true, CLI on by default), ghListReleases (ENABLE_RELEASES=true), and ghSearchDiscussions (ENABLE_DISCUSSIONS=true). 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. Pick the package that matches the version you want:

New Octocode (Rust-powered engine) - use @octocodeai/mcp:

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

Classic octocode-mcp - use 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.

npx octocode auth login   # authenticate once
npx octocode status       # verify setup
npx octocode --help       # 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

The Scope column shows where a setting applies: Both, or MCP (the CLI ignores it).

Local defaults on; clone differs by surface. Both CLI and MCP default local tools on; set ENABLE_LOCAL=false to disable them. The CLI defaults clone on, while the MCP server requires ENABLE_CLONE=true.

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 that reaches the model is scanned and redacted first. All content (local files, GitHub and npm responses, error messages, and tool outputs) passes through the Rust engine's secret scanner on the way in (tool inputs) and on the way out (results), so secrets never reach the LLM. The same enforcement runs identically under MCP and the 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 and directories are blocked by default. Octocode refuses to read known secret-bearing files and folders wherever they live, returning a redacted error instead of contents. Blocked patterns include:
  • Keys and certs: *.pem, *.key, *.crt/*.cer/*.csr, *.p12/*.pfx/*.jks/*.keystore, and SSH keys (id_rsa, *_ed25519, authorized_keys, known_hosts, .ssh/).
  • Credentials and tokens: .env / .env.*, .netrc, .npmrc, .pgpass, .git-credentials, *_token / .token, client_secret*.json, *service-account*.json, auth.json, .htpasswd.
  • Cloud and infra: .aws/, .azure/, .config/gcloud/, .kube/ / kubeconfig, .docker/, .terraform/ and *.tfstate.
  • OS and app secret stores: .git/, secrets/, private/, browser login data (Chrome/Firefox), OS keychains, password managers (*.kdbx), shell history files, and crypto wallets.
• 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: Authentication · Configuration · 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, machine-generated from the shipped binary, lives in the Full format support matrix (151 extensions: 61 AST, 47 signature, 32 LSP, 90 minify-only). Regenerate or verify with yarn workspace @octocodeai/octocode-benchmark matrix:check.

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. Every skill shares one architecture - a lean SKILL.md lobby with hard gates, references loaded only when a step needs them, and cross-skill routes - 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 start before implementation: the agent guesses the owner of a behavior, trusts a snippet without reading the exact source, or edits before proving blast radius. Prefer a cheaper loop first: orient with trees and discovery output, search with Octocode, read exact evidence, use AST/LSP when identity matters, then patch and verify.

That shape keeps the editing surface small while preserving context for what matters: file anchors, symbols, call paths, PR/history evidence, package sources, and the verification command that proves the change. In short, 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.