codexa

Codexa

理解代码。查看变更可能影响什么。核查证据。

Codexa 帮助开发者和 AI 编码助手在处理代码仓库时获取更多上下文、减少猜测。它会构建代码的本地地图，将文件与其依赖项和测试关联起来，并针对拟议和已完成的变更生成易读的报告。

可以把它看作项目地图和变更检查清单。操作者——无论是人还是编码助手——仍然掌控全局。Codexa 会指出：开卡车过桥前，你可能需要检查的地方。

你可以在终端中使用它，也可以搭配 Codex、Claude Code 或其他兼容的编码助手使用，或者在 GitHub Actions 中用它辅助审查拉取请求。核心功能无需 API 密钥、托管账户或数据库。Codexa 免费且采用 MIT 许可证；你的 AI 助手和任何可选托管服务则有各自的要求和费用。

开始使用 · 连接助手 · 日常使用 · GitHub 审查 · 故障排除 · 完整参考

维护者预期： Codexa 是一个由个人利用业余时间维护的专注型项目。回复可能需要几天到几周。提交 PR 前，请先讨论较大的变更；请参阅贡献指南。

它到底能做什么？

你的问题	Codexa 能提供什么
“这个行为在哪里实现？”	相关文件、函数和精确的文本匹配结果，并在有帮助时提供相关代码。
“如果我们修改这个，可能会有什么问题？”	一张关联代码和测试的地图，显示可能受到影响的部分。
“我们应该测试什么？”	根据变更文件和已知关联关系提出的检查建议。
“工作是否遵循了计划？”	对比已保存的计划与实际修改，包括意料之外的变更。
“这次交接有哪些证据支持？”	一张证明卡片：总结计划、验证证据和仍待解决的问题。
“这个拉取请求改了什么？”	一份变更回执：涵盖已提交的变更、可能的影响和审查指南。

例如，修改登录超时时间可能影响的不只是一个数字。Codexa 可以帮助你找到设置项、识别使用它的代码、建议相关测试，并标记超出约定范围的修改。它的发现取决于它在你的代码仓库中能够读取和关联的内容；它无法预测所有运行时行为。

Codexa 提供上下文和检查功能。实际修改由你的编辑器或助手完成，而项目测试则用于确认行为是否正常。看起来全绿的报告是有用的证据，但不是护身符。

快速开始

你需要 Node.js 22 或更高版本、npm（随 Node.js 提供）、Git，以及一个本地 Git 仓库——也就是你想要检查的项目文件夹。使用终端命令时，无需克隆 Codexa 本身，也无需安装 AI 助手。

1. 安装

在终端中运行以下命令：

node --version
git --version
npm install -g @mirnoorata/codexa
codexa --version

2. 在你的项目中试用

将 /path/to/project 替换为仓库的实际文件夹路径。如果路径中包含空格，请将其括起来。在以下示例中，. 表示“此文件夹”。

cd /path/to/project
codexa index .
codexa repo-map .

index 会读取仓库并创建本地映射。repo-map 会显示排名靠前的文件和模块。这种仅使用终端的方式无需设置助手。

提出一个与你的项目相关的问题：

codexa search . --query "login timeout"

这是一个示例查询，并非内置演示：结果取决于你的代码。若要持续使用，请遵循生成文件指南，并在下方选择你的助手设置。

不想全局安装？ 在命令前加上 npx -y @mirnoorata/codexa，例如 npx -y @mirnoorata/codexa index /path/to/project。npm 可能会下载该软件包；默认情况下，索引过程本身会在本地运行。

连接你的编码助手

Codexa 使用 MCP（Model Context Protocol），这是一种让 AI 助手能够向外部工具获取信息的连接方式。助手运行模型；Codexa 提供仓库上下文。请单独安装并登录你选择的助手。

Codex

在你的项目文件夹中：

codexa init . --agents-md
codexa session-start .

这会创建索引、将 Codexa 服务添加到 .codex/config.toml、安装 Codex 启动和编辑钩子，并向 AGENTS.md 添加一个小型托管工作流区块。如果你想自行管理 Agent 指令，请省略 --agents-md。如果 Codexa 插件已提供 MCP 连接，请避免为同一仓库注册第二个服务。

在 Codex 中打开或重新加载同一项目，并在提示时信任该项目。项目范围的 MCP 配置仅会对受信任的项目加载。在 Codex CLI 中，/mcp 会显示活动连接；请参阅官方 MCP 设置指南。

成功的 session-start 检查可确认可观测的设置和索引状态；但无法证明已运行的助手已经加载该服务。

