repomix

Repomix - 面向 AI 的代码库打包工具

将整个代码库打包成一个适合 AI 使用的文件，并针对 Claude、ChatGPT、Gemini 等大模型进行优化。

何时使用此技能

• 将代码库提供给 AI，用于分析或重构
• 生成全面的代码评审
• 根据代码生成文档
• 为 AI 辅助开发准备上下文
• 无需克隆即可分析远程代码库
• 统计 Token 数量，检查是否符合大模型上下文限制

快速开始

# Pack current directory (no install required)
npx repomix@latest

# Pack specific directory
npx repomix path/to/directory

# Pack with compression (~70% token reduction)
npx repomix --compress

# Copy output to clipboard
npx repomix --copy

默认输出： 当前目录下的 ./repomix-output.xml

示例

示例：为 Claude 代码评审准备代码库

User: "Pack my src folder for Claude to review the architecture"
→ npx repomix --include "src/**/*" --style xml --copy
→ Output copied to clipboard, ready to paste into Claude

示例：无需克隆即可分析远程代码库

User: "I want to understand how shadcn/ui implements its button"
→ npx repomix --remote shadcn-ui/ui --include "**/button/**/*" --compress
→ Generates focused output of button component

示例：准备 PR 差异以供评审

User: "Pack only the files I changed for a code review"
→ git diff --name-only main | npx repomix --stdin --compress
→ Packs only modified files with compression

示例：向 AI 发送内容前检查 Token 用量

User: "Is my codebase too large for GPT-4?"
→ npx repomix --token-count-tree
→ Shows token breakdown per file/directory

示例：根据库生成技能参考

User: "Create a Claude skill from the zod repository"
→ npx repomix --remote colinhacks/zod --skill-generate zod-reference
→ Generates AI-optimized reference documentation

输出格式

# XML (default) - best for Claude
npx repomix --style xml

# Markdown - human readable
npx repomix --style markdown

# JSON - programmatic processing
npx repomix --style json

# Plain text
npx repomix --style plain

Token 优化

大模型上下文限制参考

模型	上下文窗口	典型代码库适用规模
Claude 3.5/Opus	200K 个 Token	大型单体代码库
GPT-4 Turbo/4o	128K 个 Token	中型项目
Gemini 1.5 Pro	1M 个 Token	超大型代码库
Gemini 1.5 Flash	1M 个 Token	超大型代码库

Token 分析

# Show token count tree
npx repomix --token-count-tree

# Filter by minimum tokens (show files with 1000+ tokens)
npx repomix --token-count-tree 1000

# Split output for large codebases
npx repomix --split-output 1mb

文件选择

包含模式

# Include only TypeScript files
npx repomix --include "**/*.ts"

# Include multiple patterns
npx repomix --include "src/**/*.ts,**/*.md"

# Include specific directories
npx repomix --include "src/**/*,tests/**/*"

忽略模式

# Ignore test files
npx repomix --ignore "**/*.test.ts"

# Ignore multiple patterns
npx repomix --ignore "**/*.log,tmp/,dist/"

# Combine include and ignore
npx repomix --include "src/**/*.ts" --ignore "**/*.test.ts"

标准输入

# From find command
find src -name "*.ts" -type f | npx repomix --stdin

# From git tracked files
git ls-files "*.ts" | npx repomix --stdin

# Interactive selection with fzf
find . -name "*.ts" -type f | fzf -m | npx repomix --stdin

# From ripgrep
rg --files --type ts | npx repomix --stdin

常见工作流

PR 评审准备

# Pack only changed files for review
git diff --name-only main | npx repomix --stdin --compress

# Pack with diff context included
npx repomix --include-diffs --compress

架构分析

# Pack structure without implementation details
npx repomix --compress --include "src/**/*" --ignore "**/*.test.*"

# Focus on specific layer
npx repomix --include "src/api/**/*,src/services/**/*" --compress

文档生成

# Pack with full context for docs
npx repomix --include "src/**/*,**/*.md" --style markdown

# Include git history for changelog
npx repomix --include-logs --include-logs-count 50

依赖分析

# Pack only config and dependency files
npx repomix --include "package.json,tsconfig.json,**/*.config.*"

远程代码库

# Pack remote repository
npx repomix --remote https://github.com/user/repo

# GitHub shorthand
npx repomix --remote user/repo

# Specific branch
npx repomix --remote user/repo --remote-branch main

# Specific commit
npx repomix --remote user/repo --remote-branch 935b695

# Branch URL format
npx repomix --remote https://github.com/user/repo/tree/feature-branch

代码压缩

基于 Tree-sitter 的压缩功能会提取签名，同时移除实现细节。

支持的语言

Tree-sitter 压缩支持 JavaScript、TypeScript、Python、Ruby、Go、Rust、Java、C、C++、C#、PHP、Swift、Kotlin 等语言。

用法

npx repomix --compress

# Combine with remote
npx repomix --remote user/repo --compress

压缩前：

const calculateTotal = (items: Item[]) => {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
  }
  return total;
};

压缩后：

const calculateTotal = (items: Item[]) => { /* ... */ };

Git 集成

# Include git logs (last 50 commits)
npx repomix --include-logs

# Specify commit count
npx repomix --include-logs --include-logs-count 20

# Include git diffs
npx repomix --include-diffs

# Combine logs and diffs
npx repomix --include-logs --include-diffs

配置

初始化配置

# Create repomix.config.json
npx repomix --init

# Global config
npx repomix --init --global

