Repomix

代码仓库上下文打包器，按忽略规则筛选文件并序列化为 XML/Markdown/JSON，附 Token 统计与安全扫描，为 AI 提供一次性项目快照；不是代码关系图谱。

#type / resource #status / evergreen #tech / ai #resource / repomix #purpose / development #media / tool #interface / cli #interface / ai

[!info] related notes

所属 MOC: AI MOC, Coding Agent MOC

对比关系: Repomix 与代码关系图谱工具的区别

相邻工具: CodeGraph, GitNexus

背景: MCP 协议, Knowledge Graph

Repomix

这是什么

Repomix 是一个代码仓库上下文打包器。它读取本地或远程代码仓库，按忽略规则筛选文件，然后把项目概况、目录结构、文件路径、文件内容、Token 统计、可选的 Git diff / 提交记录整理成一个适合 AI 阅读的 XML、Markdown、JSON 或纯文本文件，默认生成 repomix-output.xml。

可以理解为：把散落在几百个文件里的代码，制作成一份结构清晰的“项目上下文包”，交给 ChatGPT、Claude、Codex 等 AI。

它不是代码搜索引擎，也不是 CodeGraph / GitNexus 那样的关系图谱，而是一个代码仓库序列化、筛选与压缩工具。

它解决什么问题

普通 AI Agent 分析仓库时通常要 ls → 读 README → 读 package.json → 看 src → grep 路由 → 读模块 A/B…，问题在于工具调用多、每次读都耗 Token、可能漏掉关键目录、不同 AI 探索过程不一致、传到网页端 AI 要手动上传很多文件。

Repomix 提前把仓库处理成 项目统计 + 目录树 + 关键文件 + 代码内容 + Git 信息，AI 一次获得相对完整的项目视图，无需从零盲目探索。

工作方式 / 流水线

本地目录 / 远程 GitHub 仓库
  → 搜集项目文件
  → 应用 .gitignore / .ignore / .repomixignore
  → 排除 node_modules、dist、二进制等
  → Secretlint 安全扫描
  → 可选：删除注释、空行、压缩代码
  → 统计文件大小、行数、Token 数
  → 生成 XML / Markdown / JSON / Plain Text

默认遵守 .gitignore、.ignore 和 .repomixignore，并有内置排除规则（.git、node_modules、dist、常见二进制）。二进制文件内容不进输出，但路径可继续显示在目录结构中。

输出里有什么

默认 XML 结构类似：

<file_summary>   项目统计、Token 数量、使用说明 </file_summary>
<directory_structure> apps/web、apps/api、packages/shared … </directory_structure>
<files>
  <file path="apps/web/src/main.tsx"> … </file>
  <file path="apps/api/src/server.ts"> … </file>
</files>

还可选加入：

<git_diffs>    当前工作区和暂存区修改 </git_diffs>
<git_logs>     最近提交记录及每次修改的文件 </git_logs>

四种格式：XML（默认，结构标签清晰，AI 不易混淆目录树/代码/指令）、Markdown（适合人读与 Obsidian）、JSON（适合二次编程）、Plain Text（兼容简单工具）。

如何减少 Token

1. 先减少不必要的文件

用 --include / --ignore 精确控制，或用 .repomixignore 排除 dist/、build/、coverage/、pnpm-lock.yaml、**/generated/**、**/__snapshots__/** 等。--token-count-tree 可查看哪些目录/文件最耗 Token。

2. 删除空行和注释

repomix --remove-empty-lines
repomix --remove-comments

空行通常可放心删；注释是否保留取决于目的：生成“架构分析包”保留注释（业务约束常写在注释里），生成“纯代码审查包”再考虑移除。

3. Tree-sitter 代码压缩（实验性）

repomix --compress

通过 Tree-sitter 解析，保留 import/export、函数与方法签名、类结构、接口与类型、属性定义，折叠或删除函数实现、循环/条件、局部变量。例如 createUser 压缩后只留签名与结构，AI 知道它存在、输入类型、是异步、属于哪个模块，但不知道内部校验与保存逻辑。官方标记实验性，典型 Token 降幅约 70%，实际随语言/风格/结构变化。适合架构与接口分析，不适合深入排查业务逻辑。

4. 按文件设置不同详细程度

通过 patterns 让 README/文档/核心代码完整保留、次要代码压缩、测试只显示路径（directoryStructureOnly）、构建产物完全忽略。规则按顺序匹配，第一个命中生效，比“全部压缩”更优雅。

{
  "output": {
    "style": "xml",
    "compress": true,            // 默认压缩未特别匹配的源码
    "patterns": [
      { "pattern": "README.md" },
      { "pattern": "docs/**/*" },
      { "pattern": "**/package.json" },
      { "pattern": "apps/api/src/runtime/**/*" },          // 核心运行时代码完整保留
      { "pattern": "**/*.test.*", "directoryStructureOnly": true },
      { "pattern": "**/*.spec.*", "directoryStructureOnly": true }
    ]
  }
}

