Octocode

Octocode：Agent 研究平台

面向 AI Agent 和开发者、以证据为先的代码研究工具。

Octocode 使用一套工具研究本地代码和外部代码（GitHub 仓库、PR、npm）：ripgrep + AST 搜索、代码树、精准读取和 LSP。你可以将它用作 CLI 或 MCP 服务；其底层由 Rust 引擎驱动，可在单个文件或超大型仓库中快速获取高效利用 token 的结果。

目录

• 快速开始
• 为什么选择 Octocode
• 专为研究打造（基准测试）
• 工具
• MCP
• CLI
• 配置
• 身份验证方式
• 安全性
• 语言支持
• 技能
• 架构
• 文档
• 故障排除
• Agent 工作流

快速开始

前置条件： Node.js 20.12+

1. 使用 npx 运行 Octocode CLI

npx octocode --help

2. 使用 GitHub 进行身份验证 - 可选，但可解锁私有仓库并提高 API 速率限制：

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

3. 选择界面。 两者使用相同的工具和 Rust 引擎。（CLI 默认启用克隆，MCP 则需选择启用。）

🖥️ CLI - 直接在终端中进行研究：

npx octocode

🤖 MCP - 一键安装：

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

其他客户端： npx octocode install

将其用作 MCP 服务

添加到 MCP 客户端配置中（或使用上方的一键安装）：

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

在 env 下添加 GitHub 令牌和选项（参见配置）。

将其用作适合 Agent 的 CLI

运行 npx octocode，Agent 就会知道如何处理。直接运行命令会显示内置用法和完整的工具目录，因此任何编码 Agent 都能开箱即用，无需 MCP 客户端或额外配置。

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