配置文件

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml",
    "compress": false,
    "removeComments": false,
    "showLineNumbers": false,
    "copyToClipboard": false
  },
  "include": ["src/**/*", "**/*.md"],
  "ignore": {
    "useGitignore": true,
    "useDefaultPatterns": true,
    "customPatterns": ["**/*.test.ts", "dist/"]
  },
  "security": {
    "enableSecurityCheck": true
  }
}

Docker 用法

# Pack current directory
docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix

# Pack specific directory
docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix path/to/directory

# Remote repository
docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote user/repo

MCP 服务集成

作为 Model Context Protocol 服务运行，为 AI 助手提供支持：

npx repomix --mcp

为 Claude Code 配置

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

可用的 MCP 工具

作为 MCP 服务运行时，提供：

工具	描述
pack_codebase	将本地目录打包为适合 AI 使用的格式
pack_remote_repository	无需克隆即可打包 GitHub 代码库
read_repomix_output	读取生成的输出文件内容
file_system_tree	获取目录树结构

Claude Agent 技能生成

为 Claude 生成技能格式的输出：

# Generate skills from local directory
npx repomix --skill-generate

# Generate with custom name
npx repomix --skill-generate my-project-reference

# From remote repository
npx repomix --remote user/repo --skill-generate

CLI 选项参考

选项	描述
-o, --output <file>	输出文件路径
--style <style>	输出格式：xml、markdown、json、plain
--compress	启用 Tree-sitter 压缩
--include <patterns>	包含与 glob 模式匹配的文件
-i, --ignore <patterns>	排除与模式匹配的文件
--remote <url>	处理远程代码库
--remote-branch <name>	远程代码库的分支、标签或提交
--stdin	从标准输入读取文件路径
--copy	将输出复制到剪贴板
--token-count-tree	显示每个文件的 Token 数量
--split-output <size>	按大小拆分输出（例如 1mb）
--include-logs	包含 Git 提交历史
--include-diffs	包含 Git 差异
--no-security-check	跳过敏感数据检测
--mcp	作为 MCP 服务运行
--skill-generate	生成 Claude 技能格式
--init	创建配置文件
--help	显示所有可用选项

故障排除

问题	解决方案
输出对大模型来说过大	使用 --compress，或通过 --include 进行筛选
缺少预期文件	检查 .repomixignore、.gitignore 和忽略模式
检测到机密信息（阻止运行）	检查被标记的文件；如果是误报，可使用 --no-security-check
大型仓库出现内存问题	使用 --split-output 1mb 将输出分块
远程仓库访问被拒绝	检查 URL 格式；确保仓库是公开的，或使用 SSH
压缩不起作用	确认 Tree-sitter 支持该语言
输出未复制到剪贴板	确保可访问剪贴板；在 macOS 上尝试 --output - | pbcopy

忽略文件

Repomix 会按优先级顺序遵循多个忽略来源：

1. 配置中的 ignore.customPatterns
2. .repomixignore（Repomix 专用）
3. .ignore（兼容 ripgrep）
4. .gitignore
5. 默认模式（node_modules、.git 等）

安全性

Repomix 内置 Secretlint，用于检测敏感信息：

# Security check enabled by default
npx repomix

# Disable security check (use with caution)
npx repomix --no-security-check

检测到的机密类型： API 密钥、令牌、密码、私钥、AWS 凭证、数据库连接字符串等。

最佳实践

1. 对大型代码库使用压缩，以减少令牌数量（约减少 70%）
2. 使用 --include 进行筛选，聚焦于相关文件
3. 使用 --token-count-tree，在打包前找出大型文件
4. 达到 AI 上下文限制时拆分输出
5. 需要了解演变过程时包含 Git 日志
6. Claude 使用 XML 样式（针对 XML 标签进行了优化）
7. 需要便于人工阅读的输出或面向其他大模型时使用 Markdown
8. 根据目标大模型的上下文窗口检查令牌数量
9. 分享打包后的输出前检查安全警告

要求

• Node.js 18.0.0 或更高版本
• PATH 中可用 npm 或 npx

资源

• 网站：https://repomix.com
• GitHub：https://github.com/yamadashy/repomix
• Chrome 扩展：Repomix - Chrome Web Store
• VSCode 扩展：Repomix Runner

---

注意事项

• --compress 会移除函数体，但保留函数签名——这很适合审查架构，但对于“这个函数为什么有缺陷”这类问题毫无用处。大模型确实无法看到实现代码。
• 安全检查检测到机密信息时会完全阻止输出——即使测试样例中只有一个形似 AWS 密钥的误报字符串，也会导致运行失败。只有检查过被标记的文件后，才使用 --no-security-check。
• 会遵循 .gitignore，但不会遵循 .dockerignore——你的 node_modules 会被排除，但 Dockerfile 忽略的大型 dist/ 目录仍会被打包。添加 .repomixignore 以匹配这些规则。
• 令牌数量基于 tiktoken（GPT）计算——Claude 使用的分词器有所不同，差异约为 10-20%。报告为“180K tokens”的仓库可能会超出 Claude 的 200K 窗口，也可能轻松适配，具体取决于内容。
• --remote user/repo 会将默认分支克隆到临时目录并在本地运行——这并非什么 GitHub API 魔法。私有仓库需要配置 SSH 密钥；错误消息只会显示“访问被拒绝”，不会说明身份验证方式。
• --stdin 会读取以 NUL 或换行符分隔的路径，并会静默丢弃不存在或位于当前工作目录之外的路径。git diff --name-only 输出中的拼写错误会导致打包结果变小，但不会发出警告。
• 在 macOS 上通过 pbcopy 使用 --copy 时，在某些终端复用器中（例如未设置 set-clipboard on 的 tmux）会在约 1MB 处截断。请检查粘贴内容的大小，再确认输出是否完整。