Skip to main content

Repomix - AI-Friendly Codebase Packer

Key Point: Pack your entire repository into a single AI-friendly file. Perfect for feeding codebases to Claude, ChatGPT, DeepSeek, and other LLMs for code review, documentation, and analysis.

🚀 Quick Start​

# Try instantly without installation
npx repomix@latest

# Or install globally
npm install -g repomix

# Pack current directory
repomix

# Pack specific directory
repomix path/to/directory

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

🎯 Core Features​

1. AI-Optimized Output​

Formats your codebase in a structured way that's easy for AI to understand and process.

2. Multiple Output Formats​

  • XML (default) - Best for AI comprehension with hierarchical structure
  • Markdown - Human-friendly and AI-parseable
  • JSON - Ideal for programmatic processing
  • Plain Text - Simple, universal format

3. Token Counting​

Provides token counts for each file and the entire repository, useful for LLM context limits.

4. Smart Compression​

Uses Tree-sitter to extract essential code structure, reducing token count by ~70% while preserving semantic meaning.

5. Git-Aware​

Automatically respects .gitignore, .ignore, and .repomixignore files.

📊 Output Formats​

XML Format (Default)​

repomix --style xml
<file_summary>
  (Metadata and usage AI instructions)
</file_summary>

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

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

<instruction>
(Custom instructions from instructionFilePath)
</instruction>

Markdown Format​

repomix --style markdown
# File Summary
(Metadata and usage AI instructions)

# Repository Structure
- src/
  - cli/
    - cliOutput.ts

# Repository Files
## File: src/index.js
(File contents)

JSON Format​

repomix --style json
{
  "fileSummary": {
    "generationHeader": "This file is a merged representation...",
    "purpose": "This file contains a packed representation...",
    "fileFormat": "The content is organized as follows...",
    "usageGuidelines": "- This file should be treated as read-only..."
  },
  "directoryStructure": "src/\n  cli/\n    cliOutput.ts",
  "files": {
    "src/index.js": "// File contents here"
  }
}

💡 Common Use Cases​

1. Code Review with AI​

repomix
# Send repomix-output.xml to ChatGPT with:
# "Review this codebase for security issues and suggest improvements"

2. Documentation Generation​

repomix --style markdown
# Prompt: "Generate comprehensive README.md based on this codebase"

3. Architecture Analysis​

repomix --compress
# Prompt: "Analyze the architecture and suggest refactoring opportunities"

4. Test Generation​

repomix --include "src/**/*.ts"
# Prompt: "Generate unit tests for all functions in this codebase"

5. Migration Planning​

repomix --remote https://github.com/old-project
# Prompt: "Create a migration plan to move this to a modern framework"

⚙️ Command Line Options​

Basic Options​

# Show version
repomix --version

# Enable detailed logging
repomix --verbose

# Suppress output
repomix --quiet

# Copy to clipboard
repomix --copy

Output Options​

# Custom output file
repomix -o custom-output.xml

# Output to stdout
repomix --stdout

# Different format
repomix --style markdown

# Compress output
repomix --compress

# Show line numbers
repomix --output-show-line-numbers

# Remove comments
repomix --remove-comments

# Remove empty lines
repomix --remove-empty-lines

# Split large output
repomix --split-output 20mb

File Selection​

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

# Ignore patterns
repomix --ignore "**/*.test.ts,docs/**"

# Don't use .gitignore
repomix --no-gitignore

# Don't use default patterns
repomix --no-default-patterns

Remote Repository​

# Clone and pack remote repo
repomix --remote https://github.com/user/repo

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

# Specific commit
repomix --remote user/repo --remote-branch abc123

# Using URL with branch
repomix --remote https://github.com/user/repo/tree/develop

Git Integration​

# Include git logs
repomix --include-logs

# Include git diffs
repomix --include-diffs

# Disable sort by changes
repomix --no-git-sort-by-changes

Token Management​

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

# Show only files with 1000+ tokens
repomix --token-count-tree 1000

# Set token encoding
repomix --token-count-encoding cl100k_base

🔧 Configuration​

Create Config File​

repomix --init

Example Configuration (repomix.config.json)​

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml",
    "compress": false,
    "removeComments": false,
    "removeEmptyLines": false,
    "showLineNumbers": false,
    "topFilesLength": 5
  },
  "include": ["**/*"],
  "ignore": {
    "useGitignore": true,
    "useDefaultPatterns": true,
    "customPatterns": [
      "**/*.log",
      "dist/**",
      "node_modules/**"
    ]
  },
  "tokenCount": {
    "encoding": "o200k_base"
  }
}

Global Configuration​

repomix --init --global

🎓 Advanced Features​

Code Compression​

Extract essential function and class signatures while removing implementation details:

repomix --compress

Before:

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;
}

interface Item {
  name: string;
  price: number;
  quantity: number;
}

After:

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

Token Count Optimization​

Visualize token usage across your project:

repomix --token-count-tree

Output:

🔢 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)

Split Output for Large Codebases​

repomix --split-output 1mb

Generates:

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

Custom Instructions​

Create repomix-instruction.md:

# Coding Guidelines
- Follow Airbnb JavaScript Style Guide
- Add comments for non-obvious logic
- All new features need unit tests

