yamadashy--repomix/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

^{特别感谢：}

Warp，专为多 AI 智能体编程而打造

支持 MacOS、Linux 与 Windows

CodeRabbit | AI 代码审查

即刻将代码审查时间与缺陷减半。

---

将代码库打包为 AI 友好格式

在线使用 Repomix！👉 repomix.com

需要交流？欢迎加入我们的 Discord！
分享你的经验与技巧
及时了解新功能
获取配置与使用方面的帮助

---

📦 Repomix 是一款强大的工具，可将整个代码仓库打包成单个 AI 友好文件。
它非常适合需要将代码库提供给大语言模型（LLM，Large Language Models）或其他 AI 工具的场景，例如 Claude、 ChatGPT、DeepSeek、Perplexity、Gemini、Gemma、Llama、Grok 等。

欢迎考虑赞助我。

🏆 开源大奖提名

我们很荣幸！Repomix 已获提名 JSNation Open Source Awards 2025. 的 Powered by AI 类别。

若没有各位使用与支持 Repomix，这一切都不可能实现。感谢大家！

🎉 新功能：Repomix 网站与 Discord 社区！

• 在浏览器中访问 repomix.com 试用 Repomix
• 加入我们的 Discord 服务器 获取支持与参与讨论

期待在那里与你相见！

🌟 功能特性

• AI 优化：以便于 AI 理解与处理的格式组织你的代码库。
• Token 计数：提供每个文件及整个仓库的 token 数量，便于应对 LLM 上下文限制。
• 简单易用：只需一条命令即可打包整个代码仓库。
• 可自定义：轻松配置需要包含或排除的内容。
• Git 感知：自动遵循你的 .gitignore、.ignore 和 .repomixignore 文件。
• 注重安全：集成 Secretlint 进行严格的安全检查，检测并防止敏感信息被纳入。
• 代码压缩：--compress 选项使用 Tree-sitter 提取关键代码元素，在保留结构的同时减少 token 数量。

🚀 快速开始

使用 CLI 工具 >_

你可以在不安装的情况下，直接在项目目录中即时试用 Repomix：

npx repomix@latest

或全局安装以便反复使用：

# Install using npm
npm install -g repomix

# Alternatively using yarn
yarn global add repomix

# Alternatively using bun
bun add -g repomix

# Alternatively using Homebrew (macOS/Linux)
brew install repomix

# Then run in any project directory
repomix

就这么简单！Repomix 会在当前目录生成一个 repomix-output.xml 文件，其中包含以 AI 友好格式呈现的整个 代码仓库。

随后，你可以将该文件发送给 AI 助手，并配合如下提示词：

This file contains all the files in the repository combined into one.
I want to refactor the code, so please review it first.

当你提出具体修改建议时，AI 可能会据此生成相应代码。借助 Claude 的 Artifacts 等功能，你甚至可以输出多个文件，从而生成多个相互依赖的代码片段。

祝编码愉快！🚀

使用网站 🌐

想快速体验？访问官方网站 repomix.com. 输入你的代码仓库 名称，填写可选信息，然后点击 Pack 按钮即可查看生成的输出。

可用选项

网站提供多项便捷功能：

• 可自定义输出格式（XML、Markdown 或纯文本）
• 即时 token 数量估算
• 还有更多！

使用浏览器扩展 🧩

从任意 GitHub 代码仓库即可即时访问 Repomix！我们的 Chrome 扩展会在 GitHub 仓库页面添加便捷的「Repomix」按钮。

安装

• Chrome 扩展：Repomix - Chrome Web Store
• Firefox 附加组件：Repomix - Firefox Add-ons

功能

• 一键访问任意 GitHub 仓库的 Repomix
• 更多精彩功能即将推出！

使用 VSCode 扩展 ⚡️

一个由社区维护的 VSCode 扩展，名为 Repomix Runner（由 massdo) 创建），让你只需几次点击即可在编辑器内直接运行 Repomix。可在任意文件夹上运行、无缝管理输出，并通过 VSCode 直观的界面进行控制。

想要将输出保存为文件还是仅获取内容？需要自动清理？该扩展都能满足。此外，它还能与你现有的 repomix.config.json 顺畅配合。

立即在 VSCode Marketplace! 试用
源代码可在 GitHub. 获取

替代工具 🛠️

如果你使用 Python，可以看看 Gitingest，它更适合 Python 生态和数据科学（data science）工作流： https://github.com/cyclotruc/gitingest

📊 用法

要打包整个仓库：

repomix

要打包特定目录：

repomix path/to/directory

使用 glob 模式: 打包特定文件或目录：

repomix --include "src/**/*.ts,**/*.md"

要排除特定文件或目录：

repomix --ignore "**/*.log,tmp/"

要打包远程仓库：

repomix --remote https://github.com/yamadashy/repomix

# You can also use GitHub shorthand:
repomix --remote yamadashy/repomix

# You can specify the branch name, tag, or commit hash:
repomix --remote https://github.com/yamadashy/repomix --remote-branch main

# Or use a specific commit hash:
repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695

# Another convenient way is specifying the branch's URL
repomix --remote https://github.com/yamadashy/repomix/tree/main

# Commit's URL is also supported
repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1

通过文件列表打包（经 stdin 管道传入）：

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

# Using git to get tracked files
git ls-files "*.ts" | repomix --stdin

# Using grep to find files containing specific content
grep -l "TODO" **/*.ts | repomix --stdin

# Using ripgrep to find files with specific content
rg -l "TODO|FIXME" --type ts | repomix --stdin

# Using ripgrep (rg) to find files
rg --files --type ts | repomix --stdin

# Using sharkdp/fd to find files
fd -e ts | repomix --stdin

# Using fzf to select from all files
fzf -m | repomix --stdin

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

# Using ls with glob patterns
ls src/**/*.ts | repomix --stdin

# From a file containing file paths
cat file-list.txt | repomix --stdin

# Direct input with echo
echo -e "src/index.ts\nsrc/utils.ts" | repomix --stdin

--stdin 选项允许你将文件路径列表通过管道传给 Repomix，在选择要打包的文件时提供极大的灵活性。

使用 --stdin 时，指定的文件实际上会被添加到 include 模式中。这意味着常规的 include 和 ignore 行为仍然适用——通过 stdin 指定的文件如果匹配 ignore 模式，仍会被排除。

Note

使用 --stdin 时，文件路径可以是相对路径或绝对路径，Repomix 会自动处理路径解析与去重。

要在输出中包含 git 日志：

# Include git logs with default count (50 commits)
repomix --include-logs

# Include git logs with specific commit count
repomix --include-logs --include-logs-count 10

# Combine with diffs for comprehensive git context
repomix --include-logs --include-diffs

git 日志包含每次提交的提交日期、提交信息与文件路径，为 AI 分析代码演进与开发模式提供有价值的上下文。

要压缩输出：

repomix --compress

# You can also use it with remote repositories:
repomix --remote yamadashy/repomix --compress

要初始化新的配置文件（repomix.config.json）：

repomix --init

生成打包文件后，可将其用于 ChatGPT、DeepSeek、Perplexity、Gemini、Gemma、Llama、Grok 等生成式 AI 工具。

Docker 用法 🐳

你也可以使用 Docker 运行 Repomix。
如果你希望在隔离环境中运行 Repomix，或更偏好使用容器，这会很有用。

基本用法（当前目录）：

docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix

要打包特定目录：

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

处理远程仓库并输出到 output 目录：

docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote https://github.com/yamadashy/repomix

提示词示例

使用 Repomix 生成打包文件后，可将其用于 ChatGPT、DeepSeek、Perplexity、Gemini、Gemma、Llama、Grok 等 AI 工具。 以下是一些示例提示词，帮助你快速上手：

