📦 Repomix (Python Version)

English | 简体中文

🎯 1. Introduction

Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. It's perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, and Gemini.

The original Repomix is written in JavaScript, and this is the ported Python version.

⭐ 2. Features

• AI-Optimized: Formats your codebase in a way that's easy for AI to understand and process.
• Token Counting: Provides token counts for each file and the entire repository using tiktoken, with configurable encoding (--token-count-encoding).
• Simple to Use: Pack your entire repository with just one command.
• Multiple Directories: Process multiple directories in a single command (repomix src lib tests).
• Customizable: Easily configure what to include or exclude.
• Git-Aware: Automatically respects your .gitignore, .repomixignore, and .ignore files.
• Security-Focused: Built-in security checks to detect and prevent the inclusion of sensitive information (powered by detect-secrets).
• Code Compression: Advanced code compression with multiple modes to reduce output size while preserving essential information.
• Semantic CLI Suggestions: Unknown CLI options suggest the closest valid alternative (e.g., --exclude → "Did you mean: --ignore?").
• Quiet Mode: Suppress all console output except errors with --quiet.
• ⚡ Performance: Utilizes multiprocessing or threading for faster analysis on multi-core systems.
• ⚙️ Encoding Aware: Automatically detects and handles various file encodings (using chardet) beyond UTF-8, increasing robustness.

🚀 3. Quick Start

Quick Run with uvx (Recommended)

The easiest way to use Repomix is with uvx - no installation required:

uvx repomix

That's it! This will pack your current directory into an AI-friendly file.

More examples:

# Pack with JSON output
uvx repomix --style json

# Pack a remote repository
uvx repomix --remote https://github.com/username/repo

# Pack with specific patterns
uvx repomix --include "src/**/*.py" --ignore "tests/**"

# Use a specific version
uvx repomix@0.5.0

You can also use pipx: pipx run repomix

Install with pip

For frequent usage, you can install Repomix globally:

pip install repomix

Then run in any project directory:

repomix

Docker Usage

You can also use Repomix with Docker without installing it locally:

# Build the Docker image
docker build -t repomix .

# Run repomix on the current directory
docker run --rm -v "$(pwd)":/app repomix

# Run repomix with specific options
docker run --rm -v "$(pwd)":/app repomix --style markdown --output custom-output.md

# Run repomix on a different directory
docker run --rm -v "/path/to/your/project":/app repomix

Docker Benefits:

• Isolated Environment: Run repomix without installing Python dependencies on your host system
• Consistent Results: Ensures the same environment across different machines
• Easy Distribution: Share the exact repomix version and configuration with your team
• No Installation Required: Use repomix immediately without pip install

That's it! Repomix will generate a repomix-output.md file (by default) in your current directory, containing your entire repository in an AI-friendly format.

📖 4. Usage

4.1 Command Line Usage

To pack your entire repository:

repomix

To pack a specific directory:

repomix path/to/directory

To pack multiple directories at once:

repomix src lib tests

To pack a remote repository:

repomix --remote https://github.com/username/repo

To pack a specific branch of a remote repository:

repomix --remote https://github.com/username/repo --remote-branch feature-branch

To initialize a new configuration file:

repomix --init
# Use --global to create a global configuration file (see Configuration Options below)
repomix --init --global

4.2 Configuration Options

Create a repomix.config.json file in your project root for custom configurations. Repomix also automatically loads a global configuration file if it exists (e.g., ~/.config/repomix/repomix.config.json on Linux), merging it with lower priority than local config and CLI options.

{
  "input": {
    "max_file_size": 52428800
  },
  "output": {
    "file_path": "repomix-output.md",
    "style": "markdown",
    "header_text": "",
    "instruction_file_path": "",
    "remove_comments": false,
    "remove_empty_lines": false,
    "top_files_length": 5,
    "show_line_numbers": false,
    "copy_to_clipboard": false,
    "include_empty_directories": false,
    "calculate_tokens": false,
    "show_file_stats": false,
    "show_directory_structure": true,
    "include_full_directory_structure": false,
    "split_output": null,
    "token_count_tree": false,
    "git": {
      "sort_by_changes": true,
      "sort_by_changes_max_commits": 100,
      "include_diffs": false,
      "include_logs": false,
      "include_logs_count": 50
    }
  },
  "security": {
    "enable_security_check": true,
    "exclude_suspicious_files": true
  },
  "ignore": {
    "custom_patterns": [],
    "use_gitignore": true,
    "use_default_ignore": true,
    "use_dot_ignore": true
  },
  "compression": {
    "enabled": false,
    "keep_signatures": true,
    "keep_docstrings": true,
    "keep_interfaces": true
  },
  "remote": {
    "url": "",
    "branch": ""
  },
  "include": [],
  "token_count": {
    "encoding": "o200k_base"
  }
}