**Windows：**使用 codexa init . --agents-md --no-hooks 进行原生 Windows 的纯 MCP 设置。生成的 shell 钩子需要 POSIX 环境，例如 WSL。macOS 和 Linux 可以使用上述标准命令。

Claude Code

若要使用最简单的连接方式：

codexa init . --claude --claude-md --no-hooks
codexa session-start .

这还会将服务条目写入 .mcp.json，并将工作流指南写入 CLAUDE.md。在该仓库中重启 Claude Code，并在提示时批准项目 MCP 服务。--no-hooks 会禁用 Codexa 的 Codex 钩子；此设置会提供 Claude 工具和指令，但不包含 Claude 钩子或斜杠命令。

想要自动启动指南、审查钩子以及 /codexa-plan 和 /codexa-review 等命令？请使用内置的 Claude Code 插件。请在该插件和上述 .mcp.json 连接方式中二选一，以避免重复的服务。

其他 MCP 客户端

在客户端的 MCP 设置中配置本地命令服务：

{
  "mcpServers": {
    "codexa": {
      "command": "codexa",
      "args": ["serve", "/path/to/project", "--auto-refresh"]
    }
  }
}

替换路径，并根据你的客户端调整外层配置格式。客户端必须能够找到 codexa 并访问仓库。客户端会启动该服务；serve 不是交互式聊天命令。

全新安装会提供三个工具：search、change_plan 和 capabilities。这是有意精简的菜单：capabilities 可用于访问其余操作。如果你的客户端需要直接列出所有操作，请在 init 或 serve 中使用 --tools full。

默认连接使用本地进程。可选的 HTTP 传输仅绑定到本机；Codexa 不提供公共远程服务。

日常工作流

在 Codexa 能消除不确定性时使用它。 对已知文件进行小修复，可能只需直接检查并运行项目的常规测试。改个逗号不必走繁琐流程。涉及多个文件的更改则更适合先规划并审查。

对于编码助手，一个实用的请求是：

找出处理登录超时的位置。如果目标或影响不明确，请使用 Codexa。在进行实质性编辑之前，先保存更改计划。完成更改，运行相关检查，并根据计划审查结果。告诉我还有哪些内容未经验证。

你也可以自行运行此工作流。此示例假设你的代码库中有 src/auth.ts；请替换为实际文件和任务：

codexa change-plan . --task "Adjust the login timeout" --file src/auth.ts --task-id login-timeout --save-snapshot

阅读计划、进行编辑，并运行适合你项目的检查。然后在提交之前，趁编辑内容仍作为本地更改可见时，审查工作：

codexa post-edit-review . --task-id login-timeout

使用 --ran-command 报告你实际运行过的检查。例如，仅当 npm test 是项目中的实际检查且你确实运行了它时：

codexa post-edit-review . --task-id login-timeout --ran-command "npm test"

此标志会记录一项声明，但不会执行命令。Codexa 会检查所报告的命令是否可能覆盖相关工作。会隐藏失败的命令（例如 npm test || true）无法获得认可。Codexa 无法检测完全捏造的报告。

如需正式交接，codexa prove . --task-id login-timeout 会汇总已保存的计划、可用证据和尚未解决的差距。若交接需要实际命令报告或选定的验证材料，请一并提供。

启动和编辑钩子可以减少手动操作，但它们的审查不能取代基于实际测试证据进行的最终审查。详细工作流、不变量和重复尝试控制，请参阅参考文档。

一些实用命令

在项目根目录中运行这些命令，并使用你自己的文件名和问题：

命令	用途
codexa search . --query "password reset"	查找切入点。
codexa explain . --file src/auth.ts	检查文件及其关联关系。
codexa impact . --file src/auth.ts	查看更改可能造成的影响。
codexa diff-impact .	检查未提交更改的影响。
codexa test-plan . --diff	获取针对当前编辑的测试建议。
codexa status .	检查索引是否为最新以及解析器错误，不刷新索引。
codexa watch .	在会话期间保持索引更新；按 Ctrl+C 停止。
codexa doctor .	诊断本地设置问题。

大多数上下文命令会自动刷新过期索引。更多选项请使用 codexa --help、codexa <command> --help 或查看命令参考。

审查拉取请求

Codexa 无需 AI 助手即可为已提交的分支生成报告。在该分支的干净检出中，并确保本地有 origin/main：

git fetch origin
codexa review . --base origin/main --head HEAD
codexa review . --base origin/main --head HEAD --format json

如果你的代码库使用不同的基准分支，请替换 origin/main。Codexa 会比较两个分支自共同祖先以来的更改。HEAD 必须与检出的提交一致，索引也必须对应此干净检出。

要在 GitHub Actions 中添加相同的审查：

codexa init . --ci