代码审查与重构

进行全面代码审查并获取重构建议：

This file contains my entire codebase. Please review the overall structure and suggest any improvements or refactoring opportunities, focusing on maintainability and scalability.

文档生成

生成项目文档：

Based on the codebase in this file, please generate a detailed README.md that includes an overview of the project, its main features, setup instructions, and usage examples.

测试用例生成

生成测试用例：

Analyze the code in this file and suggest a comprehensive set of unit tests for the main functions and classes. Include edge cases and potential error scenarios.

代码质量评估

评估代码质量及对最佳实践的遵循程度：

Review the codebase for adherence to coding best practices and industry standards. Identify areas where the code could be improved in terms of readability, maintainability, and efficiency. Suggest specific changes to align the code with best practices.

库概览

获得对库的高层次理解

This file contains the entire codebase of library. Please provide a comprehensive overview of the library, including its main purpose, key features, and overall architecture.

可根据你的具体需求以及所用 AI 工具的能力，自由修改这些提示词。

社区讨论

查看我们的 社区讨论，用户在其中分享：

• 他们搭配 Repomix 使用的 AI 工具
• 他们发现的有效提示词
• Repomix 如何帮助了他们
• 充分利用 AI 代码分析的技巧与窍门

欢迎加入讨论并分享你的经验！你的见解可能帮助他人更好地使用 Repomix。

输出文件格式

Repomix 会生成一个单一文件，在代码库不同部分之间使用清晰的分隔符。
为增强 AI 理解，输出文件以面向 AI 的说明开头，使 AI 模型更容易理解所打包仓库的上下文与结构。

XML 格式（默认）

XML 格式以层次化方式组织内容：

This file is a merged representation of the entire codebase, combining all repository files into a single document.

<file_summary>
  (Metadata and usage AI instructions)
</file_summary>

<directory_structure>
src/
cli/
cliOutput.ts
index.ts

(...remaining directories)
</directory_structure>

<files>
<file path="src/index.js">
  // File contents here
</file>

(...remaining files)
</files>

<instruction>
(Custom instructions from `output.instructionFilePath`)
</instruction>

如果你对 AI 场景下 XML 标签（XML tags）的潜力感兴趣：
https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags

当你的提示词包含上下文、指令和示例等多个组成部分时，XML 标签可以带来颠覆性的改变。它们能帮助 Claude 更准确地解析你的提示词，从而获得更高质量的输出。

这意味着 Repomix 的 XML 输出不仅是一种不同的格式，还可能是一种更有效的方式，用于将代码库输入 AI 系统进行代码分析、代码审查或其他任务。

Markdown 格式

要生成 Markdown 格式的输出，请使用 --style markdown 选项：

repomix --style markdown

Markdown 格式以层级方式组织内容：

This file is a merged representation of the entire codebase, combining all repository files into a single document.

# File Summary

(Metadata and usage AI instructions)

# Repository Structure

```
src/
  cli/
    cliOutput.ts
    index.ts
```

(...remaining directories)

# Repository Files

## File: src/index.js

```
// File contents here
```

(...remaining files)

# Instruction

(Custom instructions from `output.instructionFilePath`)

该格式提供清晰、易读的结构，既便于人类阅读，也便于 AI 系统解析。

JSON 格式

要生成 JSON 格式的输出，请使用 --style json 选项：

repomix --style json

JSON 格式将内容组织为层级化的 JSON 对象，属性名采用 camelCase：

{
  "fileSummary": {
    "generationHeader": "This file is a merged representation of the entire codebase, combined into a single document by Repomix.",
    "purpose": "This file contains a packed representation of the entire repository's contents...",
    "fileFormat": "The content is organized as follows...",
    "usageGuidelines": "- This file should be treated as read-only...",
    "notes": "- Some files may have been excluded based on .gitignore, .ignore, and .repomixignore rules..."
  },
  "userProvidedHeader": "Custom header text if specified",
  "directoryStructure": "src/\n  cli/\n    cliOutput.ts\n    index.ts\n  config/\n    configLoader.ts",
  "files": {
    "src/index.js": "// File contents here",
    "src/utils.js": "// File contents here"
  },
  "instruction": "Custom instructions from instructionFilePath"
}

该格式适用于：

• 程序化处理：易于使用 JSON 库解析和操作
• API 集成：可供 Web 服务与应用程序直接消费
• AI 工具兼容：为机器学习与 AI 系统提供结构化格式
• 数据分析：可使用 jq 等工具轻松提取特定信息

使用 jq 处理 JSON 输出

JSON 格式便于以编程方式提取特定信息：

# List all file paths
cat repomix-output.json | jq -r '.files | keys[]'

# Count total number of files
cat repomix-output.json | jq '.files | keys | length'

# Extract specific file content
cat repomix-output.json | jq -r '.files["README.md"]'
cat repomix-output.json | jq -r '.files["src/index.js"]'

# Find files by extension
cat repomix-output.json | jq -r '.files | keys[] | select(endswith(".ts"))'

# Get files containing specific text
cat repomix-output.json | jq -r '.files | to_entries[] | select(.value | contains("function")) | .key'

# Extract directory structure
cat repomix-output.json | jq -r '.directoryStructure'

# Get file summary information
cat repomix-output.json | jq '.fileSummary.purpose'
cat repomix-output.json | jq -r '.fileSummary.generationHeader'

# Extract user-provided header (if exists)
cat repomix-output.json | jq -r '.userProvidedHeader // "No header provided"'

# Create a file list with sizes
cat repomix-output.json | jq -r '.files | to_entries[] | "\(.key): \(.value | length) characters"'

纯文本格式

要生成纯文本格式的输出，请使用 --style plain 选项：

repomix --style plain

This file is a merged representation of the entire codebase, combining all repository files into a single document.

================================================================
File Summary
================================================================
(Metadata and usage AI instructions)

================================================================
Directory Structure
================================================================
src/
  cli/
    cliOutput.ts
    index.ts
  config/
    configLoader.ts

(...remaining directories)

================================================================
Files
================================================================

================
File: src/index.js
================
// File contents here

================
File: src/utils.js
================
// File contents here

(...remaining files)

================================================================
Instruction
================================================================
(Custom instructions from `output.instructionFilePath`)

命令行选项

基本选项

• -v, --version：显示版本信息并退出

CLI 输入/输出选项

Option	Description
--verbose	启用详细调试日志（显示文件处理、token 计数和配置详情）
--quiet	抑制除错误外的所有控制台输出（适用于脚本场景）
--stdout	将打包输出直接写入 stdout，而非写入文件（抑制所有日志）
--stdin	从 stdin 读取文件路径，每行一个（直接处理指定的文件）
--copy	处理完成后将生成的输出复制到系统剪贴板
--token-count-tree [threshold]	显示带 token 计数的文件树；可选阈值，仅显示 token 数 ≥N 的文件（例如 --token-count-tree 100）
--top-files-len <number>	摘要中显示的最大文件数量（默认：5）

Repomix 输出选项