[!NOTE] Note on remove_comments: This feature is language-aware, correctly handling comment syntax for various languages rather than using a simple generic pattern. Supported languages: Python, JavaScript, TypeScript, JSX, TSX, Vue, Svelte, Java, C, C++, C#, Go, Rust, Ruby, PHP, Swift, Kotlin, HTML, CSS, XML, YAML

Remote Repository Configuration

The remote section allows you to configure remote repository processing:

• url: The URL of the remote Git repository to process
• branch: The specific branch, tag, or commit hash to process (optional, defaults to repository's default branch)

When a remote URL is specified in the configuration, Repomix will process the remote repository instead of the local directory. This can be overridden by CLI parameters (--remote-branch).

You can use various URL formats with --remote:

# GitHub shorthand
repomix --remote user/repo

# Full GitHub URL
repomix --remote https://github.com/user/repo

# Specific branch
repomix --remote https://github.com/user/repo --remote-branch feature-branch

# Specific tag
repomix --remote https://github.com/user/repo --remote-branch v1.0.0

# Specific commit
repomix --remote https://github.com/user/repo --remote-branch abc123

Command Line Options

• repomix [directories...]: Target directories (defaults to current directory). Supports multiple directories.
• -v, --version: Show version.
• -o, --output <file>: Specify output file name.
• --style <style>: Specify output style (plain, xml, markdown, json).
• --remote <url>: Process a remote Git repository.
• --remote-branch <name>: Specify branch, tag, or commit for remote repository.
• --init: Initialize configuration file (repomix.config.json) in the current directory.
• --global: Use with --init to create/manage the global configuration file (located in a platform-specific user config directory, e.g., ~/.config/repomix on Linux). The global config is automatically loaded if present.
• --no-security-check: Disable security check.
• --include <patterns>: Comma-separated list of include patterns (glob format).
• -i, --ignore <patterns>: Additional comma-separated ignore patterns.
• -c, --config <path>: Path to a custom configuration file.
• --copy: Copy generated output to system clipboard.
• --top-files-len <number>: Max number of largest files to display in summary.
• --output-show-line-numbers: Add line numbers to output code blocks.
• --stdin: Read file paths from standard input (one per line) instead of discovering files automatically.
• --verbose: Enable verbose logging for debugging.
• --quiet: Suppress all console output except errors. Cannot be used with --verbose.
• --parsable-style: By escaping and formatting, ensure the output is parsable as a document of its type.
• --stdout: Output to stdout instead of writing to a file.
• --remove-comments: Remove comments from source code.
• --remove-empty-lines: Remove empty lines from source code.
• --truncate-base64: Enable truncation of base64 data strings.
• --include-empty-directories: Include empty directories in the output.
• --include-diffs: Include git diffs in the output.
• --include-logs: Include git log history in the output.
• : Number of recent commits to include with (default: 50).

4.3 Security Check

Repomix includes built-in security checks using the detect-secrets library to detect potentially sensitive information (API keys, credentials, etc.). By default (exclude_suspicious_files: true), detected files are excluded from the output.

Disable checks via configuration or CLI:

repomix --no-security-check

4.4 Custom Instructions

You can add custom instructions to the output file that will guide AI tools on how to interpret and use the packed codebase.

Create a markdown file (e.g., repomix-instruction.md) with your instructions:

## Project Context
This is a Python web application using FastAPI.
Please follow PEP 8 conventions when suggesting code changes.

Then specify the path via CLI or configuration:

# Via CLI
repomix --instruction-file-path repomix-instruction.md

# Via configuration (repomix.config.json)

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

The instruction content will be included in the "Instruction" section of the output file.

4.5 Token Count

Repomix provides token counting to help you understan