repomix

<div align="center" markdown="1"> ^{Special thanks to:} <br> <br> <a href="https://go.warp.dev/repomix"> <img alt="Warp sponsorship" width="400" src="https://raw.githubusercontent.com/warpdotdev/brand-assets/main/Github/Sponsor/Warp-Github-LG-01.png"> </a> ### [Warp, built for coding with multiple AI agents](https://go.warp.dev/repomix) [Available for MacOS, Linux, & Windows](https://go.warp.dev/repomix)<br> <br> <a href="https://tuple.app/repomix"> <img alt="Tuple sponsorship" width="400" src="website/client/src/public/images/sponsors/tuple/github_repo_sponsorship.png"> </a> ### [Tuple, the premier screen sharing app for developers on macOS and Windows.](https://tuple.app/repomix) </div> <hr /> <div align="center"> <a href="https://repomix.com"> <img src="website/client/src/public/images/repomix-title.png" alt="Repomix" width="500" height="auto" /> </a> <p align="center"> <b>Pack your codebase into AI-friendly formats</b> </p> </div> <p align="center"> <a href="https://repomix.com"><b>Use Repomix online! 👉 repomix.com</b></a><br> </p> <p align="center"> Need discussion? Join us on <a href="https://discord.gg/wNYzTwZFku">Discord</a>!<br> <i>Share your experience and tips</i><br> <i>Stay updated on new features</i><br> <i>Get help with configuration and usage</i><br> </p> <hr /> [](https://www.npmjs.com/package/repomix) [](https://www.npmjs.com/package/repomix) [](https://github.com/yamadashy/repomix/actions?query=workflow%3A"ci") [](https://codecov.io/github/yamadashy/repomix) [](https://github.com/sponsors/yamadashy) [](https://discord.gg/wNYzTwZFku) [](https://deepwiki.com/yamadashy/repomix) <!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ --> 📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. It is perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more. Please consider sponsoring me. [](https://github.com/sponsors/yamadashy) [](https://github.com/sponsors/yamadashy) ## 🏆 Open Source Awards Nomination We're honored! Repomix has been nominated for the **Powered by AI** category at the [JSNation Open Source Awards 2025](https://osawards.com/javascript/). This wouldn't have been possible without all of you using and supporting Repomix. Thank you! ## 🎉 New: Repomix Website & Discord Community! - Try Repomix in your browser at [repomix.com](https://repomix.com/) - Join our [Discord Server](https://discord.gg/wNYzTwZFku) for support and discussion **We look forward to seeing you there!** ## 🌟 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, useful for LLM context limits. - **Simple to Use**: You need just one command to pack your entire repository. - **Customizable**: Easily configure what to include or exclude. - **Git-Aware**: Automatically respects your `.gitignore` files and `.git/info/exclude`. - **Security-Focused**: Incorporates [Secretlint](https://github.com/secretlint/secretlint) for robust security checks to detect and prevent inclusion of sensitive information. - **Code Compression**: The `--compress` option uses [Tree-sitter](https://github.com/tree-sitter/tree-sitter) to extract key code elements, reducing token count while preserving structure. ## 🚀 Quick Start ### Using the CLI Tool `>_` You can try Repomix instantly in your project directory without installation: ```bash npx repomix@latest ``` Or install globally for repeated use: ```bash # Install using npm npm install -g repomix # Alternatively using yarn yarn global add repomix # Alternatively using bun bun add -g repomix # Alternatively using Homebrew (macOS/Linux) brew install repomix # Then run in any project directory repomix ``` That's it! Repomix will generate a `repomix-output.xml` file in your current directory, containing your entire repository in an AI-friendly format. You can then send this file to an AI assistant with a prompt like: ``` This file contains all the files in the repository combined into one. I want to refactor the code, so please review it first. ```  When you propose specific changes, the AI might be able to generate code accordingly. With features like Claude's Artifacts, you could potentially output multiple files, allowing for the generation of multiple interdependent pieces of code.  Happy coding! 🚀 ### Using The Website 🌐 Want to try it quickly? Visit the official website at [repomix.com](https://repomix.com). Simply enter your repository name, fill in any optional details, and click the **Pack** button to see your generated output. #### Available Options The website offers several convenient features: - Customizable output format (XML, Markdown, or Plain Text) - Instant token count estimation - Much more! ### Using The Browser Extension 🧩 Get instant access to Repomix directly from any GitHub repository! Our Chrome extension adds a convenient "Repomix" button to GitHub repository pages.  #### Install - Chrome Extension: [Repomix - Chrome Web Store](https://chromewebstore.google.com/detail/repomix/fimfamikepjgchehkohedilpdigcpkoa) - Firefox Add-on: [Repomix - Firefox Add-ons](https://addons.mozilla.org/firefox/addon/repomix/) #### Features - One-click access to Repomix for any GitHub repository - More exciting features coming soon! ### Using The VSCode Extension ⚡️ A community-maintained VSCode extension called [Repomix Runner](https://marketplace.visualstudio.com/items?itemName=DorianMassoulier.repomix-runner) (created by [massdo](https://github.com/massdo)) lets you run Repomix right inside your editor with just a few clicks. Run it on any folder, manage outputs seamlessly, and control everything through VSCode's intuitive interface. Want your output as a file or just the content? Need automatic cleanup? This extension has you covered. Plus, it works smoothly with your existing repomix.config.json. Try it now on the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=DorianMassoulier.repomix-runner)! Source code is available on [GitHub](https://github.com/massdo/repomix-runner). ### Alternative Tools 🛠️ If you're using Python, you might want to check out `Gitingest`, which is better suited for Python ecosystem and data science workflows: https://github.com/cyclotruc/gitingest ## 📊 Usage To pack your entire repository: ```bash repomix ``` To pack a specific directory: ```bash repomix path/to/directory ``` To pack specific files or directories using [glob patterns](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax): ```bash repomix --include "src/**/*.ts,**/*.md" ``` To exclude specific files or directories: ```bash repomix --ignore "**/*.log,tmp/" ``` To pack a remote repository: ```bash repomix --remote https://github.com/yamadashy/repomix # You can also use GitHub shorthand: repomix --remote yamadashy/repomix # You can specify the branch name, tag, or commit hash: repomix --remote https://github.com/yamadashy/repomix --remote-branch main # Or use a specific commit hash: repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695 # Another convenient way is specifying the branch's URL repomix --remote https://github.com/yamadashy/repomix/tree/main # Commit's URL is also supported repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1 ``` To pack files from a file list (pipe via stdin): ```bash # Using find command find src -name "*.ts" -type f | repomix --stdin # Using git to get tracked files git ls-files "*.ts" | repomix --stdin # Using grep to find files containing specific content grep -l "TODO" **/*.ts | repomix --stdin # Using ripgrep to find files with specific content rg -l "TODO|FIXME" --type ts | repomix --stdin # Using ripgrep (rg) to find files rg --files --type ts | repomix --stdin # Using sharkdp/fd to find files fd -e ts | repomix --stdin # Using fzf to select from all files fzf -m | repomix --stdin # Interactive file selection with fzf find . -name "*.ts" -type f | fzf -m | repomix --stdin # Using ls with glob patterns ls src/**/*.ts | repomix --stdin # From a file containing file paths cat file-list.txt | repomix --stdin # Direct input with echo echo -e "src/index.ts\nsrc/utils.ts" | repomix --stdin ``` The `--stdin` option allows you to pipe a list of file paths to Repomix, giving you ultimate flexibility in selecting which files to pack. When using `--stdin`, the specified files are effectively added to the include patterns. This means that the normal include and ignore behavior still applies - files specified via stdin will still be excluded if they match ignore patterns. > [!NOTE] > When using `--stdin`, file paths can be relative or absolute, and Repomix will automatically handle path resolution and deduplication. To include git logs in the output: ```bash # Include git logs with default count (50 commits) repomix --include-logs # Include git logs with specific commit count repomix --include-logs --include-logs-count 10 # Combine with diffs for comprehensive git context repomix --include-logs --include-diffs ``` The git logs include commit dates, messages, and file paths for each commit, providing valuable context for AI analysis of code evolution and development patterns. To compress the output: ```bash repomix --compress # You can also use it with remote repositories: repomix --remote yamadashy/repomix --compress ``` To initialize a new configuration file (`repomix.config.json`): ```bash repomix --init ``` Once you have generated the packed file, you can use it with Generative AI tools like ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more. ### Docker Usage 🐳 You can also run Repomix using Docker. This is useful if you want to run Repomix in an isolated environment or prefer using containers. Basic usage (current directory): ```bash docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix ``` To pack a specific directory: ```bash docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix path/to/directory ``` Process a remote repository and output to a `output` directory: ```bash docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote https://github.com/yamadashy/repomix ``` ### Prompt Examples Once you have generated the packed file with Repomix, you can use it with AI tools like ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more. Here are some example prompts to get you started: #### Code Review and Refactoring For a comprehensive code review and refactoring suggestions: ``` This file contains my entire codebase. Please review the overall structure and suggest any improvements or refactoring opportunities, focusing on maintainability and scalability. ``` #### Documentation Generation To generate project documentation: ``` Based on the codebase in this file, please generate a detailed README.md that includes an overview of the project, its main features, setup instructions, and usage examples. ``` #### Test Case Generation For generating test cases: ``` Analyze the code in this file and suggest a comprehensive set of unit tests for the main functions and classes. Include edge cases and potential error scenarios. ``` #### Code Quality Assessment Evaluate code quality and adherence to best practices: ``` Review the codebase for adherence to coding best practices and industry standards. Identify areas where the code could be improved in terms of readability, maintainability, and efficiency. Suggest specific changes to align the code with best practices. ``` #### Library Overview Get a high-level understanding of the library ``` This file contains the entire codebase of library. Please provide a comprehensive overview of the library, including its main purpose, key features, and overall architecture. ``` Feel free to modify these prompts based on your specific needs and the capabilities of the AI tool you're using. ### Community Discussion Check out our [community discussion](https://github.com/yamadashy/repomix/discussions/154) where users share: - Which AI tools they're using with Repomix - Effective prompts they've discovered - How Repomix has helped them - Tips and tricks for getting the most out of AI code analysis Feel free to join the discussion and share your own experiences! Your insights could help others make better use of Repomix. ### Output File Format Repomix generates a single file with clear separators between different parts of your codebase. To enhance AI comprehension, the output file begins with an AI-oriented explanation, making it easier for AI models to understand the context and structure of the packed repository. #### XML Format (default) The XML format structures the content in a hierarchical manner: ```xml This file is a merged representation of the entire codebase, combining all repository files into a single document. <file_summary> (Metadata and usage AI instructions) </file_summary> <directory_structure> src/ cli/ cliOutput.ts index.ts (...remaining directories) </directory_structure> <files> <file path="src/index.js"> // File contents here </file> (...remaining files) </files> <instruction> (Custom instructions from `output.instructionFilePath`) </instruction> ``` For those interested in the potential of XML tags in AI contexts: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags > When your prompts involve multiple components like context, instructions, and examples, XML tags can be a > game-changer. They help Claude parse your prompts more accurately, leading to higher-quality outputs. This means that the XML output from Repomix is not just a different format, but potentially a more effective way to feed your codebase into AI systems for analysis, code review, or other tasks. #### Markdown Format To generate output in Markdown format, use the `--style markdown` option: ```bash repomix --style markdown ``` The Markdown format structures the content in a hierarchical manner: ````markdown This file is a merged representation of the entire codebase, combining all repository files into a single document. # File Summary (Metadata and usage AI instructions) # Repository Structure ``` src/ cli/ cliOutput.ts index.ts ``` (...remaining directories) # Repository Files ## File: src/index.js ``` // File contents here ``` (...remaining files) # Instruction (Custom instructions from `output.instructionFilePath`) ```` This format provides a clean, readable structure that is both human-friendly and easily parseable by AI systems. #### JSON Format To generate output in JSON format, use the `--style json` option: ```bash repomix --style json ``` The JSON format structures the content as a hierarchical JSON object with camelCase property names: ```json { "fileSummary": { "generationHeader": "This file is a merged representation of the entire codebase, combined into a single document by Repomix.", "purpose": "This file contains a packed representation of the entire repository's contents...", "fileFormat": "The content is organized as follows...", "usageGuidelines": "- This file should be treated as read-only...", "notes": "- Some files may have been excluded based on .gitignore rules..." }, "userProvidedHeader": "Custom header text if specified", "directoryStructure": "src/\n cli/\n cliOutput.ts\n index.ts\n config/\n configLoader.ts", "files": { "src/index.js": "// File contents here", "src/utils.js": "// File contents here" }, "instruction": "Custom instructions from instructionFilePath" } ``` This format is ideal for: - **Programmatic processing**: Easy to parse and manipulate with JSON libraries - **API integration**: Direct consumption by web services and applications - **AI tool compatibility**: Structured format for machine learning and AI systems - **Data analysis**: Straightforward extraction of specific information using tools like `jq` ##### Working with JSON Output Using `jq` The JSON format makes it easy to extract specific information programmatically: ```bash # List all file paths cat repomix-output.json | jq -r '.files | keys[]' # Count total number of files cat repomix-output.json | jq '.files | keys | length' # Extract specific file content cat repomix-output.json | jq -r '.files["README.md"]' cat repomix-output.json | jq -r '.files["src/index.js"]' # Find files by extension cat repomix-output.json | jq -r '.files | keys[] | select(endswith(".ts"))' # Get files containing specific text cat repomix-output.json | jq -r '.files | to_entries[] | select(.value | contains("function")) | .key' # Extract directory structure cat repomix-output.json | jq -r '.directoryStructure' # Get file summary information cat repomix-output.json | jq '.fileSummary.purpose' cat repomix-output.json | jq -r '.fileSummary.generationHeader' # Extract user-provided header (if exists) cat repomix-output.json | jq -r '.userProvidedHeader // "No header provided"' # Create a file list with sizes cat repomix-output.json | jq -r '.files | to_entries[] | "\(.key): \(.value | length) characters"' ``` #### Plain Text Format To generate output in plain text format, use the `--style plain` option: ```bash repomix --style plain ``` ```text This file is a merged representation of the entire codebase, combining all repository files into a single document. ================================================================ File Summary ================================================================ (Metadata and usage AI instructions) ================================================================ Directory Structure ================================================================ src/ cli/ cliOutput.ts index.ts config/ configLoader.ts (...remaining directories) ================================================================ Files ================================================================ ================ File: src/index.js ================ // File contents here ================ File: src/utils.js ================ // File contents here (...remaining files) ================================================================ Instruction ================================================================ (Custom instructions from `output.instructionFilePath`) ``` ### Command Line Options #### Basic Options - `-v, --version`: Show version information and exit #### CLI Input/Output Options - `--verbose`: Enable detailed debug logging (shows file processing, token counts, and configuration details) - `--quiet`: Suppress all console output except errors (useful for scripting) - `--stdout`: Write packed output directly to stdout instead of a file (suppresses all logging) - `--stdin`: Read file paths from stdin, one per line (specified files are processed directly) - `--copy`: Copy the generated output to system clipboard after processing - `--token-count-tree [threshold]`: Show file tree with token counts; optional threshold to show only files with ≥N tokens (e.g., --token-count-tree 100) - `--top-files-len <number>`: Number of largest files to show in summary (default: 5, e.g., --top-files-len 20) #### Repomix Output Options - `-o, --output <file>`: Output file path (default: repomix-output.xml, use "-" for stdout) - `--style <style>`: Output format: xml, markdown, json, or plain (default: xml) - `--parsable-style`: Escape special characters to ensure valid XML/Markdown (needed when output contains code that breaks formatting) - `--compress`: Extract essential code structure (classes, functions, interfaces) using Tree-sitter parsing - `--output-show-line-numbers`: Prefix each line with its line number in the output - `--no-file-summary`: Omit the file summary section from output - `--no-directory-structure`: Omit the directory tree visualization from output - `--no-files`: Generate metadata only without file contents (useful for repository analysis) - `--remove-comments`: Strip all code comments before packing - `--remove-empty-lines`: Remove blank lines from all files - `--truncate-base64`: Truncate long base64 data strings to reduce output size - `--header-text <text>`: Custom text to include at the beginning of the output - `--instruction-file-path <path>`: Path to file containing custom instructions to include in output - `--include-empty-directories`: Include folders with no files in directory structure - `--no-git-sort-by-changes`: Don't sort files by git change frequency (default: most changed files first) - `--include-diffs`: Add git diff section showing working tree and staged changes - `--include-logs`: Add git commit history with messages and changed files - `--include-logs-count <count>`: Number of recent commits to include with --include-logs (default: 50) #### File Selection Options - `--include <patterns>`: Include only files matching these glob patterns (comma-separated, e.g., "src/**/*.js,*.md") - `-i, --ignore <patterns>`: Additional patterns to exclude (comma-separated, e.g., "*.test.js,docs/**") - `--no-gitignore`: Don't use .gitignore rules for filtering files - `--no-default-patterns`: Don't apply built-in ignore patterns (node_modules, .git, build dirs, etc.) #### Remote Repository Options - `--remote <url>`: Clone and pack a remote repository (GitHub URL or user/repo format) - `--remote-branch <name>`: Specific branch, tag, or commit to use (default: repository's default branch) #### Configuration Options - `-c, --config <path>`: Use custom config file instead of repomix.config.json - `--init`: Create a new repomix.config.json file with defaults - `--global`: With --init, create config in home directory instead of current directory #### Security Options - `--no-security-check`: Skip scanning for sensitive data like API keys and passwords #### Token Count Options - `--token-count-encoding <encoding>`: Tokenizer model for counting: o200k_base (GPT-4o), cl100k_base (GPT-3.5/4), etc. (default: o200k_base) #### MCP - `--mcp`: Run as Model Context Protocol server for AI tool integration #### Examples ```bash # Basic usage repomix # Custom output repomix -o output.xml --style xml # Output to stdout repomix --stdout > custom-output.txt # Send output to stdout, then pipe into another command (for example, simonw/llm) repomix --stdout | llm "Please explain what this code does." # Custom output with compression repomix --compress # Process specific files repomix --include "src/**/*.ts" --ignore "**/*.test.ts" # Remote repository with branch repomix --remote https://github.com/user/repo/tree/main # Remote repository with commit repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1 # Remote repository with shorthand repomix --remote user/repo ``` ### Updating Repomix To update a globally installed Repomix: ```bash # Using npm npm update -g repomix # Using yarn yarn global upgrade repomix # Using bun bun update -g repomix ``` Using `npx repomix` is generally more convenient as it always uses the latest version. ### Remote Repository Processing Repomix supports processing remote Git repositories without the need for manual cloning. This feature allows you to quickly analyze any public Git repository with a single command. To process a remote repository, use the `--remote` option followed by the repository URL: ```bash repomix --remote https://github.com/yamadashy/repomix ``` You can also use GitHub's shorthand format: ```bash repomix --remote yamadashy/repomix ``` You can specify the branch name, tag, or commit hash: ```bash # Using --remote-branch option repomix --remote https://github.com/yamadashy/repomix --remote-branch main # Using branch's URL repomix --remote https://github.com/yamadashy/repomix/tree/main ``` Or use a specific commit hash: ```bash # Using --remote-branch option repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695 # Using commit's URL repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1 ``` ### Code Compression The `--compress` option utilizes [Tree-sitter](https://github.com/tree-sitter/tree-sitter) to perform intelligent code extraction, focusing on essential function and class signatures while removing implementation details. This can help reduce token count while retaining important structural information. ```bash repomix --compress ``` For example, this code: ```typescript 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; } // Shopping item interface interface Item { name: string; price: number; quantity: number; } ``` Will be compressed to: ```typescript import { ShoppingItem } from './shopping-item'; ⋮---- /** * Calculate the total price of shopping items */ const calculateTotal = ( items: ShoppingItem[] ) => { ⋮---- // Shopping item interface interface Item { name: string; price: number; quantity: number; } ``` > [!NOTE] > This is an experimental feature that we'll be actively improving based on user feedback and real-world usage ### Token Count Optimization Understanding your codebase's token distribution is crucial for optimizing AI interactions. Use the `--token-count-tree` option to visualize token usage across your project: ```bash repomix --token-count-tree ``` This displays a hierarchical view of your codebase with token counts: ``` 🔢 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) ``` You can also set a minimum token threshold to focus on larger files: ```bash repomix --token-count-tree 1000 # Only show files/directories with 1000+ tokens ``` This helps you: - **Identify token-heavy files** that might exceed AI context limits - **Optimize file selection** using `--include` and `--ignore` patterns - **Plan compression strategies** by targeting the largest contributors - **Balance content vs. context** when preparing code for AI analysis ### MCP Server Integration Repomix supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), allowing AI assistants to directly interact with your codebase. When run as an MCP server, Repomix provides tools that enable AI assistants to package local or remote repositories for analysis without requiring manual file preparation. ```bash repomix --mcp ``` #### Configuring MCP Servers To use Repomix as an MCP server with AI assistants like Claude, you need to configure the MCP settings: **For VS Code:** You can install the Repomix MCP server in VS Code using one of these methods: 1. **Using the Install Badge:** [](https://insiders.vscode.dev/redirect/mcp/install?name=repomix&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22repomix%22%2C%22--mcp%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=repomix&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22repomix%22%2C%22--mcp%22%5D%7D&quality=insiders) 2. **Using the Command Line:** ```bash code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}' ``` For VS Code Insiders: ```bash code-insiders --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}' ``` **For Cline (VS Code extension):** Edit the `cline_mcp_settings.json` file: ```json { "mcpServers": { "repomix": { "command": "npx", "args": [ "-y", "repomix", "--mcp" ] } } } ``` **For Cursor:** In Cursor, add a new MCP server from `Cursor Settings` > `MCP` > `+ Add new global MCP server` with a configuration similar to Cline. **For Claude Desktop:** Edit the `claude_desktop_config.json` file with similar configuration to Cline's config. **For Claude Code:** To configure Repomix as an MCP server in [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), use the following command: ```bash claude mcp add repomix -- npx -y repomix --mcp ``` **Using Docker instead of npx:** You can use Docker as an alternative to npx for running Repomix as an MCP server: ```json { "mcpServers": { "repomix-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/yamadashy/repomix", "--mcp" ] } } } ``` Once configured, your AI assistant can directly use Repomix's capabilities to analyze codebases without manual file preparation, making code analysis workflows more efficient. #### Available MCP Tools When running as an MCP server, Repomix provides the following tools: 1. **pack_codebase**: Package a local code directory into a consolidated XML file for AI analysis - Parameters: - `directory`: Absolute path to the directory to pack - `compress`: (Optional, default: false) Enable Tree-sitter compression to extract essential code signatures and structure while removing implementation details. Reduces token usage by ~70% while preserving semantic meaning. Generally not needed since grep_repomix_output allows incremental content retrieval. Use only when you specifically need the entire codebase content for large repositories. - `includePatterns`: (Optional) Specify files to include using fast-glob patterns. Multiple patterns can be comma-separated (e.g., "**/*.{js,ts}", "src/**,docs/**"). Only matching files will be processed. - `ignorePatterns`: (Optional) Specify additional files to exclude using fast-glob patterns. Multiple patterns can be comma-separated (e.g., "test/**,*.spec.js", "node_modules/**,dist/**"). These patterns supplement .gitignore and built-in exclusions. - `topFilesLength`: (Optional, default: 10) Number of largest files by size to display in the metrics summary for codebase analysis. 2. **attach_packed_output**: Attach an existing Repomix packed output file for AI analysis - Parameters: - `path`: Path to a directory containing repomix-output.xml or direct path to a packed repository XML file - `topFilesLength`: (Optional, default: 10) Number of largest files by size to display in the metrics summary - Features: - Accepts either a directory containing a repomix-output.xml file or a direct path to an XML file - Registers the file with the MCP server and returns the same structure as the pack_codebase tool - Provides secure access to existing packed outputs without requiring re-processing - Useful for working with previously generated packed repositories 3. **pack_remote_repository**: Fetch, clone, and package a GitHub repository into a consolidated XML file for AI analysis - Parameters: - `remote`: GitHub repository URL or user/repo format (e.g., "yamadashy/repomix", "https://github.com/user/repo", or "https://github.com/user/repo/tree/branch") - `compress`: (Optional, default: false) Enable Tree-sitter compression to extract essential code signatures and structure while removing implementation details. Reduces token usage by ~70% while preserving semantic meaning. Generally not needed since grep_repomix_output allows incremental content retrieval. Use only when you specifically need the entire codebase content for large repositories. - `includePatterns`: (Optional) Specify files to include using fast-glob patterns. Multiple patterns can be comma-separated (e.g., "**/*.{js,ts}", "src/**,docs/**"). Only matching files will be processed. - `ignorePatterns`: (Optional) Specify additional files to exclude using fast-glob patterns. Multiple patterns can be comma-separated (e.g., "test/**,*.spec.js", "node_modules/**,dist/**"). These patterns supplement .gitignore and built-in exclusions. - `topFilesLength`: (Optional, default: 10) Number of largest files by size to display in the metrics summary for codebase analysis. 4. **read_repomix_output**: Read the contents of a Repomix-generated output file. Supports partial reading with line range specification for large files. - Parameters: - `outputId`: ID of the Repomix output file to read - `startLine`: (Optional) Starting line number (1-based, inclusive). If not specified, reads from beginning. - `endLine`: (Optional) Ending line number (1-based, inclusive). If not specified, reads to end. - Features: - Specifically designed for web-based environments or sandboxed applications - Retrieves the content of previously generated outputs using their ID - Provides secure access to packed codebase without requiring file system access - Supports partial reading for large files 5. **grep_repomix_output**: Search for patterns in a Repomix output file using grep-like functionality with JavaScript RegExp syntax - Parameters: - `outputId`: ID of the Repomix output file to search - `pattern`: Search pattern (JavaScript RegExp regular expression syntax) - `contextLines`: (Optional, default: 0) Number of context lines to show before and after each match. Overridden by beforeLines/afterLines if specified. - `beforeLines`: (Optional) Number of context lines to show before each match (like grep -B). Takes precedence over contextLines. - `afterLines`: (Optional) Number of context lines to show after each match (like grep -A). Takes precedence over contextLines. - `ignoreCase`: (Optional, default: false) Perform case-insensitive matching - Features: - Uses JavaScript RegExp syntax for powerful pattern matching - Supports context lines for better understanding of matches - Allows separate control of before/after context lines - Case-sensitive and case-insensitive search options 6. **file_system_read_file**: Read a file from the local file system using an absolute path. Includes built-in security validation to detect and prevent access to files containing sensitive information. - Parameters: - `path`: Absolute path to the file to read - Security features: - Implements security validation using [Secretlint](https://github.com/secretlint/secretlint) - Prevents access to files containing sensitive information (API keys, passwords, secrets) - Validates absolute paths to prevent directory traversal attacks 7. **file_system_read_directory**: List the contents of a directory using an absolute path. Returns a formatted list showing files and subdirectories with clear indicators. - Parameters: - `path`: Absolute path to the directory to list - Features: - Shows files and directories with clear indicators (`[FILE]` or `[DIR]`) - Provides safe directory traversal with proper error handling - Validates paths and ensures they are absolute - Useful for exploring project structure and understanding codebase organization ## ⚙️ Configuration Create a `repomix.config.json` file in your project root for custom configurations. ```bash repomix --init ``` Here's an explanation of the configuration options: | Option | Description | Default | |----------------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------| | `input.maxFileSize` | Maximum file size in bytes to process. Files larger than this will be skipped | `50000000` | | `output.filePath` | The name of the output file | `"repomix-output.xml"` | | `output.style` | The style of the output (`xml`, `markdown`, `json`, `plain`) | `"xml"` | | `output.parsableStyle` | Whether to escape the output based on the chosen style schema. Note that this can increase token count. | `false` | | `output.compress` | Whether to perform intelligent code extraction to reduce token count | `false` | | `output.headerText` | Custom text to include in the file header | `null` | | `output.instructionFilePath` | Path to a file containing detailed custom instructions | `null` | | `output.fileSummary` | Whether to include a summary section at the beginning of the output | `true` | | `output.directoryStructure` | Whether to include the directory structure in the output | `true` | | `output.files` | Whether to include file contents in the output | `true` | | `output.removeComments` | Whether to remove comments from supported file types | `false` | | `output.removeEmptyLines` | Whether to remove empty lines from the output | `false` | | `output.showLineNumbers` | Whether to add line numbers to each line in the output | `false` | | `output.truncateBase64` | Whether to truncate long base64 data strings (e.g., images) to reduce token count | `false` | | `output.copyToClipboard` | Whether to copy the output to system clipboard in addition to saving the file | `false` | | `output.topFilesLength` | Number of top files to display in the summary. If set to 0, no summary will be displayed | `5` | | `output.tokenCountTree` | Whether to display file tree with token count summaries. Can be boolean or number (minimum token count threshold) | `false` | | `output.includeEmptyDirectories` | Whether to include empty directories in the repository structure | `false` | | `output.git.sortByChanges` | Whether to sort files by git change count (files with more changes appear at the bottom) | `true` | | `output.git.sortByChangesMaxCommits` | Maximum number of commits to analyze for git changes | `100` | | `output.git.includeDiffs` | Whether to include git diffs in the output (includes both work tree and staged changes separately) | `false` | | `output.git.includeLogs` | Whether to include git logs in the output (includes commit history with dates, messages, and file paths) | `false` | | `output.git.includeLogsCount` | Number of git log commits to include | `50` | | `include` | Patterns of files to include (using [glob patterns](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax)) | `[]` | | `ignore.useGitignore` | Whether to use patterns from the project's `.gitignore` file | `true` | | `ignore.useDefaultPatterns` | Whether to use default ignore patterns | `true` | | `ignore.customPatterns` | Additional patterns to ignore (using [glob patterns](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax)) | `[]` | | `security.enableSecurityCheck` | Whether to perform security checks on files | `true` | | `tokenCount.encoding` | Token count encoding used by OpenAI's [tiktoken](https://github.com/openai/tiktoken) tokenizer (e.g., `o200k_base` for GPT-4o, `cl100k_base` for GPT-4/3.5). See [tiktoken model.py](https://github.com/openai/tiktoken/blob/main/tiktoken/model.py#L24) for encoding details. | `"o200k_base"` | The configuration file supports [JSON5](https://json5.org/) syntax, which allows: - Comments (both single-line and multi-line) - Trailing commas in objects and arrays - Unquoted property names - More relaxed string syntax Example configuration: ```json5 { "input": { "maxFileSize": 50000000 }, "output": { "filePath": "repomix-output.xml", "style": "xml", "parsableStyle": false, "compress": false, "headerText": "Custom header information for the packed file.", "fileSummary": true, "directoryStructure": true, "files": true, "removeComments": false, "removeEmptyLines": false, "topFilesLength": 5, "tokenCountTree": false, // or true, or a number like 10 for minimum token threshold "showLineNumbers": false, "truncateBase64": false, "copyToClipboard": false, "includeEmptyDirectories": false, "git": { "sortByChanges": true, "sortByChangesMaxCommits": 100, "includeDiffs": false, "includeLogs": false, "includeLogsCount": 50 } }, "include": ["**/*"], "ignore": { "useGitignore": true, "useDefaultPatterns": true, // Patterns can also be specified in .repomixignore "customPatterns": [ "additional-folder", "**/*.log" ], }, "security": { "enableSecurityCheck": true }, "tokenCount": { "encoding": "o200k_base" } } ``` ### Global Configuration To create a global configuration file: ```bash repomix --init --global ``` The global configuration file will be created in: - Windows: `%LOCALAPPDATA%\Repomix\repomix.config.json` - macOS/Linux: `$XDG_CONFIG_HOME/repomix/repomix.config.json` or `~/.config/repomix/repomix.config.json` Note: Local configuration (if present) takes precedence over global configuration. ### Include and Ignore #### Include Patterns Repomix now supports specifying files to include using [glob patterns](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax). This allows for more flexible and powerful file selection: - Use `**/*.js` to include all JavaScript files in any directory - Use `src/**/*` to include all files within the `src` directory and its subdirectories - Combine multiple patterns like `["src/**/*.js", "**/*.md"]` to include JavaScript files in `src` and all Markdown files #### Ignore Patterns Repomix offers multiple methods to set ignore patterns for excluding specific files or directories during the packing process: - **.gitignore**: By default, patterns listed in your project's `.gitignore` files and `.git/info/exclude` are used. This behavior can be controlled with the `ignore.useGitignore` setting or the `--no-gitignore` cli option. - **Default patterns**: Repomix includes a default list of commonly excluded files and directories (e.g., node_modules, .git, binary files). This feature can be controlled with the `ignore.useDefaultPatterns` setting or the `--no-default-patterns` cli option. Please see [defaultIgnore.ts](src/config/defaultIgnore.ts) for more details. - **.repomixignore**: You can create a `.repomixignore` file in your project root to define Repomix-specific ignore patterns. This file follows the same format as `.gitignore`. - **Custom patterns**: Additional ignore patterns can be specified using the `ignore.customPatterns` option in the configuration file. You can overwrite this setting with the `-i, --ignore` command line option. Priority Order (from highest to lowest): 1. Custom patterns `ignore.customPatterns` 2. `.repomixignore` 3. `.gitignore` and `.git/info/exclude` (if `ignore.useGitignore` is true and `--no-gitignore` is not used) 4. Default patterns (if `ignore.useDefaultPatterns` is true and `--no-default-patterns` is not used) This approach allows for flexible file exclusion configuration based on your project's needs. It helps optimize the size of the generated pack file by ensuring the exclusion of security-sensitive files and large binary files, while preventing the leakage of confidential information. Note: Binary files are not included in the packed output by default, but their paths are listed in the "Repository Structure" section of the output file. This provides a complete overview of the repository structure while keeping the packed file efficient and text-based. ### Custom Instruction The `output.instructionFilePath` option allows you to specify a separate file containing detailed instructions or context about your project. This allows AI systems to understand the specific context and requirements of your project, potentially leading to more relevant and tailored analysis or suggestions. Here's an example of how you might use this feature: 1. Create a file named `repomix-instruction.md` in your project root: ```markdown # Coding Guidelines - Follow the Airbnb JavaScript Style Guide - Suggest splitting files into smaller, focused units when appropriate - Add comments for non-obvious logic. Keep all text in English - All new features should have corresponding unit tests # Generate Comprehensive Output - Include all content without abbreviation, unless specified otherwise - Optimize for handling large codebases while maintaining output quality ``` 2. In your `repomix.config.json`, add the `instructionFilePath` option: ```json5 { "output": { "instructionFilePath": "repomix-instruction.md", // other options... } } ``` When Repomix generates the output, it will include the contents of `repomix-instruction.md` in a dedicated section. Note: The instruction content is appended at the end of the output file. This placement can be particularly effective for AI systems. For those interested in understanding why this might be beneficial, Anthropic provides some insights in their documentation: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips > Put long-form data at the top: Place your long documents and inputs (~20K+ tokens) near the top of your prompt, above > your query, instructions, and examples. This can significantly improve Claude's performance across all models. > Queries at the end can improve response quality by up to 30% in tests, especially with complex, multi-document inputs. ### Comment Removal When `output.removeComments` is set to `true`, Repomix will attempt to remove comments from supported file types. This feature can help reduce the size of the output file and focus on the essential code content. Supported languages include: HTML, CSS, JavaScript, TypeScript, Vue, Svelte, Python, PHP, Ruby, C, C#, Java, Go, Rust, Swift, Kotlin, Dart, Shell, and YAML. Note: The comment removal process is conservative to avoid accidentally removing code. In complex cases, some comments might be retained. ## 🔍 Security Check Repomix includes a security check feature that uses [Secretlint](https://github.com/secretlint/secretlint) to detect potentially sensitive information in your files. This feature helps you identify possible security risks before sharing your packed repository. The security check results will be displayed in the CLI output after the packing process is complete. If any suspicious files are detected, you'll see a list of these files along with a warning message. Example output: ``` 🔍 Security Check: ────────────────── 2 suspicious file(s) detected: 1. src/utils/test.txt 2. tests/utils/secretLintUtils.test.ts Please review these files for potentially sensitive information. ``` By default, Repomix's security check feature is enabled. You can disable it by setting `security.enableSecurityCheck` to `false` in your configuration file: ```json { "security": { "enableSecurityCheck": false } } ``` Or using the `--no-security-check` command line option: ```bash repomix --no-security-check ``` > [!NOTE] > Disabling security checks may expose sensitive information. Use this option with caution and only when necessary, such > as when working with test files or documentation that contains example credentials. ## 🤖 Using Repomix with GitHub Actions You can also use Repomix in your GitHub Actions workflows. This is useful for automating the process of packing your codebase for AI analysis. Basic usage: ```yaml - name: Pack repository with Repomix uses: yamadashy/repomix/.github/actions/repomix@main with: output: repomix-output.xml style: xml ``` Use `--style` to generate output in different formats: ```yaml - name: Pack repository with Repomix uses: yamadashy/repomix/.github/actions/repomix@main with: output: repomix-output.md style: markdown ``` ```yaml - name: Pack repository with Repomix (JSON format) uses: yamadashy/repomix/.github/actions/repomix@main with: output: repomix-output.json style: json ``` Pack specific directories with compression: ```yaml - name: Pack repository with Repomix uses: yamadashy/repomix/.github/actions/repomix@main with: directories: src tests include: "**/*.ts,**/*.md" ignore: "**/*.test.ts" output: repomix-output.txt compress: true ``` Upload the output file as an artifact: ```yaml - name: Pack repository with Repomix uses: yamadashy/repomix/.github/actions/repomix@main with: directories: src output: repomix-output.txt compress: true - name: Upload Repomix output uses: actions/upload-artifact@v4 with: name: repomix-output path: repomix-output.txt ``` Complete workflow example: ```yaml name: Pack repository with Repomix on: workflow_dispatch: push: branches: [ main ] pull_request: 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 - name: Upload Repomix output uses: actions/upload-artifact@v4 with: name: repomix-output.xml path: repomix-output.xml retention-days: 30 ``` See the complete workflow example [here](https://github.com/yamadashy/repomix/blob/main/.github/workflows/pack-repository.yml). ### Action Inputs | Name | Description | Default | |------|-------------|---------| | `directories` | Space-separated list of directories to process (e.g., `src tests docs`) | `.` | | `include` | Comma-separated glob patterns to include files (e.g., `**/*.ts,**/*.md`) | `""` | | `ignore` | Comma-separated glob patterns to ignore files (e.g., `**/*.test.ts,**/node_modules/**`) | `""` | | `output` | Relative path for the packed file (extension determines format: `.txt`, `.md`, `.xml`) | `repomix-output.xml` | | `compress` | Enable smart compression to reduce output size by pruning implementation details | `true` | | `style` | Output style (`xml`, `markdown`, `json`, `plain`) | `xml` | | `additional-args` | Extra raw arguments for the repomix CLI (e.g., `--no-file-summary --no-security-check`) | `""` | | `repomix-version` | Version of the npm package to install (supports semver ranges, tags, or specific versions like `0.2.25`) | `latest` | ### Action Outputs | Name | Description | |------|-------------| | `output_file` | Path to the generated output file. Can be used in subsequent steps for artifact upload, LLM processing, or other operations. The file contains a formatted representation of your codebase based on the specified options. | ## 📚 Using Repomix as a Library In addition to using Repomix as a CLI tool, you can also use it as a library in your Node.js applications. ### Installation ```bash npm install repomix ``` ### Basic Usage ```javascript import { runCli, type CliOptions } from 'repomix'; // Process current directory with custom options 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; } ``` ### Process Remote Repository ```javascript import { runCli, type CliOptions } from 'repomix'; // Clone and process a GitHub repo async function processRemoteRepo(repoUrl) { const options = { remote: repoUrl, output: 'output.xml', compress: true } as CliOptions; return await runCli(['.'], process.cwd(), options); } ``` ### Using Core Components If you need more control, you can use the low-level APIs: ```javascript import { searchFiles, collectFiles, processFiles, TokenCounter } from 'repomix'; async function analyzeFiles(directory) { // Find and collect files const { filePaths } = await searchFiles(directory, { /* config */ }); const rawFiles = await collectFiles(filePaths, directory); const processedFiles = await processFiles(rawFiles, { /* config */ }); // Count tokens const tokenCounter = new TokenCounter('o200k_base'); // Return analysis results return processedFiles.map(file => ({ path: file.path, tokens: tokenCounter.countTokens(file.content) })); } ``` For more examples, check the source code at [website/server/src/remoteRepo.ts](https://github.com/yamadashy/repomix/blob/main/website/server/src/remoteRepo.ts) which demonstrates how repomix.com uses the library. ## 🤝 Contribution We welcome contributions from the community! To get started, please refer to our [Contributing Guide](CONTRIBUTING.md). ### Contributors <a href="https://github.com/yamadashy/repomix/graphs/contributors"> <img alt="contributors" src="https://contrib.rocks/image?repo=yamadashy/repomix"/> </a> ## 🔒 Privacy Policy ### Repomix CLI Tool - **Data Collection**: The Repomix CLI tool does **not** collect, transmit, or store any user data, telemetry, or repository information. - **Network Usage**: Repomix CLI operates fully offline after installation. The only cases where an internet connection is needed are: - Installation via npm/yarn. - Using the `--remote` flag to process remote repositories. - Checking for updates (manually triggered). - **Security Considerations**: Since all processing is local, Repomix CLI is safe to use with private and internal repositories. ### Repomix Website ([repomix.com](https://repomix.com/)) - **Data Collection**: The Repomix website uses **Google Analytics** to collect usage data, such as page views and user interactions. This helps us understand how the website is used and improve the user experience. - **File Processing**: When uploading ZIP files or folders, your files are temporarily stored on our servers for processing. All uploaded files and processed data are automatically deleted immediately after processing is complete. ### Repomix Browser Extension - **Data Collection**: The Repomix browser extension does **not** collect, transmit, or store any user data, telemetry, or repository information. - **Permissions**: The extension only requires minimal permissions necessary to add the Repomix button to GitHub repository pages. It does not access or modify repository data. ### Liability Disclaimer Repomix (the CLI tool, website, and browser extension) is provided "as is" without any warranties or guarantees. We do not take responsibility for how the generated output is used, including but not limited to its accuracy, legality, or any potential consequences arising from its use. ## 📜 License This project is licensed under the [MIT License](LICENSE). <p align="center"> &nbsp;&nbsp;&nbsp; <a href="#repo-content-pjax-container" target="_blank"> Back To Top </a> </p>