按照常规拉取请求流程审查并提交生成的 .github/workflows/codexa-review.yml。它会检出拉取请求的确切头部提交，使用只读代码库权限，并将结果写入 Actions 摘要和注释。它不会发布拉取请求评论，也不会运行项目测试。请保留现有 CI。

默认的 observe 模式会报告发现的问题，但不会因此阻止流程。warn 模式会添加警告注释。显式启用 fail 模式时，若本地计划出现偏差、所请求的本地计划不可用，或报告的命令失败，则可能阻止流程。仅建议但未运行的测试不会导致审查失败。无效输入和设置错误在任何模式下都可能导致失败。

有关计划比较、信任限制和 CI 选项，请参阅已提交更改凭据。

会写入仓库的内容？

位置	内容	常见 Git 处理方式
.codex/codebase/	生成的映射、关系和索引。	忽略；每次检出后重新生成。
.codex/cache/	保存的计划、会话笔记、审查状态和可选缓存。	忽略；将本地证据保留为私有内容。
.codex/static-analysis/	导入的或明确生成的扫描器报告。	忽略。
.codex/config.toml, .codex/hooks.json	通过 init 配置的 Codex 连接和钩子。	通常为本地文件；谨慎共享。
.mcp.json	按需配置的 Claude 连接。	共享前检查路径和现有服务。
AGENTS.md, CLAUDE.md	仅在使用相应标志时添加的托管工作流区块。	若对团队有用，则共享。
.codex/policies/	用于证明卡片的可选 JSON 策略。	若体现团队策略，则共享。
.github/workflows/codexa-review.yml	可选的 GitHub Actions 审查。	提交以启用。

将这些生成的路径添加到项目的 .gitignore 中（Codexa 不会替你添加 这些路径）：

.codex/codebase/
.codex/cache/
.codex/static-analysis/

如果 MCP 配置和钩子仅供本机使用，也请忽略这些文件。 如果团队会在 .codex/ 中跟踪策略或设置脚本，请避免忽略整个 .codex/ 目录。提交配置前请检查生成的启动路径； 对于已跟踪的文件，init 支持可移植配置。每位团队成员和新检出的工作副本仍需自行安装并创建索引。

重新运行 init 会刷新 Codexa 管理的配置，并保留其他 MCP 服务条目。可选指令区块仅替换 Codexa 标记之间的区域。--policy-pack 会创建本地证明策略，而不会 替换现有策略文件。有关可移植性和托管文件行为，请参阅 设置参考。

支持、隐私与限制

• **语言支持：**TypeScript、JavaScript 和 Python 支持最深入的 解析。Rust、Go 和 Java 支持较浅层的声明和关系。 其他可识别文件会提取较轻量的信息。外部符号报告可以扩展覆盖范围；这并不意味着能在编译器级别完整理解每种语言。
• **覆盖范围：**Codexa 会读取受支持且 Git 可见的文件，包括未被忽略的 新文件。它会跳过常见的生成文件和依赖项目录，以及大于 2 MiB 的源文件。影响分析最多沿关系追踪三步； 动态行为和大型仓库可能需要进一步调查。
• **隐私：**默认情况下，索引和查询均在本地运行，不调用模型。 返回给 AI 助手的上下文受该助手的数据策略约束。可选的 OpenAI 嵌入会将选定的源文本和查询发送给 OpenAI；可选的 TypeSafe 重排序会将查询和候选源代码片段发送给 TypeSafe。 两者默认均关闭。
• **执行：**MCP 工具可以更新 Codexa 生成的状态，但不会编辑 源文件或运行验证命令。可选的 AutoVerify 会在用户明确配置后，让编辑钩子运行选定的本地检查。 此功能默认关闭，也不是沙盒。
• **证据：**直接观察到的事实、推断出的关系和猜测 使用不同的置信度标签。报告的验证结果会与 AutoVerify 执行区分开来。证明卡片会记录证据和缺口；它 不会认证代码正确或安全。

无需运维 Web 仪表板或托管索引服务。可选的 嵌入、TypeSafe、语言服务器辅助、扫描器导入、会话记忆和 AutoVerify，均记录在 参考文档中。

故障排查