Option	Description
-o, --output <file>	输出文件路径（默认：repomix-output.xml，使用 "-" 输出到 stdout）
--style <style>	输出格式：xml、markdown、json 或 plain（默认：xml）
--output-file-path-style <style>	输出中文件路径的显示方式：target-relative 或 cwd-relative（默认：target-relative）
--parsable-style	转义特殊字符，确保生成有效的 XML/Markdown（当输出包含会破坏格式的代码时需要）
--compress	使用 Tree-sitter 解析提取核心代码结构（类、函数、接口）
--output-show-line-numbers	在输出的每一行前添加行号前缀
--no-file-summary	从输出中省略文件摘要部分
--no-directory-structure	从输出中省略目录树可视化
--no-files	仅生成元数据，不包含文件内容（适用于仓库分析）
--remove-comments	打包前移除所有代码注释
--remove-empty-lines	从所有文件中移除空行
--truncate-base64	截断较长的 base64 数据字符串以减小输出体积
--header-text <text>	在输出开头包含的自定义文本
--instruction-file-path <path>	包含自定义指令的文件路径，这些指令将写入输出
--split-output <size>	将输出拆分为多个编号文件（例如 repomix-output.1.xml）；大小类似 500kb、2mb 或 1.5mb
--include-empty-directories	在目录结构中包含没有文件的文件夹
--include-full-directory-structure	在输出中显示完整目录树，包括未被 --include 模式匹配的文件
--no-git-sort-by-changes	不按 git 变更频率排序文件（默认：变更最频繁的文件在前）
--include-diffs	添加 git diff 部分，显示工作区与暂存区的变更
--include-logs	添加 git 提交历史，包含提交信息与变更文件
--include-logs-count <count>	与 --include-logs 一起包含的最近提交数量（默认：50）

文件选择选项

选项	说明
--include <patterns>	仅包含匹配这些 glob 模式的文件（逗号分隔，例如 "src/**/*.js,*.md"）
-i, --ignore <patterns>	额外要排除的模式（逗号分隔，例如 "*.test.js,docs/**"）
--no-gitignore	不使用 .gitignore 规则来过滤文件
--no-dot-ignore	不使用 .ignore 规则来过滤文件
--no-default-patterns	不应用内置忽略模式（node_modules、.git、构建目录等）

远程仓库选项

选项	说明
--remote <url>	克隆并打包远程仓库（GitHub URL 或 user/repo 格式）
--remote-branch <name>	要使用的特定分支、标签或提交（默认：仓库的默认分支）
--remote-trust-config	信任并加载远程仓库中的配置文件（出于安全考虑，默认禁用）

配置选项

选项	说明
-c, --config <path>	使用自定义配置文件，而非 repomix.config.json
--init	使用默认值创建新的 repomix.config.json 文件
--global	与 --init 配合使用时，在主目录而非当前目录创建配置

安全选项

• --no-security-check：跳过对 API 密钥、密码等敏感数据的扫描

Token 计数选项

• --token-count-encoding <encoding>：用于计数的分词器（Tokenizer）模型：o200k_base（GPT-4o）、cl100k_base（GPT-3.5/4）等（默认：o200k_base）
• --token-budget <number>：当打包输出超过 N 个 token 时以非零退出码失败。在 CI 流水线和 Agent 工作流中可作为护栏，使输出保持在目标模型的上下文窗口内。输出仍会生成；仅通过退出码表示溢出。

MCP

• --mcp：作为 Model Context Protocol（MCP）服务器运行，用于 AI 工具集成

Agent Skills 生成

选项	说明
--skill-generate [name]	生成 Claude Agent Skills 格式输出到 .claude/skills/<name>/ 目录（若省略则自动生成名称）
--skill-project-name <name>	覆盖生成 Skills 描述中使用的项目名称
--skill-output <path>	直接指定技能输出目录路径（跳过位置提示）
-f, --force	跳过所有确认提示（例如技能目录覆盖）

监视模式（Watch Mode）

• -w, --watch：监视文件变更并自动重新打包。对快速变更进行防抖（300ms），并在每次重建时记录时间戳。使用 Ctrl+C 停止。

  监视模式仅适用于本地目录，因此不能与 --remote、位置参数形式的远程仓库 URL、--stdout、--stdin、--split-output、--skill-generate 或 --copy 组合使用（无论在命令行还是配置文件中设置）。

示例

# Basic usage
repomix

# Custom output
repomix -o output.xml --style xml

# Output to stdout
repomix --stdout > custom-output.txt

# Send output to stdout, then pipe into another command (for example, simonw/llm)
repomix --stdout | llm "Please explain what this code does."

# Custom output with compression
repomix --compress

# Process specific files
repomix --include "src/**/*.ts" --ignore "**/*.test.ts"

# Split output into multiple files (max size per part)
repomix --split-output 20mb

# Remote repository with branch
repomix --remote https://github.com/user/repo/tree/main

# Remote repository with commit
repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1

# Remote repository with shorthand
repomix --remote user/repo

# Watch mode — automatically re-pack on file changes
repomix --watch
repomix -w --include "src/**/*.ts"

更新 Repomix

要更新全局安装的 Repomix：

# Using npm
npm update -g repomix

# Using yarn
yarn global upgrade repomix

# Using bun
bun update -g repomix

使用 npx repomix 通常更方便，因为它始终使用最新版本。

远程仓库处理

Repomix 支持处理远程 Git 仓库，无需手动克隆。借助该功能，你可以用一条命令快速分析任意公开 Git 仓库。

要处理远程仓库，请使用 --remote 选项，后跟仓库 URL：

repomix --remote https://github.com/yamadashy/repomix

你也可以使用 GitHub 的简写格式：

repomix --remote yamadashy/repomix

你可以指定分支名、标签或提交哈希：

# Using --remote-branch option
repomix --remote https://github.com/yamadashy/repomix --remote-branch main

# Using branch's URL
repomix --remote https://github.com/yamadashy/repomix/tree/main

或使用特定的提交哈希：

# Using --remote-branch option
repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695

# Using commit's URL
repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1

Note

出于安全考虑，远程仓库中的配置文件（repomix.config.*）默认不会加载。这可防止不受信任的仓库通过配置文件执行代码。你的全局配置和 CLI 选项仍会生效。若要信任远程仓库的配置，请使用 --remote-trust-config 或设置 REPOMIX_REMOTE_TRUST_CONFIG=true。

将 --config 与 --remote 一起使用时，需要提供绝对路径（例如 --config /home/user/repomix.config.json）。

代码压缩

--compress 选项利用 Tree-sitter) 执行智能代码提取，聚焦于关键的函数与类签名，同时移除实现细节。这有助于在保留重要结构信息的同时减少 token 数量。

repomix --compress

例如，以下代码：

import { ShoppingItem } from './shopping-item';

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

// Shopping item interface
interface Item {
  name: string;
  price: number;
  quantity: number;
}

将被压缩为：

import { ShoppingItem } from './shopping-item';
⋮----
/**
 * Calculate the total price of shopping items
 */
