We live in an absurd golden era of context windows. Frontier models happily digest one to two million tokens in a single gulp, yet the average developer's workflow for feeding a local project into Claude or Gemini remains deeply primitive. Most of us still spend twenty minutes playing copy-paste roulette across thirty editor tabs, inadvertently missing a critical interface definition and accidentally pasting our local .env file directly into a cloud chat window.
Repomix (formerly Repopack), created by Kazuki Yamada, cleanly eliminates this indignity. It is a purpose-built CLI tool that scans your local repository, strips out binary noise, runs security checks for exposed credentials, computes token counts, and packages your entire directory structure into a single structured XML, Markdown, or plain text file.
What Is Repomix?
[Local Codebase] ──> [Filter & Secret Scan] ──> [Tree-Sitter / Tokeniser] ──> [repomix-output.xml]
│ │ │
.gitignore / tiktoken / Claude / Gemini /
Secretlint c100k_base OpenAI Ready
Repomix is an open-source CLI utility that consolidates multi-file codebases into a single, context-efficient document optimised for Large Language Models (LLMs). It processes directory structures, respects ignore rules, strips sensitive credentials via integrated security audits, and structures outputs using model-friendly delimiters like XML tags.
Key Technical Capabilities
- Semantic Formatting: Generates structured XML (Claude's preferred prompt format) or clean Markdown with file-tree headers.
- Native Secret Scanning: Leverages Secretlint under the hood to prevent accidental API key leaks before generation completes.
- Tree-Sitter Compression: Optional parsing to extract signatures and interfaces while removing boilerplate implementation logic.
- Token Budgeting: Built-in token counting via
@dqbd/tiktokento check output against model context limits prior to upload. - Configurable Patterns: Fine-grained inclusion and exclusion patterns on top of existing
.gitignoremanifests.
Why XML Output Matters for Frontier LLMs
A common developer debate across GitHub discussions and YouTube technical breakdowns centres on whether to feed LLMs raw Markdown or XML. While Markdown is standard for human readers, models trained on prompt-engineering standards (particularly Anthropic's Claude series) parse nested XML tags with far higher retrieval fidelity.
Repomix generates an explicit hierarchy:
This file is a merged representation of the entire codebase, combined by Repomix.
<file_summary>
<purpose>This section provides a high-level overview of the repository.</purpose>
<directory_structure>
src/
index.ts
utils/
parser.ts
</directory_structure>
</file_summary>
<directory name="src">
<file name="utils/parser.ts">
export function parseConfig() { /* ... */ }
</file>
</directory>
This layout removes ambiguity. The model does not hallucinate whether a line of code belongs to an import snippet or a file definition, drastically improving multi-file reasoning, refactoring tasks, and global architecture reviews.
Repomix vs Traditional Ingestion Tools
| Feature | Repomix | Raw Bash / cat Scripts | Gitingest |
|---|---|---|---|
| Output Formats | XML, Markdown, Plain Text | Raw Text | Text, Markdown |
| Secret Scanning | Built-in (Secretlint) | None | None |
| Token Calculation | Real-time (Model specific) | None (External tool needed) | Approximate |
| Code Compression | Tree-sitter parsing | None | None |
| Monorepo Filtering | Built-in glob profiles | Manual find piping | Basic git filter |
| Offline Execution | Local Node.js binary | Native OS | Web or Docker |
Installation and CLI Quickstart
You can run Repomix on the fly without installing it globally, or hook it directly into your local development environment via npm, Homebrew, or Bun.
1. Instant Run via npx
Navigate to your project root and generate an AI pack in seconds:
npx repomix
This automatically outputs a repomix-output.xml file at your project root, accompanied by a terminal summary of processed files, ignored paths, and total token usage.
2. Global Installation
# Via npm
npm install -g repomix
# Via Homebrew (macOS/Linux)
brew install repomix
3. Custom Formats and Code Compression
If you want to produce a lightweight prompt containing only interface contracts and function signatures (ideal for mapping large libraries without blowing past token allocations):
# Output clean Markdown instead of XML
repomix --style markdown
# Enable Tree-sitter code compression to extract structural outlines
repomix --compress
# Scan and print detailed token breakdown per file
repomix --token-count-encoding o200k_base
Custom Configuration: repomix.config.json
For large monorepos, running arbitrary CLI flags gets tedious. Repomix supports a local configuration file that checks into version control. Generate a default template:
repomix --init
Customise the generated repomix.config.json to lock in sensible defaults for your team:
{
"output": {
"filePath": "repomix-context.xml",
"style": "xml",
"headerText": "Production backend service. Prioritise TypeScript safety and functional patterns.",
"topFilesLength": 10,
"showLineNumbers": false,
"removeComments": false,
"removeEmptyLines": true
},
"include": [
"src/**/*.ts",
"prisma/schema.prisma"
],
"ignore": {
"useGitignore": true,
"useDefaultPatterns": true,
"customPatterns": [
"**/*.test.ts",
"**/__mocks__/**",
"dist/**"
]
},
"security": {
"enableSecurityCheck": true
}
}
Key Takeaways for Builders
- Zero-Friction Context Loading: Converts hours of manually assembling code snippets into a five-second CLI invocation.
- Safer Prompting: Halts execution if API credentials, private keys, or high-entropy secrets are detected in your source files.
- Tailored for XML Reasoning: Provides the exact structural demarcations required for high-accuracy reasoning in Claude 3.5 Sonnet and Gemini 1.5 Pro.
- Repository-Native: Runs locally across private offline codebases with no third-party telemetry or cloud parsing requirements.