症状	检查内容
找不到 codexa	重新打开终端，检查 npm 的全局可执行文件目录是否在 PATH 中，或使用 npx 替代方案。
安装时构建原生依赖失败	检查 Node.js 是否为 22+；如果没有可用的预构建二进制文件，Tree-sitter 依赖可能需要平台对应的原生构建工具。
助手看不到 Codexa	运行 codexa doctor .，确认仓库路径，然后在助手中重新加载该项目。在 Codex 中，检查项目是否受信任以及 /mcp。
“当前线程 MCP：未经验证”	CLI 无法检查助手的实时连接。请检查助手当前启用的服务列表；仅此一项并不代表安装失败。
索引缺失、过期或不匹配	在实际检出目录中运行 codexa index .。切勿从其他工作树复制索引。
解析器报错或关系缺失	检查 codexa status .、语言支持、被忽略的文件和源文件大小限制。结果降级意味着证据不完整。
无法运行已提交代码审查	解决本地更改，检出指定的提交，然后重建索引。对于未提交的编辑，请使用 post-edit-review。
原生 Windows 上的钩子失败	若仅用于 MCP，请使用 --no-hooks 重新运行 init；若要使用 shell 钩子，请改用 WSL。

更新或移除 Codexa

使用 npm install -g @mirnoorata/codexa@latest 更新，然后在每个仓库中重新运行所选的 init 命令，并重新加载助手连接。使用 --claude 或 --agents-md 等可选 标志来刷新相应集成。普通的 init 会保留现有工具配置；若要切换配置，请使用 --tools core。

要移除 Codexa，请先禁用其服务或插件，并仅删除由它管理的配置项、 钩子和指令块。保留其他工具的设置。 然后运行 npm uninstall -g @mirnoorata/codexa。可以删除生成的索引； 删除 .codex/cache/ 前，请导出所有需要保留的计划或证据。 如果启用了 CI 工作流，也请将其移除。目前没有一键卸载 命令。

Codex 项目工作树和本地设置

Git 工作树是同一仓库的另一个检出目录。请在每个工作树中运行 codexa init， 使其配置和索引与各自的代码相匹配。如果经常创建工作树，请在项目设置中 自动执行这一步。

开发 Codexa 本身时，此仓库包含 Codex 本地 环境和引导脚本，用于安装锁定版本的依赖、构建软件包并验证工作树设置。 这些脚本仅适用于此仓库； 普通用户无需复制。请参阅 工作树和恢复指南。

面向贡献者和感兴趣的读者

Codexa 的引擎使用 TypeScript 编写。其主要路径如下：

Repository → local index → relevant context and change analysis → evidence report

区域	查看位置
安装和命令	src/init.ts、src/cli.ts
文件发现、解析和关系	src/indexer/、src/parser/、src/resolver.ts、src/graph.ts
搜索、计划、审查和测试证据	src/query/、src/prove.ts
助手工具和本地会话状态	src/mcp/、src/session-memory/
主机集成和 CI	plugins/codexa/、integrations/claude-code/、action.yml
验证和打包	tests/、scripts/

从源代码构建：

git clone https://github.com/mirnoorata/codexa.git
cd codexa
npm ci
npm run build
npm link
npm run check

npm link 会在本地提供此检出目录中的 codexa 命令；如果 更愿意使用 node dist/cli.js，则可跳过此步骤。完整的检查流程会构建并进行类型检查、 检查代码规范和公开路径、运行测试，并检查启动上下文 预算。请参阅贡献指南和 架构参考。

公开验证

仓库包含可复现的检索评估和 Agent A/B 测试工具。这些评估衡量的是不同方面：找到有用的上下文，本身并不能证明助手能更快或更好地完成任务。一项已归档的小规模 Agent 试点显示，额外开销并未带来完成任务方面的收益；这并不能证明普遍存在效率提升。结果、日期、注意事项和复现命令均保存在公开验证中。

GitHub 发布记录

GitHub Releases 是当前项目公开可见的时间线。维护者通常使用发布自动化。如明确请求手动运行 npm run release:github，则会生成变更日志式摘要、变更区域摘要、恢复说明和仅向前的 PR 回滚命令。请参阅手动发布参考。

发布自动化

Release Please 使用仓库的 GITHUB_TOKEN 准备版本／变更日志 PR 和 GitHub Releases。这并不意味着每次合并到 main 都会发布 npm：普通变更会先合并，之后才会在发布版本后发布 npm。请参阅发布自动化和公开发布检查清单。

npm 包发布

维护者工作流通过 GitHub Actions 和 npm 可信发布进行发布。它会在明确触发 Release Please 后，或手动发布 GitHub Release（release: published）后运行，而不仅仅是在推送标签后运行。完成发布和安全检查后，工作流会运行：

npm publish --registry https://registry.npmjs.org --access public --tag latest --provenance --ignore-scripts

包用户只需按照上面的安装说明操作。维护者可在发布参考中查找身份验证和恢复流程。

帮助与许可证

如有问题，请使用 Discussions；如发现可复现的错误，请使用 Issues。请通过私密安全公告报告安全漏洞；另请参阅 SECURITY.md。

Codexa 采用 MIT 许可证。