const calculateTotal = (
  items: ShoppingItem[]
) => {
⋮----
// Shopping item interface
interface Item {
  name: string;
  price: number;
  quantity: number;
}

Note

这是一项实验性功能，我们将根据用户反馈和实际使用情况持续改进

按文件包含级别（output.patterns）

--compress 对所有文件应用同一级别，而 output.patterns 允许你在配置文件中按 glob 控制详细程度。每条规则通过 glob 匹配文件（匹配方式与 include/ignore 相同），并为匹配的文件覆盖全局 output.compress 设置：

{
  "output": {
    "compress": false, // global default acts as the catch-all
    "patterns": [
      { "pattern": "docs/**/*", "compress": true },
      { "pattern": "website/**/*", "directoryStructureOnly": true }
    ]
  }
}

共有三个级别：

• 完整内容（默认）——包含文件的完整内容。
• 压缩（compress: true）——内容会经过与 --compress 相同的 Tree-sitter 处理流水线。
• 仅目录结构（directoryStructureOnly: true）——文件会列在目录结构中，但其内容块会完全从输出中省略。

语义说明：

• 模式按数组顺序求值，对给定文件首个匹配的模式生效。
• 匹配模式的标志会覆盖全局 output.compress 设置。若某模式匹配但未设置任一标志，则强制该文件为完整内容（适用于在全局 compress 下将文件加入白名单）。
• 当两者同时设置时，directoryStructureOnly 优先于 compress。
• 若无模式匹配，则应用全局行为（完整内容，或在 output.compress 为 true 时进行压缩）。

这是一项仅可通过配置文件设置的选项；没有用于按模式（per-pattern）设置级别的 CLI 标志。

Token 数量优化

了解代码库的 token 分布对于优化 AI 交互至关重要。使用 --token-count-tree 选项可可视化整个项目中的 token 使用情况：

repomix --token-count-tree

这会以层级视图展示代码库及各处的 token 数量：

🔢 Token Count Tree:
────────────────────
└── src/ (70,925 tokens)
    ├── cli/ (12,714 tokens)
    │   ├── actions/ (7,546 tokens)
    │   └── reporters/ (990 tokens)
    └── core/ (41,600 tokens)
        ├── file/ (10,098 tokens)
        └── output/ (5,808 tokens)

你也可以设置最低 token 阈值，以聚焦较大的文件：

repomix --token-count-tree 1000  # Only show files/directories with 1000+ tokens

这可以帮助你：

• 识别 token 密集文件，这些文件可能超出 AI 上下文限制
• 优化文件选择，使用 --include 和 --ignore 模式
• 规划压缩策略，针对占用 token 最多的文件
• 平衡内容与上下文，在为 AI 分析准备代码时

针对大型代码库拆分输出

处理大型代码库时，打包输出可能超过某些 AI 工具的文件大小限制（例如 Google AI Studio 的 1MB 限制）。使用 --split-output 可自动将输出拆分为多个文件：

repomix --split-output 1mb

这会生成如下编号的文件：

• repomix-output.1.xml
• repomix-output.2.xml
• repomix-output.3.xml

可使用单位指定大小：500kb、1mb、2mb、1.5mb 等。支持小数值。

Note

文件按顶层目录分组，以保持上下文。单个文件或目录绝不会被拆分到多个输出文件中。

MCP 服务器集成

Repomix 支持 Model Context Protocol (MCP),，使 AI 助手能够直接与你的代码库交互。作为 MCP 服务器运行时，Repomix 提供工具，让 AI 助手可在无需手动准备文件的情况下打包本地或远程仓库以供分析。

repomix --mcp

配置 MCP 服务器

要在 Claude 等 AI 助手中将 Repomix 用作 MCP 服务器，需要配置 MCP 设置：

适用于 VS Code：

你可以通过以下方式之一在 VS Code 中安装 Repomix MCP 服务器：

1. 使用安装徽章：

2. 使用命令行：

code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

适用于 VS Code Insiders：

code-insiders --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

适用于 Cline（VS Code 扩展）：

编辑 cline_mcp_settings.json 文件：

{
  "mcpServers": {
    "repomix": {
      "command": "npx",
      "args": [
        "-y",
        "repomix",
        "--mcp"
      ]
    }
  }
}

适用于 Cursor：

在 Cursor 中，从 Cursor Settings > MCP > + Add new global MCP server 添加新的 MCP 服务器，配置方式与 Cline 类似。

适用于 Claude Desktop：

编辑 claude_desktop_config.json 文件，配置方式与 Cline 类似。

适用于 Claude Code：

要在 Claude Code, 中将 Repomix 配置为 MCP 服务器，请使用以下命令：

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

或者，你可以使用官方 Repomix 插件（见下方 Claude Code Plugins 一节）。

使用 Docker 替代 npx：

你可以使用 Docker 替代 npx 来将 Repomix 作为 MCP 服务器运行：

{
  "mcpServers": {
    "repomix-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/yamadashy/repomix",
        "--mcp"
      ]
    }
  }
}

配置完成后，AI 助手可直接使用 Repomix 的功能分析代码库，无需手动准备文件，从而让代码分析工作流更高效。

可用的 MCP 工具

作为 MCP 服务器运行时，Repomix 提供以下工具：

1. pack_codebase：将本地代码目录打包为 consolidated XML 文件，供 AI 分析

• 参数：
  • directory：要打包目录的绝对路径
  • compress：（可选，默认：false）启用 Tree-sitter 压缩，提取核心代码签名与结构，同时移除实现细节。可在保留语义的同时将 token 使用量降低约 70%。由于 grep_repomix_output 支持增量检索内容，通常无需启用；仅当你明确需要大型仓库的完整代码库内容时才使用。
  • includePatterns：（可选）使用 fast-glob 模式指定要包含的文件。多个模式可用逗号分隔（例如 "**/*.{js,ts}"、"src/**,docs/**"）。仅处理匹配的文件。
  • ignorePatterns：（可选）使用 fast-glob 模式指定要额外排除的文件。多个模式可用逗号分隔（例如 "test/**,*.spec.js"、"node_modules/**,dist/**"）。这些模式是对 .gitignore、.ignore 及内置排除规则的补充。
  • outputPatterns：（可选）按文件设置包含级别，与配置文件中的 output.patterns 选项对应。为 { pattern, compress?, directoryStructureOnly? } 条目数组；首个匹配的模式生效，directoryStructureOnly 优先于 compress，若匹配项两者皆未设置则强制包含完整内容（可用于将文件从全局 compress 中豁免）。会覆盖目标仓库 repomix.config.json 中的任何 output.patterns。
  • topFilesLength：（可选，默认：10）在代码库分析的指标摘要中，按大小显示的最大文件数量。

2. attach_packed_output：附加现有的 Repomix 打包输出文件以供 AI 分析

• 参数：
  • path：包含 repomix-output.xml 的目录路径，或直接指向已打包仓库 XML 文件的路径
  • topFilesLength：（可选，默认：10）在指标摘要中按大小显示的最大文件数量
• 功能：
  • 可接受包含 repomix-output.xml 的目录，或直接指向 XML 文件的路径
  • 在 MCP 服务器中注册该文件，并返回与 pack_codebase 工具相同的结构
  • 无需重新处理即可安全访问现有打包输出
  • 适用于处理先前生成的打包仓库

3. pack_remote_repository：获取、克隆并将 GitHub 仓库打包为 consolidated XML 文件，供 AI 分析

• 参数：
  • remote：GitHub 仓库 URL 或 user/repo 格式（例如 "yamadashy/repomix"、"https://github.com/user/repo" 或 "https://github.com/user/repo/tree/branch"）
  • compress：（可选，默认：false）启用 Tree-sitter 压缩，提取核心代码签名与结构，同时移除实现细节。可在保留语义的同时将 token 使用量降低约 70%。由于 grep_repomix_output 支持增量检索内容，通常无需启用；仅当你明确需要大型仓库的完整代码库内容时才使用。
  • includePatterns：（可选）使用 fast-glob 模式指定要包含的文件。多个模式可用逗号分隔（例如 "**/*.{js,ts}"、"src/**,docs/**"）。仅处理匹配的文件。
  • ignorePatterns：（可选）使用 fast-glob 模式指定要额外排除的文件。多个模式可用逗号分隔（例如 "test/**,*.spec.js"、"node_modules/**,dist/**"）。这些模式是对 .gitignore、.ignore 及内置排除规则的补充。
  • outputPatterns：（可选）按文件设置包含级别，与配置文件中的 output.patterns 选项对应。为 { pattern, compress?, directoryStructureOnly? } 条目数组；首个匹配的模式生效，directoryStructureOnly 优先于 compress，若匹配项两者皆未设置则强制包含完整内容（可用于将文件从全局 compress 中豁免）。
  • topFilesLength：（可选，默认：10）在代码库分析的指标摘要中，按大小显示的最大文件数量。

4. read_repomix_output：读取 Repomix 生成的输出文件内容。支持通过指定行范围对部分读取，适用于大文件。

