Repomix

Repomix - Codebase Packing for AI

Pack your entire repository into a single, AI-friendly file optimized for LLMs like Claude, ChatGPT, Gemini, and more.

When to Use This Skill

• Feeding codebase to AI for analysis or refactoring
• Generating comprehensive code reviews
• Creating documentation from code
• Preparing context for AI-assisted development
• Analyzing remote repositories without cloning
• Token counting for LLM context limits

Quick Start

# 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

Default output: ./repomix-output.xml in current directory

Examples

Example: Prepare codebase for Claude review

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

Example: Analyze remote repo without cloning

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

Example: Prepare PR diff for review

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

Example: Check token usage before sending to AI

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

Example: Generate skills reference from library

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

Output Formats

# 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 Optimization

LLM Context Limits Reference

Model	Context Window	Typical Repo Fit
Claude 3.5/Opus	200K tokens	Large monorepos
GPT-4 Turbo/4o	128K tokens	Medium projects
Gemini 1.5 Pro	1M tokens	Very large codebases
Gemini 1.5 Flash	1M tokens	Very large codebases

Token Analysis

# 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

File Selection

Include Patterns

# 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 Patterns

# 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"

Stdin Input

# 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

Common Workflows

PR Review Preparation

# 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

Architecture Analysis

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

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

Documentation Generation

# 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

Dependency Analysis

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

Remote Repositories

# 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

Code Compression

Tree-sitter powered compression extracts signatures while removing implementation details.

Supported Languages

Tree-sitter compression works with: JavaScript, TypeScript, Python, Ruby, Go, Rust, Java, C, C++, C#, PHP, Swift, Kotlin, and more.

Usage

npx repomix --compress

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

Before compression:

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

After compression:

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

Git Integration

# 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

Configuration

Initialize Config

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

# Global config
npx repomix --init --global

Configuration File

{
  "$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 Usage

# 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 Server Integration

Run as Model Context Protocol server for AI assistants:

npx repomix --mcp

Configure for Claude Code

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

Available MCP Tools

When running as MCP server, provides:

Tool	Description
pack_codebase	Pack local directory into AI-friendly format
pack_remote_repository	Pack GitHub repository without cloning
read_repomix_output	Read contents of generated output file
file_system_tree	Get directory tree structure

Claude Agent Skills Generation

Generate skills format output for 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 Options Reference

Option	Description
-o, --output <file>	Output file path
--style <style>	Output format: xml, markdown, json, plain
--compress	Enable Tree-sitter compression
--include <patterns>	Include files matching glob patterns
-i, --ignore <patterns>	Exclude files matching patterns
--remote <url>	Process remote repository
--remote-branch <name>	Branch, tag, or commit for remote
--stdin	Read file paths from stdin
--copy	Copy output to clipboard
--token-count-tree	Show token counts per file
--split-output <size>	Split output by size (e.g., 1mb)
--include-logs	Include git commit history
--include-diffs	Include git diffs
--no-security-check	Skip sensitive data detection
--mcp	Run as MCP server
--skill-generate	Generate Claude skills format
--init	Create configuration file
--help	Show all available options

Troubleshooting

Issue	Solution
Output too large for LLM	Use --compress or filter with --include
Missing expected files	Check .repomixignore, .gitignore, and ignore patterns
Secrets detected (blocking)	Review flagged files; use --no-security-check if false positive
Memory issues on large repos	Use --split-output 1mb to chunk output
Remote repo access denied	Check URL format; ensure repo is public or use SSH
Compression not working	Verify language is supported by Tree-sitter
Output not in clipboard	Ensure clipboard access; try --output - | pbcopy on macOS

Ignore Files

Repomix respects multiple ignore sources (priority order):

1. ignore.customPatterns in config
2. .repomixignore (Repomix-specific)
3. .ignore (ripgrep compatible)
4. .gitignore
5. Default patterns (node_modules, .git, etc.)

Security

Repomix includes Secretlint for detecting sensitive information:

# Security check enabled by default
npx repomix

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

Detected secret types: API keys, tokens, passwords, private keys, AWS credentials, database connection strings, and more.

Best Practices

1. Use compression for large codebases to reduce token count (~70% reduction)
2. Filter with --include to focus on relevant files
3. Use --token-count-tree to identify large files before packing
4. Split output when hitting AI context limits
5. Include git logs for evolution context when needed
6. Use XML style for Claude (optimized for XML tags)
7. Use Markdown for human-readable output or other LLMs
8. Check token counts against your target LLM's context window
9. Review security warnings before sharing packed output

Requirements

• Node.js 18.0.0 or higher
• npm or npx available in PATH

Resources

• Website: https://repomix.com
• GitHub: https://github.com/yamadashy/repomix
• Chrome Extension: Repomix - Chrome Web Store
• VSCode Extension: Repomix Runner

---

Gotchas

• --compress strips function bodies but keeps signatures — great for architecture review, useless for "why is this function buggy" questions. The LLM literally cannot see the implementation.
• Security check blocks output entirely on detected secrets — even a single false-positive AWS-key-shaped string in a test fixture kills the run. Use --no-security-check only after reviewing the flagged files.
• .gitignore is respected but .dockerignore is not — your node_modules is excluded but the giant dist/ your Dockerfile ignores will be packed. Add a .repomixignore to match.
• Token counts are tiktoken-based (GPT) — Claude's tokenizer differs by ~10-20%. A repo reported as "180K tokens" can blow past Claude's 200K window or fit comfortably depending on content.
• --remote user/repo clones the default branch to a temp dir and runs locally — no GitHub API magic. Private repos require SSH keys configured; the error message just says "access denied" without explaining auth path.
• --stdin reads NUL or newline-separated paths and silently drops paths that don't exist or are outside the cwd. A typo in git diff --name-only output produces a smaller pack with no warning.
• --copy on macOS via pbcopy truncates at ~1MB in some terminal multiplexers (tmux without set-clipboard on). Verify the paste size before assuming the full output made it.