Agent Skills: Repomix - Codebase Packing for AI

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.