• 参数：
  • outputId：要读取的 Repomix 输出文件 ID
  • startLine：（可选）起始行号（从 1 开始，含该行）。未指定时从文件开头读取。
  • endLine：（可选）结束行号（从 1 开始，含该行）。未指定时读取至文件末尾。
• 功能特性：
  • 专为 Web 环境或沙箱应用设计
  • 通过 ID 获取先前生成输出的内容
  • 无需文件系统访问即可安全访问已打包的代码库
  • 支持对大文件进行部分读取

5. grep_repomix_output：使用类 grep 功能在 Repomix 输出文件中搜索模式，支持 JavaScript RegExp 语法

• 参数：
  • outputId：要搜索的 Repomix 输出文件 ID
  • pattern：搜索模式（JavaScript RegExp 正则表达式语法）
  • contextLines：（可选，默认：0）每个匹配前后显示的上下文行数。若指定了 beforeLines/afterLines 则被覆盖。
  • beforeLines：（可选）每个匹配之前显示的上下文行数（类似 grep -B）。优先于 contextLines。
  • afterLines：（可选）每个匹配之后显示的上下文行数（类似 grep -A）。优先于 contextLines。
  • ignoreCase：（可选，默认：false）执行不区分大小写的匹配
• 功能特性：
  • 使用 JavaScript RegExp 语法进行强大的模式匹配
  • 支持上下文行以便更好理解匹配结果
  • 可分别控制匹配前后的上下文行数
  • 提供区分大小写与不区分大小写的搜索选项

6. file_system_read_file：使用绝对路径从本地文件系统读取文件。内置安全校验，可检测并阻止访问包含敏感信息的文件。

• 参数：
  • path：要读取文件的绝对路径
• 安全特性：
  • 使用 Secretlint 实现安全校验
  • 阻止访问包含敏感信息的文件（API 密钥、密码、密钥等）
  • 校验绝对路径以防止目录遍历攻击

7. file_system_read_directory：使用绝对路径列出目录内容。返回格式化的列表，清晰标示文件和子目录。

• 参数：
  • path：要列出内容的目录绝对路径
• 功能特性：
  • 以清晰标识显示文件和目录（[FILE] 或 [DIR]）
  • 提供安全的目录遍历及完善的错误处理
  • 校验路径并确保其为绝对路径
  • 适用于探索项目结构并理解代码库组织

Claude Code 插件

Repomix 为 Claude Code 提供官方插件，可与 AI 驱动的开发环境无缝集成。

安装

1. 添加 Repomix 插件市场：

/plugin marketplace add yamadashy/repomix

2. 安装插件：

# Install MCP server plugin (recommended foundation)
/plugin install repomix-mcp@repomix

# Install commands plugin (extends functionality)
/plugin install repomix-commands@repomix

# Install repository explorer plugin (AI-powered analysis)
/plugin install repomix-explorer@repomix

注意：建议将 repomix-mcp 插件作为基础。repomix-commands 插件提供便捷的斜杠命令，repomix-explorer 则增加 AI 驱动的分析能力。你可以单独安装它们，但安装全部三个可获得最完整的体验。

或者，使用交互式插件安装器：

/plugin

这将打开交互式界面，你可以浏览并安装可用插件。

可用插件

1. repomix-mcp（MCP 服务器插件）

基础插件，通过 MCP 服务器集成提供 AI 驱动的代码库分析。

功能特性：

• 打包本地和远程仓库
• 搜索已打包的输出
• 读取文件并内置安全扫描（Secretlint）
• 自动 Tree-sitter 压缩（约 70% token 减少）

2. repomix-commands（斜杠命令插件）

提供便捷的斜杠命令，支持自然语言快速操作。

可用命令：

• /repomix-commands:pack-local - 使用多种选项打包本地代码库
• /repomix-commands:pack-remote - 打包并分析远程 GitHub 仓库

使用示例：

/repomix-commands:pack-local
Pack this project as markdown with compression

/repomix-commands:pack-remote yamadashy/repomix
Pack only TypeScript files from the yamadashy/repomix repository

3. repomix-explorer（AI 分析 Agent 插件）

AI 驱动的仓库分析 Agent，使用 Repomix CLI 智能探索代码库。

功能特性：

• 自然语言代码库探索与分析
• 智能模式发现与代码结构理解
• 使用 grep 和目标文件读取进行增量分析
• 针对大型仓库的自动上下文管理

可用命令：

• /repomix-explorer:explore-local - 在 AI 辅助下分析本地代码库
• /repomix-explorer:explore-remote - 在 AI 辅助下分析远程 GitHub 仓库

使用示例：

/repomix-explorer:explore-local ./src
Find all authentication-related code

/repomix-explorer:explore-remote facebook/react
Show me the main component architecture

Agent 会自动：

1. 运行 npx repomix@latest 打包仓库
2. 使用 Grep 和 Read 工具高效搜索输出
3. 提供全面分析，同时避免消耗过多上下文

优势

• 无缝集成：Claude 可直接分析代码库，无需手动准备
• 自然语言：使用对话式命令，无需记忆 CLI 语法
• 始终最新：自动使用 npx repomix@latest 获取最新功能
• 内置安全：自动 Secretlint 扫描防止敏感数据泄露
• Token 优化：针对大型代码库的 Tree-sitter 压缩

更多详情，请参阅 .claude/plugins/ 目录中的插件文档。

Agent Skills 生成

Repomix 可生成 Claude Agent Skills 格式输出，创建结构化的 Skills 目录，可作为 AI 助手的可复用代码库参考。当你需要引用远程仓库中的实现时，此功能尤为强大。

基本用法

# Generate Skills from local directory
repomix --skill-generate

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

# Generate with a custom project name in Skills descriptions
repomix --skill-generate --skill-project-name "My Project"

# Generate from remote repository
repomix --remote https://github.com/user/repo --skill-generate

运行命令后，Repomix 会提示你选择 Skills 的保存位置：

1. Personal Skills（~/.claude/skills/）- 在你本机的所有项目中可用
2. Project Skills（.claude/skills/）- 通过 git 与团队共享

非交互式用法

对于 CI 流水线和自动化脚本，可使用 --skill-output 和 --force 跳过所有交互式提示：

# Specify output directory directly
repomix --skill-generate --skill-output ./my-skills

# Skip overwrite confirmation with --force
repomix --skill-generate --skill-output ./my-skills --force

# Full non-interactive example
repomix --remote user/repo --skill-generate my-skill --skill-output ./output --force

生成的结构

Skills 按以下结构生成：

.claude/skills/<skill-name>/
├── SKILL.md                 # Main Skills metadata & documentation
└── references/
    ├── summary.md           # Purpose, format, and statistics
    ├── project-structure.md # Directory tree with line counts
    ├── files.md             # All file contents (grep-friendly)
    └── tech-stacks.md       # Languages, frameworks, dependencies

包含内容

• SKILL.md：包含 Skills 元数据、文件/行/token 计数、概览及使用说明
• summary.md：说明 Skills 的用途、使用指南，并按文件类型和语言提供统计明细
• project-structure.md：目录树及各文件行数，便于快速定位文件
• files.md：所有文件内容，带语法高亮标题，针对 grep 友好搜索进行了优化
• tech-stacks.md：根据依赖文件自动检测各软件包的技术栈（package.json、requirements.txt、Cargo.toml 等）

自动生成的 Skills 名称

如果未提供名称，Repomix 会自动生成一个：

repomix src/ --skill-generate                # → repomix-reference-src
repomix --remote user/repo --skill-generate  # → repomix-reference-repo
repomix --skill-generate CustomName          # → custom-name (normalized to kebab-case)

与 Repomix 功能的集成

Skills 生成遵循所有标准 Repomix 选项：

# Generate Skills with file filtering
repomix --skill-generate --include "src/**/*.ts" --ignore "**/*.test.ts"