5. Token 统计与预算

repomix --token-count-tree            # 查看 Token 分布
repomix --token-count-tree 1000       # 只看超过 1000 Token 的项
repomix --token-budget 100000         # 超预算仍以非零状态码退出，适合 CI/Agent

基础使用

npx repomix@latest                   # 项目根目录，生成 repomix-output.xml
repomix apps/web apps/api            # 指定多个目录
repomix --remote yamadashy/repomix   # 分析远程仓库，可加 --remote-branch
repomix --watch                      # 本地监听变更并自动重新生成（仅本地）

支持全局安装、Bun / Yarn / Homebrew / Docker。

MCP 与 Agent 集成

repomix --mcp
claude mcp add repomix -- npx -y repomix --mcp

MCP 模式下 Agent 可调用：pack_codebase、pack_remote_repository、read_repomix_output、grep_repomix_output、file_system_read_file、file_system_read_directory。典型流程：先 pack_codebase 获得整体结构，再 grep_repomix_output 定位关键词，最后局部读取相关区域——比一次性塞入全文更合理。

另有面向 Codex 的 Repomix Explorer Skill（npx skills add yamadashy/repomix --skill repomix-explorer --agent codex），教 Agent 正确打包、先 grep 再局部读取、按任务选压缩与 include 规则。以及 --skill-generate（实验性）：把你自己的仓库或第三方仓库（如 facebook/react）转换成参考 Skill（SKILL.md + references），供 Agent 后续参考。

与代码关系图谱工具的区别

Repomix 解决“怎么把代码仓库高质量地交给 AI”；CodeGraph / GitNexus 解决“AI 怎么在代码关系网络里精确导航”。Repomix 的 MCP 搜索本质仍是正则/文本定位，不等于“查找所有调用 X 的函数”“查找接口 I 的全部实现”“查找从路由到 DB 的调用链”——这些更适合 CodeGraph、语言服务器或 GitNexus。详见 Repomix 与代码关系图谱工具的区别。

优势

非常简单：npx repomix@latest 即得可交付文件
对一次性项目分析（陌生 GitHub 项目、生成架构文档、写简历项目经历）非常合适
可固定上下文：同一份快照交给不同模型，大家看到同一仓库视图
方便做归档/项目快照（重构前后对比）
对网页端 AI 友好（上传一个文件胜过上传几十个源码文件）

局限

大项目仍可能非常大：不要直接 repomix 全量扔给模型，应分层（目录元数据 → 压缩源码 → 任务相关完整源码）
压缩会丢失实现细节：--compress 适合回答“有哪些模块/接口边界/技术栈”，不适合排查具体并发死锁、reducer 重复、SQL 错误
没有真正理解项目：收集/过滤/格式化/压缩/统计由 Repomix 完成，理解仍靠 LLM，不保证 AI 正确识别架构或不产生幻觉
打包输出会过期：代码修改后旧 XML 是旧快照；本地可用 --watch，但不支持远程仓库与部分选项组合

安全

默认用 Secretlint 扫描 API Key、Access Token、私钥、数据库连接串、密码等，发现可疑文件即从输出排除。但仍非绝对保证，建议始终在忽略规则中加入 .env、*.pem、secrets/ 等，并在上传前用 grep 复查。处理远程仓库时不要随意用 --remote-trust-config（远程配置可能执行命令、读本地文件），仅完全信任目标仓库时才开启。

官方入口

官网：https://repomix.com/
GitHub：https://github.com/yamadashy/repomix