# Context
This is a TypeScript project using React and Node.js

Then configure:

{
  "output": {
    "instructionFilePath": "repomix-instruction.md"
  }
}

📚 Integration Examples​

Using with LLMs​

Claude​

repomix --style xml --compress
# Upload repomix-output.xml to Claude
# Prompt: "Analyze this codebase and suggest architectural improvements"

ChatGPT​

repomix --style markdown
# Copy to clipboard
repomix --copy
# Paste into ChatGPT with your prompt

DeepSeek​

repomix --style plain --compress
# Use for code analysis and suggestions

Using with GitHub Actions​

name: Pack repository with Repomix

on:
  workflow_dispatch:
  push:
    branches: [ main ]

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

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

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

Docker Usage​

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

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

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

MCP Server Integration​

Run as Model Context Protocol server:

repomix --mcp

Configure in Claude Desktop (claude_desktop_config.json):

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

🎯 Prompt Examples​

Code Review​

This file contains my entire codebase. Please review the overall structure 
and suggest improvements focusing on maintainability and scalability.

Documentation​

Based on this codebase, generate a detailed README.md that includes:
- Project overview
- Main features
- Setup instructions
- Usage examples

Test Generation​

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

Architecture Analysis​

Review the codebase for adherence to best practices and identify areas 
where the code could be improved in terms of readability, maintainability, 
and efficiency.

Library Overview​

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

🔗 Additional Resources​

Claude Code Plugins​

# Add Repomix plugin marketplace
/plugin marketplace add yamadashy/repomix

# Install MCP server plugin
/plugin install repomix-mcp@repomix

# Install commands plugin
/plugin install repomix-commands@repomix

# Install explorer plugin
/plugin install repomix-explorer@repomix

Agent Skills Generation​

# Generate Claude Agent Skills
repomix --skill-generate

# With custom name
repomix --skill-generate my-project-reference

# From remote repo
repomix --remote https://github.com/user/repo --skill-generate

Using as Library​

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

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;
}

🛠️ Best Practices​

1. Optimize Token Count​

# Use compression for large codebases
repomix --compress

# Exclude unnecessary files
repomix --ignore "**/*.test.ts,docs/**,dist/**"

# Check token distribution first
repomix --token-count-tree

2. Respect File Limits​

# Split output for AI tools with file size limits
repomix --split-output 1mb

# Remove comments and empty lines
repomix --remove-comments --remove-empty-lines

3. Include Context​

# Add git logs for history
repomix --include-logs

# Add git diffs for recent changes
repomix --include-diffs

# Add custom instructions
repomix --instruction-file-path instructions.md

4. Format for Use Case​

# XML for AI (best comprehension)
repomix --style xml

# Markdown for human review
repomix --style markdown

# JSON for programmatic processing
repomix --style json

5. Security Considerations​

# Enable security check (default)
repomix

# Disable only if necessary
repomix --no-security-check

# Review .repomixignore for sensitive files
echo "*.env" >> .repomixignore
echo "secrets/" >> .repomixignore

📊 Comparison with Alternatives​

FeatureRepomixManual Copy-PasteOther Tools
AI-Optimized✅ Native❌ No⚠️ Limited
Token Counting✅ Built-in❌ No❌ No
Multiple Formats✅ 4 formats❌ Plain text⚠️ 1-2 formats
Git Integration✅ Full❌ No⚠️ Limited
Compression✅ Smart❌ No❌ No
Remote Repos✅ Yes❌ No⚠️ Sometimes
MCP Support✅ Yes❌ No❌ No

Choose Repomix when:

  • You need AI-optimized codebase formatting
  • Token counting and optimization matter
  • Git context is important
  • You want multiple output formats
  • Remote repository support is needed

🔍 Troubleshooting​

Issue: Output Too Large​

# Solution 1: Use compression
repomix --compress

# Solution 2: Split output
repomix --split-output 1mb

# Solution 3: Include only necessary files
repomix --include "src/**/*.ts"

Issue: Too Many Tokens​

# Check token distribution
repomix --token-count-tree

# Remove high-token files
repomix --ignore "large-file.js"

# Use compression
repomix --compress

Issue: Sensitive Data Included​

# Add to .repomixignore
echo "*.env" >> .repomixignore
echo "config/secrets.json" >> .repomixignore

# Run security check
repomix

Issue: Remote Repository Not Accessible​

# Check URL format
repomix --remote https://github.com/user/repo

# Or use shorthand
repomix --remote user/repo

# Specify branch
repomix --remote user/repo --remote-branch main

🌐 Official Resources​

🎯 Summary​

Repomix is essential for:

  • 🤖 AI-assisted code review and analysis
  • 📝 Automated documentation generation
  • 🔍 Codebase understanding and exploration
  • 🧪 Test case generation
  • 📊 Architecture analysis
  • 🔄 Migration planning

Key Advantages:

  • AI-optimized output formats
  • Built-in token counting
  • Smart code compression
  • Git-aware processing
  • Multiple output formats
  • Remote repository support
  • MCP server integration
  • Claude Code plugins

Bottom Line: Repomix transforms your repository into AI-digestible formats, making it perfect for leveraging LLMs for code analysis, documentation, testing, and more. Essential tool for modern AI-assisted development workflows.