# Generate Skills with compression
repomix --skill-generate --compress

# Generate Skills from remote repository
repomix --remote yamadashy/repomix --skill-generate

Repomix Explorer Skill（Agent Skills）

Repomix 提供了一个开箱即用的 Repomix Explorer skill，使 AI 编程助手能够使用 Repomix CLI 分析和探索代码库。该 skill 可与多种 AI 工具配合使用，包括 Claude Code、Cursor、Codex、GitHub Copilot 等。

快速安装

对于 Claude Code，安装官方 Repomix Explorer 插件：

/plugin marketplace add yamadashy/repomix
/plugin install repomix-explorer@repomix

对于 Codex、Cursor、OpenClaw 及其他兼容 Agent Skills 的助手，使用 Skills CLI 安装独立 skill：

npx skills add yamadashy/repomix --skill repomix-explorer

要针对特定助手，请传入 --agent：

npx skills add yamadashy/repomix --skill repomix-explorer --agent codex
npx skills add yamadashy/repomix --skill repomix-explorer --agent openclaw

对于 Hermes Agent，使用 Hermes Agent 原生的 skills 命令安装单文件 skill：

hermes skills install https://raw.githubusercontent.com/yamadashy/repomix/main/skills/repomix-explorer/SKILL.md

功能说明

安装完成后，你可以使用自然语言指令分析代码库。

分析远程仓库：

"What's the structure of this repo?
https://github.com/facebook/react"

探索本地代码库：

"What's in this project?
~/projects/my-app"

这不仅有助于理解代码库，还适用于你想通过参考其他仓库来实现功能时。

⚙️ 配置

Repomix 支持多种配置文件格式，兼具灵活性与易用性。

配置文件格式

Repomix 会按以下优先级顺序自动查找配置文件：

1. TypeScript（repomix.config.ts、repomix.config.mts、repomix.config.cts）
2. JavaScript/ES Module（repomix.config.js、repomix.config.mjs、repomix.config.cjs）
3. JSON（repomix.config.json5、repomix.config.jsonc、repomix.config.json）

JSON 配置

在项目根目录创建 repomix.config.json 文件：

repomix --init

这将创建一个带有默认设置的 repomix.config.json 文件。

TypeScript 配置

TypeScript 配置文件可提供最佳开发体验，具备完整类型检查与 IDE 支持。

安装：

要在 defineConfig 中使用 TypeScript 或 JavaScript 配置，你需要将 Repomix 安装为开发依赖：

npm install -D repomix

示例：

// repomix.config.ts
import { defineConfig } from 'repomix';

export default defineConfig({
  output: {
    filePath: 'output.xml',
    style: 'xml',
    removeComments: true,
  },
  ignore: {
    customPatterns: ['**/node_modules/**', '**/dist/**'],
  },
});

优势：

• ✅ 在 IDE 中享受完整的 TypeScript 类型检查
• ✅ 出色的 IDE 自动补全与 IntelliSense
• ✅ 可使用动态值（时间戳、环境变量等）

动态值示例：

// repomix.config.ts
import { defineConfig } from 'repomix';

// Generate timestamp-based filename
const timestamp = new Date().toISOString().slice(0, 19).replace(/[:.]/g, '-');

export default defineConfig({
  output: {
    filePath: `output-${timestamp}.xml`,
    style: 'xml',
  },
});

JavaScript 配置

JavaScript 配置文件与 TypeScript 用法相同，支持 defineConfig 和动态值。

配置选项

以下是配置选项说明：

选项	说明	默认值
input.maxFileSize	要处理的最大文件大小（字节）。超过此大小的文件将被跳过	50000000
input.processors	在打包前运行外部命令以转换匹配文件的 { pattern, command, timeout?, onError? } 条目有序数组（例如 JSON→TOON）。首个匹配的 glob 生效。由于会执行任意命令，因此仅用于本地 CLI 运行（以及带有 --remote-trust-config 的远程仓库）。参见 File Processors	未设置
output.filePath	输出文件的名称	"repomix-output.xml"
output.style	输出样式（xml、markdown、json、plain）	"xml"
output.filePathStyle	输出中文件路径的显示方式（target-relative 使路径相对于各目标根目录，cwd-relative 使路径相对于当前工作目录）	"target-relative"
output.parsableStyle	是否根据所选样式 schema 对输出进行转义。注意这可能会增加 token 数量。	false
output.compress	是否执行智能代码提取以降低 token 数量	false
output.patterns	逐文件包含级别。{ pattern, compress?, directoryStructureOnly? } 条目的有序数组；首个匹配的 glob 生效，并覆盖该文件的全局 output.compress。参见 Per-file Inclusion Levels	未设置
output.headerText	要包含在文件头部的自定义文本	null
output.instructionFilePath	包含详细自定义说明的文件路径	null
output.fileSummary	是否在输出开头包含摘要部分	true
output.directoryStructure	是否在输出中包含目录结构	true
output.files	是否在输出中包含文件内容	true
output.removeComments	是否从支持的文件类型中移除注释	false
output.removeEmptyLines	是否从输出中移除空行	false
output.showLineNumbers	是否为输出中的每一行添加行号	false
output.truncateBase64	是否截断较长的 base64 数据字符串（例如图片）以降低 token 数量	false
output.copyToClipboard	除保存文件外，是否将输出复制到系统剪贴板	false
output.splitOutput	按每部分最大大小将输出拆分为多个编号文件（例如 1000000 对应约 1MB）。确保每个文件不超过限制，并避免将文件拆分到多个部分	未设置
output.topFilesLength	摘要中显示的排名靠前文件数量。若设为 0，则不显示摘要	5
output.tokenCountTree	是否显示带有 token 计数摘要的文件树。可为布尔值或数字（最低 token 计数阈值）	false
output.tokenBudget	当打包输出超过此 token 数量时以非零退出码失败。作为 CI/agent 上下文限制的防护；输出仍会生成	未设置
output.includeEmptyDirectories	是否在仓库结构中包含空目录	false
output.includeFullDirectoryStructure	使用 include 模式时，是否显示完整目录树（同时遵守忽略模式），但仍仅处理包含的文件。为 AI 分析提供完整仓库上下文	false
output.git.sortByChanges	是否按 git 变更次数对文件排序（变更次数较多的文件显示在底部）	true
output.git.sortByChangesMaxCommits	分析 git 变更时最多分析的提交数量	100
output.git.includeDiffs	是否在输出中包含 git diff（分别包含工作树和暂存区变更）	false
output.git.includeLogs	是否在输出中包含 git 日志（包含日期、消息和文件路径的提交历史）	false
output.git.includeLogsCount	要包含的 git 日志提交数量	50
include	要包含的文件模式（使用 glob patterns)	[]
ignore.useGitignore	是否使用项目 .gitignore 文件中的模式	true
ignore.useDotIgnore	是否使用项目 .ignore 文件中的模式	true
ignore.useDefaultPatterns	是否使用默认忽略模式	true
ignore.customPatterns	额外要忽略的模式（使用 glob patterns)	[]
security.enableSecurityCheck	是否对文件执行安全检查	true
tokenCount.encoding	用于 OpenAI 兼容分词的 token 计数编码（例如 o200k_base 用于 GPT-4o，cl100k_base 用于 GPT-4/3.5）。由 gpt-tokenizer. 提供支持	"o200k_base"

配置文件支持 JSON5 语法，允许：

• 注释（单行与多行）
• 对象与数组中的尾随逗号
• 不加引号的属性名
• 更宽松的字符串语法

Schema 校验

你可以在配置文件中添加 $schema 属性以启用 schema 校验：

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml"
  }
}

在支持 JSON schema 的编辑器中，这将提供自动补全与校验。