每个 MCP 工具也都是普通命令：输入 JSON，输出节省令牌的 YAML。本地路径会路由到本地工具；owner/repo[/path] 会路由到 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) {"

了解更多信息，请访问 octocode.ai。

为什么选择 Octocode

基于证据编写代码的 Agent，比靠猜测编写得更好。Octocode 通过一个流程研究两个领域：你的本地代码，以及 GitHub 和 npm 上的外部代码，并在 Agent 修改、审查或解释代码之前，提供精简且可引用的上下文。代码即真相；上下文是地图。

大多数工具只处理其中一环（网页搜索，或 grep 你的代码库），然后返回一整块固定内容。Octocode 覆盖完整流程，并让Agent 决定下一步需要哪些数据：

• 由 Agent 驱动的高效流程。 Octocode 不会一次性倾倒数据，而是将低成本步骤串联成优化后的研究流程：先广泛搜索代码，再只获取精确匹配的行／区域，并通过智能分页和开箱即用的精简处理，避免模型获取过多信息。每个结果都会附带后续步骤提示，引导你以最低成本继续探索。
• 适用于大型单体代码库。 在一个代码库中发现某种模式后，可找到引入它的 PR，再追踪它在其他代码库和你自己的文件中的应用，无需离开聊天界面。克隆任意代码库并在本地研究。
• 智能 GitHub 流程。 并行批量查询代码、PR、提交、议题和代码库，始终遵循相同的原则：先广泛搜索，再精确阅读，最后按语义追踪。
• 无需 GitHub 也能使用。 克隆任意代码库，并将本地工具（搜索、AST、LSP、内容）指向它，即可使用相同的证据优先流程。
• 读取结构，而非噪声。 对 70 多种语言即时精简／提取骨架：100 KB 的文件只需几百个 token，而不是铺天盖地的样板代码。
• 快速且独立运行。 搜索、解析、导航和脱敏都由一个预构建的Rust 引擎完成：无论在笔记本电脑还是超大型代码库中都能快速运行，无需安装额外内容。
• 默认安全。 发送给模型的每个字节都会先经过扫描并进行机密信息脱敏（参见安全性）。

你可以做什么（在下一步需要可靠上下文而非猜测时）：

专为研究打造（基准测试）

一项盲测对比，测试的是以研究为导向的工作流，而非简单查询（多跳跟踪、依赖关系／调用图链、提交范围、影响范围、跨仓库 PR 审查）。

工作原理：30 个 GitHub 问题 × 3 轮；使用相同问题对比 Octocode、gh、gh+Headroom 和 gh+RTK（只有 CLI 不同）。盲审评员（gpt-5.5）对正确性进行评分；指标是经过模型的字符数，根据经过检测的日志统计（字符数，而非 token 数）。**结果：**在正确性几乎持平的情况下，在本地构建的主要测试中，Octocode 的回答比纯 gh 少约 2.0× 字符，比 gh+Headroom 少约 2.6×，比 gh+RTK 少约 3.2×。

▶ 打开交互式报告 · 运行／方法 · 问题 · 所有报告

工具

**完整目录中有 17 个工具。**注册的工具数量取决于使用场景和 所设置的标志：

在 MCP 上，ghListReleases 和 ghSearchDiscussions 需要两个设置，而不是一个： ENABLE_RELEASES=1 或 ENABLE_DISCUSSIONS=1 会将工具加入目录，而 ENABLE_TOOLS="ghListReleases,ghSearchDiscussions" 会注册工具。单独设置其中 任一项都不会注册工具，因为这两个工具的 isDefault: false，而 MCP 注册筛选器只允许默认工具或明确列入允许列表的工具。 CLI 只需要 ENABLE_RELEASES 和 ENABLE_DISCUSSIONS 标志。ENABLE_LOCAL 和 ENABLE_CLONE 接受 true 或 1；ENABLE_RELEASES 和 ENABLE_DISCUSSIONS 也接受 yes 和 on。 标志：配置。

Token 调节项。concise:true 会返回仅包含路径／标题的列表。minify 控制文件读取密度：symbols = 带行号的骨架，standard = 去除注释／空行（默认），none = 精确字节。

GitHub 工具

本地工具

包搜索

LSP

每个工具的完整架构、字段和示例请参见 docs/OCTOCODE_TOOLS.md（链接位于文档下）。

MCP

MCP 服务通过 stdio 将 Octocode 工具目录直接提供给你的 AI 助手。

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

手动配置

使用 octocode-mcp 添加到你的 MCP 客户端配置中：

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

在 env 下添加 GitHub 令牌和选项——请参见身份验证和配置。

CLI

使用相同的研究引擎，无需 MCP 客户端。本地路径会路由到本地工具；owner/repo[/path] 会路由到 GitHub。使用 npx octocode auth login 完成一次身份验证（请参见身份验证）；运行 npx octocode --help 查看完整用法。

命令

工具命令

更多命令

• 缓存和克隆 — npx octocode clone、npx octocode cache fetch|status|clear
• 技能 — npx octocode skill list|install|check|info|remove，用于管理捆绑的 Octocode 技能
• 语言服务器 — npx octocode lsp-server list|install|status|uninstall|clean
• 设置和内省 — npx octocode install、npx octocode auth、npx octocode status、npx octocode context

完整语法、标志和退出代码：Octocode CLI 指南

配置

所有设置都是可选的；Octocode 使用合理的默认值运行。设置按优先级从三个来源解析：

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

1. MCP / 环境变量（最高优先级）：按客户端或项目设置，在 MCP 配置的 env 中或 Shell 中设置。
2. 全局配置：<octocode-home>/.octocoderc，供CLI 和 MCP 服务共同读取的整台机器默认设置。
3. 内置默认值：两者都未设置时使用。

Octocode 主目录（<octocode-home>）存放全局配置、加密凭据、会话、统计数据和临时物化缓存。在所有平台上，它都是操作系统主目录下的 .octocode — macOS 和 Linux 上为 ~/.octocode，Windows 上为 %USERPROFILE%\.octocode。使用 OCTOCODE_HOME 覆盖此目录。

将值设为 MCP env 条目（按客户端设置；优先级高于 .octocoderc），或在 <octocode-home>/.octocoderc 中全局设置（带注释的 JSON）。切勿将令牌放入 .octocoderc — 请使用 env 或 npx octocode auth login。

常用设置

最常用的设置（除非另有说明，同时适用于 CLI 和 MCP）：

OCTOCODE_HOME、GitHub Enterprise（GITHUB_API_URL）、MCP 工具许可列表（TOOLS_TO_RUN/ENABLE_TOOLS/DISABLE_TOOLS）以及网络超时和重试设置：请参阅配置参考。

配置示例

~/.octocode/.octocoderc：

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

项目级覆盖设置和自定义 LSP 服务器位于工作区的 .octocode/ 文件夹中。有关完整的 .octocoderc 架构、可直接复制的示例、克隆缓存调优、GitHub Enterprise 设置和优先级详情，请参阅配置参考。

身份验证方式

GitHub 支持的工具需要身份验证。任选一种方式即可。完整详情请参阅：身份验证设置。

选项 1：Octocode CLI（推荐）

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

交互式登录可让你选择 Octocode 浏览器 OAuth 或 gh auth login。Octocode OAuth 凭据会加密后存储在磁盘上。

选项 2：GitHub CLI（同样支持）

gh auth login

Octocode 会自动读取 gh 令牌 — 无需进一步配置。

选项 3：个人访问令牌（也支持）

在 shell 中设置 OCTOCODE_TOKEN、GH_TOKEN 或 GITHUB_TOKEN。所需权限范围：repo、read:user、read:org。

在 github.com/settings/tokens 创建令牌。

注意： 切勿将令牌提交到版本控制中。请使用环境变量或安全的机密管理方式。

安全性

发送给模型的每个字节都会先经过扫描和脱敏。 所有内容在传入和传出时都会经过 Rust 引擎的机密扫描器，因此机密不会到达模型。这涵盖本地文件、GitHub 和 npm 响应、错误以及工具输出。MCP 和命令行下的行为完全一致。

• 输入和输出均会进行机密脱敏。 涵盖 300 多种服务商凭据模式（AWS、Azure、GCP、GitHub、OpenAI、Anthropic、Stripe、Slack、1Password 等），以及通用 JWT、PEM／私钥、Bearer 令牌、数据库连接字符串和高熵字符串。脱敏后的值会显示警告，让 Agent 知晓。
• 在内容源头进行清理。 本地读取（localGetFileContent、ripgrep、结构化搜索、二进制文件、文件发现、结构）和外部获取（GitHub 代码／文件、npm）会在读取时进行扫描，而不仅仅是在边界处扫描。
• 路径安全。 相对路径输入会从 WORKSPACE_ROOT／配置／cwd 解析，然后本地读取范围会限制在引擎允许的根目录内（默认是主目录，加上 ALLOWED_PATHS 和 Octocode 注册的根目录）。符号链接会被解析，并对真实目标重新验证，因此链接无法绕过限制，指向被阻止的位置。
• 默认阻止读取敏感文件。 读取已知包含机密的文件和文件夹时，会返回脱敏错误而非内容：密钥／证书、.env*、.npmrc／.netrc、云／基础设施凭据（.aws/、.kube/、*.tfstate）、.git/、浏览器登录信息、操作系统密钥链和钱包。完整列表见 SECURITY.md。
• 命令安全。 普通本地搜索在 octocode-engine 进程内运行。外部辅助工具按执行通道固定，并对命令／参数进行允许列表检查，通过 spawn 和参数数组运行：不使用 shell 字符串，不存在注入风险。
• 任何工具执行前都会进行架构验证；不可信输入的大小和格式均受到限制。
• 凭据。 GitHub 身份验证通过环境变量令牌、使用 AES-256-GCM 加密并存储在磁盘上的 OAuth 凭据，或 gh CLI 进行；令牌绝不会被记录到日志中。

完整的安全模型、处理流程和威胁覆盖范围：SECURITY.md。 相关内容：配置和身份验证 · 凭据

语言支持

四个代码智能维度；其中三个由 Rust 引擎原生支持，无需外部工具：

📋 **完整支持矩阵：**每种扩展名对应的确切 AST、签名、LSP 和精简能力，请参阅 完整格式支持矩阵。

技能

Agent Skills 是一种轻量、开放的格式，用于扩展 AI Agent 的能力。 在 skills.sh/bgauryy/octocode-mcp 浏览和安装

skills/ 下共有 13 项技能，打包在 octocode 包中。每项技能都是精简的 SKILL.md，仅在需要时加载参考资料，因此可以组合使用。可从 ⭐ Research 开始，进行以证据为先的代码工作。

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

核心研究与提取

规划与架构

评估与审查

Agent 编排

Web 自动化工作流： octocode-scraping 会先执行安全的静态处理（获取/爬取/提取 → 本地语料库 → graph v2）。当图谱显示存在动态操作，或静态输出受阻/内容不足时，octocode-chrome-devtools 会验证实时可操作性、Cookie/存储、网络/HAR 正文、屏幕截图或受身份验证保护的状态；发现的 URL/数据/产物可以反馈到抓取语料库，继续提供证据。

架构

这是一个 yarn 工作区单体仓库。MCP 服务和 CLI 是精简的前端，共用一个 TypeScript 工具核心；该核心将所有 CPU 密集型路径委托给单个 Rust 引擎（通过 napi-rs 编译为预构建的 .node 二进制文件）。一份工具目录，一个安全层，一个响应整形器，两种调用方式。

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

请求流程完全相同，无论调用通过 MCP 还是 CLI 进入：

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

单个 Rust 引擎负责机密检测、清理、路径和命令验证、精简（70 多种语言）、签名提取、结构化 AST 搜索、ripgrep 解析、差异过滤、YAML 序列化和 LSP。因此，Node 事件循环不会受阻，也不需要重复的原生加载器。该引擎提供适用于 darwin（arm64/x64）、linux（arm64/x64，gnu 和 musl）和 win32-x64 的预构建版本；运行时不需要 Rust 工具链。

软件包

packages/octocode-benchmark（私有，未发布）包含基准测试方法、评估和运行产物 - 请参阅文档。

文档

网站：octocode.ai · 产品文档：github.com/bgauryy/octocode/tree/main/docs。本节是权威文档索引；基准测试方法、评测和运行产物位于 packages/octocode-benchmark。

故障排查

Node.js 或环境问题？ 运行内置的 doctor 命令来检查环境：

npx node-doctor

常见问题：

• **GitHub 身份验证失败：**确保你的 Personal Access Token（PAT）具有 repo 和 read:user 权限范围。如果使用 CLI，请运行 npx octocode auth login 以刷新。
• **MCP 连接问题：**如果 AI 助手（如 Cursor 或 Windsurf）无法连接，请确保先在终端运行 npx octocode auth login，或在 MCP env 配置中显式传入 OCTOCODE_TOKEN。
• **原生引擎错误：**Octocode 使用预构建的 Rust 引擎。如果它在 Linux 上无法加载，请确保系统兼容 glibc 或 musl。在 macOS/Windows 上，请确保使用受支持的架构（x64 或 arm64）。

Agent 工作流

推荐的开发模式：Pi + Octocode

Pi 是一款快速、以本地优先的编码 Agent，其明确的理念是 “使用带有 README 的 CLI 工具（技能），而不是 MCP。” 将它与 Octocode 搭配使用，可构建精简、以证据为依据的开发循环——Pi 负责编辑，Octocode 负责研究。有两种方式，可根据所需功能范围选择：

• 技能方式 — 推荐，最精简。 将 octocode-research 技能放入 Pi 的全局技能目录。它会直接驱动 Octocode CLI——无需 MCP 传输，Token 开销极低——而且 Pi 会自动发现它：

  npx octocode skill install octocode-research --platform pi
  

• 适配器方式 — 完整工具功能。 安装 pi-mcp-adapter，通过单个约 200 Token 的代理工具提供 Octocode MCP 工具，这样服务器会保持断开状态，直到调用工具。使用 ENABLE_CLONE=true 启用克隆工具。

以研究为驱动的循环

大多数 Agent 失败都发生在编辑之前：猜测某项行为由谁负责，不读源代码就相信代码片段，还未确认影响范围就开始编辑。改用成本更低的循环：通过目录树确定方向，搜索，阅读确切证据，在需要确认身份时使用 AST/LSP，然后进行修补并验证。宿主负责编辑，Octocode 提供地图，技能则将这种习惯编码下来。

宣言

“代码即真相，上下文即地图。” 阅读 Octocode 的研究驱动开发宣言，了解 Octocode 背后的理念。