配置示例

示例配置：

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "input": {
    "maxFileSize": 50000000,
    // Optional: transform matching files with an external command before packing (local CLI only)
    // "processors": [
    //   { "pattern": "**/*.json", "command": "npx @toon-format/cli {file}" }
    // ]
  },
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml",
    "filePathStyle": "target-relative",
    "parsableStyle": false,
    "compress": false,
    // Optional: override the inclusion level per glob (first match wins)
    // "patterns": [
    //   { "pattern": "docs/**/*", "compress": true },
    //   { "pattern": "website/**/*", "directoryStructureOnly": true }
    // ],
    "headerText": "Custom header information for the packed file.",
    "fileSummary": true,
    "directoryStructure": true,
    "files": true,
    "removeComments": false,
    "removeEmptyLines": false,
    "topFilesLength": 5,
    "tokenCountTree": false, // or true, or a number like 10 for minimum token threshold
    // "tokenBudget": 180000, // optional: fail when the packed output exceeds this many tokens
    "showLineNumbers": false,
    "truncateBase64": false,
    "copyToClipboard": false,
    // "splitOutput": 1000000, // optional: split output into multiple ~1MB files
    "includeEmptyDirectories": false,
    "git": {
      "sortByChanges": true,
      "sortByChangesMaxCommits": 100,
      "includeDiffs": false,
      "includeLogs": false,
      "includeLogsCount": 50
    }
  },
  "include": ["**/*"],
  "ignore": {
    "useGitignore": true,
    "useDefaultPatterns": true,
    // Patterns can also be specified in .repomixignore
    "customPatterns": [
      "additional-folder",
      "**/*.log"
    ],
  },
  "security": {
    "enableSecurityCheck": true
  },
  "tokenCount": {
    "encoding": "o200k_base"
  }
}

全局配置

创建全局配置文件：

repomix --init --global

全局配置文件将创建在：

• Windows：%LOCALAPPDATA%\Repomix\repomix.config.json
• macOS/Linux：$XDG_CONFIG_HOME/repomix/repomix.config.json 或 ~/.config/repomix/repomix.config.json

注意：本地配置（若存在）优先于全局配置。

包含与忽略

包含模式

Repomix 现已支持使用 glob 模式. 指定要包含的文件，从而实现更灵活、更强大的文件选择：

• 使用 **/*.js 包含任意目录下的所有 JavaScript 文件
• 使用 src/**/* 包含 src 目录及其子目录下的所有文件
• 组合多个模式，例如 ["src/**/*.js", "**/*.md"]，以包含 src 中的 JavaScript 文件以及所有 Markdown 文件

忽略模式

Repomix 提供多种方式设置忽略模式，以便在打包过程中排除特定文件或目录：

• .gitignore：默认使用项目 .gitignore 文件与 .git/info/exclude 中列出的模式。可通过 ignore.useGitignore 设置或 --no-gitignore CLI 选项控制此行为。
• .ignore：可在项目根目录使用 .ignore 文件，格式与 .gitignore 相同。ripgrep、silver searcher 等工具会遵循该文件，从而减少维护多份忽略文件的需要。可通过 ignore.useDotIgnore 设置或 --no-dot-ignore CLI 选项控制此行为。
• 默认模式：Repomix 内置一份常用排除文件与目录的默认列表（例如 node_modules、.git、二进制文件）。可通过 ignore.useDefaultPatterns 设置或 --no-default-patterns CLI 选项控制。更多细节请参阅 defaultIgnore.ts。
• .repomixignore：可在项目根目录创建 .repomixignore 文件，定义 Repomix 专用的忽略模式。该文件格式与 .gitignore 相同。
• 自定义模式：可在配置文件中使用 ignore.customPatterns 选项指定额外的忽略模式。也可通过 -i, --ignore 命令行选项覆盖该设置。

优先级顺序（从高到低）：

1. 自定义模式（ignore.customPatterns）
2. 忽略文件（.repomixignore、.ignore、.gitignore 与 .git/info/exclude）：
   • 在嵌套目录中，更深层目录中的文件优先级更高
   • 在同一目录中，这些文件会合并，无特定顺序
3. 默认模式（当 ignore.useDefaultPatterns 为 true 且未使用 --no-default-patterns 时）

这种方式可根据项目需求灵活配置文件排除规则。通过排除安全敏感文件与大型二进制文件，有助于优化生成打包文件的大小，并防止机密信息泄露。

注意：二进制文件默认不会包含在打包输出中，但其路径会列在输出文件的「Repository Structure」部分。这样既能完整呈现仓库结构概览，又能保持打包文件高效且以文本为主。

自定义指令

output.instructionFilePath 选项允许你指定一个单独的文件，其中包含关于项目的详细说明或上下文。这使 AI 系统能够理解项目的具体背景与需求，从而可能获得更相关、更贴合的分析或建议。

以下是使用该功能的一种示例：

1. 在项目根目录创建名为 repomix-instruction.md 的文件：

# Coding Guidelines

- Follow the Airbnb JavaScript Style Guide
- Suggest splitting files into smaller, focused units when appropriate
- Add comments for non-obvious logic. Keep all text in English
- All new features should have corresponding unit tests

# Generate Comprehensive Output

- Include all content without abbreviation, unless specified otherwise
- Optimize for handling large codebases while maintaining output quality

2. 在 repomix.config.json 中添加 instructionFilePath 选项：

{
  "output": {
    "instructionFilePath": "repomix-instruction.md",
    // other options...
  }
}

当 Repomix 生成输出时，会将 repomix-instruction.md 的内容包含在专用章节中。

注意：指令内容会追加在输出文件末尾。这种放置方式对 AI 系统可能特别有效。若你想了解为何这样做可能有益，Anthropic 在其文档中提供了一些见解：
https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips

Put long-form data at the top: Place your long documents and inputs (~20K+ tokens) near the top of your prompt, above your query, instructions, and examples. This can significantly improve Claude's performance across all models. Queries at the end can improve response quality by up to 30% in tests, especially with complex, multi-document inputs.

注释移除

当 output.removeComments 设置为 true 时，Repomix 会尝试从受支持的文件类型中移除注释。该功能有助于减小输出文件体积，并聚焦于核心代码内容。

支持的语言包括：
HTML、CSS、JavaScript、TypeScript、Vue、Svelte、Python、PHP、Ruby、C、C#、Java、Go、Rust、Swift、Kotlin、Dart、Shell， 以及 YAML。

注意：注释移除过程采用保守策略，以避免误删代码。在复杂情况下，部分注释可能会被保留。

文件处理器

input.processors 会在打包之前运行外部命令来转换文件内容。每条配置通过 glob 匹配目标文件（匹配方式与 include/ignore 相同），并用命令的标准输出替换匹配文件的内容——适用于减少 token 或进行格式转换，例如 JSON→TOON, SVG 压缩，或 notebook→script 转换。

{
  "input": {
    "processors": [
      { "pattern": "**/*.json", "command": "npx @toon-format/cli {file}" }
    ]
  }
}

必需的 {file} 占位符会被替换为包含文件内容的临时文件，命令的 stdout 则成为新内容。模式按顺序求值，首个匹配生效（每个文件仅一个处理器）。每条配置还可接受 timeout（毫秒，默认 60000）和 onError（"fail" 中止打包，默认；"skip" 发出警告并保留原始内容）。

示例命令（每条都是一个 command 值，搭配合适的 pattern）：

Pattern	command	作用
**/*.json	jq -c . {file}	通过去除空白字符压缩 JSON
**/*.json	npx @toon-format/cli {file}	将 JSON 转换为 TOON,，一种紧凑且省 token 的格式
**/*.svg	npx svgo -i {file} -o -	压缩 SVG
**/*.ipynb	jupyter nbconvert --to script --stdout {file}	将 Jupyter notebook 转换为纯 Python 脚本

每个文件仅应用一个处理器（首个匹配生效），并确保其调用的工具位于你的 PATH 上（基于 npx 的命令会在首次使用时下载）。

Warning

文件处理器会运行配置文件中的任意命令，因此默认拒绝执行：

• 仅在本地 CLI 运行时启用，此时 Repomix 假定工作目录中的配置是你自己的——与 npm script 或 Makefile 具有相同的信任边界。与这些工具一样，如果你在他人的仓库中运行 repomix，却未先审查其 repomix.config.json，其中的处理器命令就会在你的机器上执行。打包不受信任的仓库前，请先审查其配置。
• 对库 API（pack() / runCli()）、MCP 服务器以及托管的 repomix.com. 禁用。
• 对于远程仓库（--remote），仅当你显式传入 --remote-trust-config 时，克隆下来的配置及其处理器才会被信任；未传入时，远程配置甚至不会被加载。

启动时和错误消息中会打印活跃的处理器，因此请通过环境变量引用凭据（例如 $TOKEN），这些变量会以未展开的形式记录，而不是直接内联。超时时 Repomix 会终止命令的 shell，但会自行派生长生命周期后台进程的命令可能仍会留下运行中的进程。详见配置指南。

🔍 安全检查

Repomix 包含安全检查功能，使用 Secretlint 检测 文件中可能存在的敏感信息。该功能可帮助你在分享 打包后的仓库之前识别潜在的安全风险。

安全检查结果会在打包流程完成后显示在 CLI 输出中。如果检测到任何可疑 文件，你会看到这些文件的列表以及警告消息。

示例输出：

🔍 Security Check:
──────────────────
2 suspicious file(s) detected:
1. src/utils/test.txt
2. tests/utils/secretLintUtils.test.ts

Please review these files for potentially sensitive information.

默认情况下，Repomix 的安全检查功能处于启用状态。你可以在配置文件中将 security.enableSecurityCheck 设置为 false 来禁用它：

{
  "security": {
    "enableSecurityCheck": false
  }
}

或使用 --no-security-check 命令行选项：

repomix --no-security-check

Note

禁用安全检查可能会暴露敏感信息。请谨慎使用此选项，并仅在必要时使用，例如 处理包含示例凭据的测试文件或文档时。

🤖 在 GitHub Actions 中使用 Repomix

你也可以在 GitHub Actions 工作流中使用 Repomix。这有助于自动化打包代码库以供 AI 分析。

基本用法：

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.xml
    style: xml

使用 --style 生成不同格式的输出：

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.md
    style: markdown

- name: Pack repository with Repomix (JSON format)
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.json
    style: json

打包指定目录并启用压缩：

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    directories: src tests
    include: "**/*.ts,**/*.md"
    ignore: "**/*.test.ts"
    output: repomix-output.txt
    compress: true

将输出文件上传为构件（artifact）：

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    directories: src
    output: repomix-output.txt
    compress: true

- name: Upload Repomix output
  uses: actions/upload-artifact@v7
  with:
    name: repomix-output
    path: repomix-output.txt

完整工作流示例：

name: Pack repository with Repomix

on:
  workflow_dispatch:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  pack-repo:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Pack repository with Repomix
        uses: yamadashy/repomix/.github/actions/repomix@main
        with:
          output: repomix-output.xml

      - name: Upload Repomix output
        uses: actions/upload-artifact@v7
        with:
          name: repomix-output.xml
          path: repomix-output.xml
          retention-days: 30

完整工作流示例见此处.

Action 输入

名称	说明	默认值
directories	以空格分隔的要处理的目录列表（例如 src tests docs）	.
include	以逗号分隔的 glob 模式，用于包含文件（例如 **/*.ts,**/*.md）	""
ignore	以逗号分隔的 glob 模式，用于忽略文件（例如 **/*.test.ts,**/node_modules/**）	""
output	打包文件的相对路径（扩展名决定格式：.txt、.md、.xml）	repomix-output.xml
compress	启用智能压缩，通过裁剪实现细节来减小输出体积	true
style	输出样式（xml、markdown、json、plain）	xml
additional-args	传给 repomix CLI 的额外原始参数（例如 --no-file-summary --no-security-check）	""
repomix-version	要安装的 npm 包版本（支持 semver 范围、标签或特定版本，例如 0.2.25）	latest

Action 输出

名称	说明
output_file	生成的输出文件路径。可在后续步骤中用于构件上传、LLM 处理或其他操作。该文件根据指定选项包含代码库的格式化表示。

📚 将 Repomix 作为库使用

除了将 Repomix 作为 CLI 工具使用外，你还可以在 Node.js 应用中以库的形式使用它。

安装

npm install repomix

基本用法

import { runCli, type CliOptions } from 'repomix';

// Process current directory with custom options
async function packProject() {
  const options = {
    output: 'output.xml',
    style: 'xml',
    compress: true,
    quiet: true
  } as CliOptions;
  
  const result = await runCli(['.'], process.cwd(), options);
  return result.packResult;
}

处理远程仓库

import { runCli, type CliOptions } from 'repomix';

// Clone and process a GitHub repo
async function processRemoteRepo(repoUrl) {
  const options = {
    remote: repoUrl,
    output: 'output.xml',
    compress: true
  } as CliOptions;
  
  return await runCli(['.'], process.cwd(), options);
}

使用核心组件

若需要更细粒度的控制，可使用底层 API：

import { searchFiles, collectFiles, processFiles, TokenCounter } from 'repomix';

async function analyzeFiles(directory) {
  // Find and collect files
  const { filePaths } = await searchFiles(directory, { /* config */ });
  const rawFiles = await collectFiles(filePaths, directory);
  const processedFiles = await processFiles(rawFiles, { /* config */ });
  
  // Count tokens
  const tokenCounter = new TokenCounter('o200k_base');
  
  // Return analysis results
  return processedFiles.map(file => ({
    path: file.path,
    tokens: tokenCounter.countTokens(file.content)
  }));
}

更多示例请查看 website/server/src/remoteRepo.ts 中的源码，其中演示了 repomix.com 如何使用该库。

打包

使用 Rolldown 或 esbuild 等工具打包 repomix 时，部分依赖必须保持 external（外部化），且需要复制 WASM 文件：

外部依赖（不可打包）：

• tinypool - 通过文件路径启动 worker 线程

需要复制的 WASM 文件：

• web-tree-sitter.wasm → 与打包后的 JS 位于同一目录（代码压缩功能所需）
• Tree-sitter 语言文件 → 由 REPOMIX_WASM_DIR 环境变量指定的目录

完整示例见 website/server/scripts/bundle.mjs.

🌍 社区项目

探索 Repomix 社区打造的精彩项目！

• Repomix Runner - 用于将文件打包为单一输出以供 AI 处理的 VSCode 扩展
• Repomix Desktop - 使用 Python 和 CustomTkinter 构建的 Repomix 图形界面桌面应用
• Python Repomix - 基于 AST 压缩的 Python 实现
• Rulefy - 使用 Claude AI 将 GitHub 仓库转换为自定义 Cursor AI 规则
• Codebase MCP - 使用 Repomix 进行 AI 驱动代码库分析的 MCP 服务器
• vibe-tools - 面向 AI 代理的 CLI 工具集，支持网页搜索、仓库分析与浏览器自动化

了解更多，请访问我们的 社区项目页面.

🤝 贡献

欢迎社区贡献！入门请参阅我们的 贡献指南。

贡献者

🔒 隐私政策

请参阅我们的 隐私政策.

📜 许可证

本项目采用 MIT License 许可。

    返回顶部