Skip to content
Back to search

repomix

MarketplaceWorks with Claude CodeGitHub

๐Ÿ“ฆ Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. 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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/yamadashy/repomix with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/yamadashy/repomix'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yamadashy-repomix/badge.svg)](/listings/yamadashy-repomix)

HTML

<a href="/listings/yamadashy-repomix"><img src="/api/listings/yamadashy-repomix/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using the CLI Tool `>_`

You can try Repomix instantly in your project directory without installation:

npx repomix@latest

Or install globally for repeated use:

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json ยท Manifest ยท 27 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "repomix",
  3. "owner": {
  4. "name": "yamadashy"
  5. },
  6. "metadata": {
  7. "description": "Official Repomix plugins for Claude Code",
  8. "version": "1.0.2"
  9. },
  10. "plugins": [
  11. {
  12. "name": "repomix-mcp",
  13. "source": "./.claude/plugins/repomix-mcp",
  14. "category": "integration"
  15. },
  16. {
  17. "name": "repomix-commands",
  18. "source": "./.claude/plugins/repomix-commands",
  19. "category": "productivity"
  20. },
  21. {
  22. "name": "repomix-explorer",
  23. "source": "./.claude/plugins/repomix-explorer",
  24. "category": "productivity"
  25. }
  26. ]
  27. }
README.md ยท README ยท 2,026 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center" markdown="1">
  2. <sup>Special thanks to:</sup>
  3. <br>
  4. <br>
  5. <a href="https://go.warp.dev/repomix">
  6. <img alt="Warp sponsorship" width="400" src="https://raw.githubusercontent.com/warpdotdev/brand-assets/main/Github/Sponsor/Warp-Github-LG-01.png">
  7. </a>
  8. ### [Warp, built for coding with multiple AI agents](https://go.warp.dev/repomix)
  9. [Available for MacOS, Linux, & Windows](https://go.warp.dev/repomix)<br>
  10. <br>
  11. <a href="https://coderabbit.link/repomix">
  12. <picture>
  13. <source media="(prefers-color-scheme: dark)" srcset="website/client/src/public/images/sponsors/coderabbit/dark.png">
  14. <img alt="CodeRabbit sponsorship" width="400" src="website/client/src/public/images/sponsors/coderabbit/light.png">
  15. </picture>
  16. </a>
  17. ### [CodeRabbit | AI Code Reviews](https://coderabbit.link/repomix)
  18. [Cut code review time & bugs in half, instantly.](https://coderabbit.link/repomix)<br>
  19. </div>
  20. <hr />
  21. <div align="center">
  22. <a href="https://repomix.com">
  23. <img src="website/client/src/public/images/repomix-title.png" alt="Repomix" width="500" height="auto" />
  24. </a>
  25. <p align="center">
  26. <b>Pack your codebase into AI-friendly formats</b>
  27. </p>
  28. </div>
  29. <p align="center">
  30. <a href="https://repomix.com"><b>Use Repomix online! ๐Ÿ‘‰ repomix.com</b></a><br>
  31. </p>
  32. <p align="center">
  33. Need discussion? Join us on <a href="https://discord.gg/wNYzTwZFku">Discord</a>!<br>
  34. <i>Share your experience and tips</i><br>
  35. <i>Stay updated on new features</i><br>
  36. <i>Get help with configuration and usage</i><br>
  37. </p>
  38. <hr />
  39. [![npm](https://img.shields.io/npm/v/repomix.svg?maxAge=1000)](https://www.npmjs.com/package/repomix)
  40. [![npm](https://img.shields.io/npm/d18m/repomix)](https://www.npmjs.com/package/repomix)
  41. [![Actions Status](https://github.com/yamadashy/repomix/actions/workflows/ci.yml/badge.svg)](https://github.com/yamadashy/repomix/actions?query=workflow%3A"ci")
  42. [![codecov](https://codecov.io/github/yamadashy/repomix/graph/badge.svg?token=PYQHDJ5SHX)](https://codecov.io/github/yamadashy/repomix)
  43. [![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/yamadashy/repomix?utm_source=oss&utm_medium=github&utm_campaign=yamadashy%2Frepomix&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)](https://coderabbit.ai)
  44. [![Sponsors](https://img.shields.io/github/sponsors/yamadashy?logo=github)](https://github.com/sponsors/yamadashy)
  45. [![Discord](https://badgen.net/discord/online-members/wNYzTwZFku?icon=discord&label=discord)](https://discord.gg/wNYzTwZFku)
  46. [![DeepWiki](https://img.shields.io/badge/DeepWiki-yamadashy%2Frepomix-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/yamadashy/repomix)
  47. <!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
  48. ๐Ÿ“ฆ Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file.
  49. It is perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude,
  50. ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.
  51. Please consider sponsoring me.
  52. [![Sponsor](.github/assets/github-like-sponsor-button.svg)](https://github.com/sponsors/yamadashy)
  53. [![Sponsors](https://cdn.jsdelivr.net/gh/yamadashy/sponsor-list/sponsors/sponsors.png)](https://github.com/sponsors/yamadashy)
  54. ## ๐Ÿ† Open Source Awards Nomination
  55. We're honored! Repomix has been nominated for the **Powered by AI** category at the [JSNation Open Source Awards 2025](https://osawards.com/javascript/).
  56. This wouldn't have been possible without all of you using and supporting Repomix. Thank you!
  57. ## ๐ŸŽ‰ New: Repomix Website & Discord Community!
  58. - Try Repomix in your browser at [repomix.com](https://repomix.com/)
  59. - Join our [Discord Server](https://discord.gg/wNYzTwZFku) for support and discussion
  60. **We look forward to seeing you there!**
  61. ## ๐ŸŒŸ Features
  62. - **AI-Optimized**: Formats your codebase in a way that's easy for AI to understand and process.
  63. - **Token Counting**: Provides token counts for each file and the entire repository, useful for LLM context limits.
  64. - **Simple to Use**: You need just one command to pack your entire repository.
  65. - **Customizable**: Easily configure what to include or exclude.
  66. - **Git-Aware**: Automatically respects your `.gitignore`, `.ignore`, and `.repomixignore` files.
  67. - **Security-Focused**: Incorporates [Secretlint](https://github.com/secretlint/secretlint) to detect files matching known credential formats and leave them out of the output.
  68. - **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.
  69. ## ๐Ÿš€ Quick Start
  70. ### Using the CLI Tool `>_`
  71. You can try Repomix instantly in your project directory without installation:
  72. ```bash
  73. npx repomix@latest
  74. ```
  75. Or install globally for repeated use:
  76. ```bash
  77. # Install using npm
  78. npm install -g repomix
  79. # Alternatively using yarn
  80. yarn global add repomix
  81. # Alternatively using bun
  82. bun add -g repomix
  83. # Alternatively using Homebrew (macOS/Linux)
  84. brew install repomix
  85. # Then run in any project directory
  86. repomix
  87. ```
  88. That's it! Repomix will generate a `repomix-output.xml` file in your current directory, containing your entire
  89. repository in an AI-friendly format.
  90. You can then send this file to an AI assistant with a prompt like:
  91. ```
  92. This file contains all the files in the repository combined into one.
  93. I want to refactor the code, so please review it first.
  94. ```
  95. ![Repomix File Usage 1](website/client/src/public/images/docs/repomix-file-usage-1.png)
  96. When you propose specific changes, the AI might be able to generate code accordingly. With features like Claude's
  97. Artifacts, you could potentially output multiple files, allowing for the generation of multiple interdependent pieces of
  98. code.
  99. ![Repomix File Usage 2](website/client/src/public/images/docs/repomix-file-usage-2.png)
  100. Happy coding! ๐Ÿš€
  101. ### Using The Website ๐ŸŒ
  102. Want to try it quickly? Visit the official website at [repomix.com](https://repomix.com). Simply enter your repository
  103. name, fill in any optional details, and click the **Pack** button to see your generated output.
  104. #### Available Options
  105. The website offers several convenient features:
  106. - Customizable output format (XML, Markdown, or Plain Text)
  107. - Instant token count estimation
  108. - Much more!
  109. ### Using The Browser Extension ๐Ÿงฉ
  110. Get instant access to Repomix directly from any GitHub repository! Our Chrome extension adds a convenient "Repomix" button to GitHub repository pages.
  111. ![Repomix Browser Extension](website/client/src/public/images/docs/browser-extension.png)
  112. #### Install
  113. - Chrome Extension: [Repomix - Chrome Web Store](https://chromewebstore.google.com/detail/repomix/fimfamikepjgchehkohedilpdigcpkoa)
  114. - Firefox Add-on: [Repomix - Firefox Add-ons](https://addons.mozilla.org/firefox/addon/repomix/)
  115. #### Features
  116. - One-click access to Repomix for any GitHub repository
  117. - More exciting features coming soon!
  118. ### Using The VSCode Extension โšก๏ธ
  119. 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.
  120. 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.
  121. Try it now on the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=DorianMassoulier.repomix-runner)!
  122. Source code is available on [GitHub](https://github.com/massdo/repomix-runner).
  123. ### Alternative Tools ๐Ÿ› ๏ธ
  124. If you're using Python, you might want to check out `Gitingest`, which is better suited for Python ecosystem and data
  125. science workflows:
  126. https://github.com/cyclotruc/gitingest
  127. ## ๐Ÿ“Š Usage
  128. To pack your entire repository:
  129. ```bash
  130. repomix
  131. ```
  132. To pack a specific directory:
  133. ```bash
  134. repomix path/to/directory
  135. ```
  136. To pack specific files or directories
  137. using [glob patterns](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax):
  138. ```bash
  139. repomix --include "src/**/*.ts,**/*.md"
  140. ```
  141. To exclude specific files or directories:
  142. ```bash
  143. repomix --ignore "**/*.log,tmp/"
  144. ```
  145. To pack a remote repository:
  146. ```bash
  147. repomix --remote https://github.com/yamadashy/repomix
  148. # You can also use GitHub shorthand:
  149. repomix --remote yamadashy/repomix
  150. # You can specify the branch name, tag, or commit hash:
  151. repomix --remote https://github.com/yamadashy/repomix --remote-branch main
  152. # Or use a specific commit hash:
  153. repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695
  154. # Another convenient way is specifying the branch's URL
  155. repomix --remote https://github.com/yamadashy/repomix/tree/main
  156. # Commit's URL is also supported
  157. repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1
  158. ```
  159. To pack files from a file list (pipe via stdin):
  160. ```bash
  161. # Using find command
  162. find src -name "*.ts" -type f | repomix --stdin
  163. # Using git to get tracked files
  164. git ls-files "*.ts" | repomix --stdin
  165. # Using grep to find files containing specific content
  166. grep -l "TODO" **/*.ts | repomix --stdin
  167. # Using ripgrep to find files with specific content
  168. rg -l "TODO|FIXME" --type ts | repomix --stdin
  169. # Using ripgrep (rg) to find files
  170. rg --files --type ts | repomix --stdin
  171. # Using sharkdp/fd to find files
  172. fd -e ts | repomix --stdin
  173. # Using fzf to select from all files
  174. fzf -m | repomix --stdin
  175. # Interactive file selection with fzf
  176. find . -name "*.ts" -type f | fzf -m | repomix --stdin
  177. # Using ls with glob patterns
  178. ls src/**/*.ts | repomix --stdin
  179. # From a file containing file paths
  180. cat file-list.txt | repomix --stdin
  181. # Direct input with echo
  182. echo -e "src/index.ts\nsrc/utils.ts" | repomix --stdin
  183. ```
  184. The `--stdin` option allows you to pipe a list of file paths to Repomix, giving you ultimate flexibility in selecting which files to pack.
  185. 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.
  186. > [!NOTE]
  187. > When using `--stdin`, file paths can be relative or absolute, and Repomix will automatically handle path resolution and deduplication.
  188. To include git logs in the output:
  189. ```bash
  190. # Include git logs with default count (50 commits)
  191. repomix --include-logs
  192. # Include git logs with specific commit count
  193. repomix --include-logs --include-logs-count 10
  194. # Combine with diffs for comprehensive git context
  195. repomix --include-logs --include-diffs
  196. ```
  197. 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.
  198. To compress the output:
  199. ```bash
  200. repomix --compress
  201. # You can also use it with remote repositories:
  202. repomix --remote yamadashy/repomix --compress
  203. ```
  204. To initialize a new configuration file (`repomix.config.json`):
  205. ```bash
  206. repomix --init
  207. ```
  208. 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.
  209. ### Docker Usage ๐Ÿณ
  210. You can also run Repomix using Docker.
  211. This is useful if you want to run Repomix in an isolated environment or prefer using containers.
  212. Basic usage (current directory):
  213. ```bash
  214. docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix
  215. ```
  216. To pack a specific directory:
  217. ```bash
  218. docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix path/to/directory
  219. ```
  220. Process a remote repository and output to a `output` directory:
  221. ```bash
  222. docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote https://github.com/yamadashy/repomix
  223. ```
  224. ### Prompt Examples
  225. 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.
  226. Here are some example prompts to get you started:
  227. #### Code Review and Refactoring
  228. For a comprehensive code review and refactoring suggestions:
  229. ```
  230. This file contains my entire codebase. Please review the overall structure and suggest any improvements or refactoring opportunities, focusing on maintainability and scalability.
  231. ```
  232. #### Documentation Generation
  233. To generate project documentation:
  234. ```
  235. 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.
  236. ```
  237. #### Test Case Generation
  238. For generating test cases:
  239. ```
  240. 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.
  241. ```
  242. #### Code Quality Assessment
  243. Evaluate code quality and adherence to best practices:
  244. ```
  245. 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.
  246. ```
  247. #### Library Overview
  248. Get a high-level understanding of the library
  249. ```
  250. 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.
  251. ```
  252. Feel free to modify these prompts based on your specific needs and the capabilities of the AI tool you're using.
  253. ### Community Discussion
  254. Check out our [community discussion](https://github.com/yamadashy/repomix/discussions/154) where users share:
  255. - Which AI tools they're using with Repomix
  256. - Effective prompts they've discovered
  257. - How Repomix has helped them
  258. - Tips and tricks for getting the most out of AI code analysis
  259. Feel free to join the discussion and share your own experiences! Your insights could help others make better use of
  260. Repomix.
  261. ### Output File Format
  262. Repomix generates a single file with clear separators between different parts of your codebase.
  263. To enhance AI comprehension, the output file begins with an AI-oriented explanation, making it easier for AI models to
  264. understand the context and structure of the packed repository.
  265. #### XML Format (default)
  266. The XML format structures the content in a hierarchical manner:
  267. ```xml
  268. This file is a merged representation of the entire codebase, combining all repository files into a single document.
  269. <file_summary>
  270. (Metadata and usage AI instructions)
  271. </file_summary>
  272. <directory_structure>
  273. src/
  274. cli/
  275. cliOutput.ts
  276. index.ts
  277. (...remaining directories)
  278. </directory_structure>
  279. <files>
  280. <file path="src/index.js">
  281. // File contents here
  282. </file>
  283. (...remaining files)
  284. </files>
  285. <instruction>
  286. (Custom instructions from `output.instructionFilePath`)
  287. </instruction>
  288. ```
  289. For those interested in the potential of XML tags in AI contexts:
  290. https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags
  291. > When your prompts involve multiple components like context, instructions, and examples, XML tags can be a
  292. > game-changer. They help Claude parse your prompts more accurately, leading to higher-quality outputs.
  293. This means that the XML output from Repomix is not just a different format, but potentially a more effective way to feed
  294. your codebase into AI systems for analysis, code review, or other tasks.
  295. #### Markdown Format
  296. To generate output in Markdown format, use the `--style markdown` option:
  297. ```bash
  298. repomix --style markdown
  299. ```
  300. The Markdown format structures the content in a hierarchical manner:
  301. ````markdown
  302. This file is a merged representation of the entire codebase, combining all repository files into a single document.
  303. # File Summary
  304. (Metadata and usage AI instructions)
  305. # Repository Structure
  306. ```
  307. src/
  308. cli/
  309. cliOutput.ts
  310. index.ts
  311. ```
  312. (...remaining directories)
  313. # Repository Files
  314. ## File: src/index.js
  315. ```
  316. // File contents here
  317. ```
  318. (...remaining files)
  319. # Instruction
  320. (Custom instructions from `output.instructionFilePath`)
  321. ````
  322. This format provides a clean, readable structure that is both human-friendly and easily parseable by AI systems.
  323. #### JSON Format
  324. To generate output in JSON format, use the `--style json` option:
  325. ```bash
  326. repomix --style json
  327. ```
  328. The JSON format structures the content as a hierarchical JSON object with camelCase property names:
  329. ```json
  330. {
  331. "fileSummary": {
  332. "generationHeader": "This file is a merged representation of the entire codebase, combined into a single document by Repomix.",
  333. "purpose": "This file contains a packed representation of the entire repository's contents...",
  334. "fileFormat": "The content is organized as follows...",
  335. "usageGuidelines": "- This file should be treated as read-only...",
  336. "notes": "- Some files may have been excluded based on .gitignore, .ignore, and .repomixignore rules..."
  337. },
  338. "userProvidedHeader": "Custom header text if specified",
  339. "directoryStructure": "src/\n cli/\n cliOutput.ts\n index.ts\n config/\n configLoader.ts",
  340. "files": {
  341. "src/index.js": "// File contents here",
  342. "src/utils.js": "// File contents here"
  343. },
  344. "instruction": "Custom instructions from instructionFilePath"
  345. }
  346. ```
  347. This format is ideal for:
  348. - **Programmatic processing**: Easy to parse and manipulate with JSON libraries
  349. - **API integration**: Direct consumption by web services and applications
  350. - **AI tool compatibility**: Structured format for machine learning and AI systems
  351. - **Data analysis**: Straightforward extraction of specific information using tools like `jq`
  352. ##### Working with JSON Output Using `jq`
  353. The JSON format makes it easy to extract specific information programmatically:
  354. ```bash
  355. # List all file paths
  356. cat repomix-output.json | jq -r '.files | keys[]'
  357. # Count total number of files
  358. cat repomix-output.json | jq '.files | keys | length'
  359. # Extract specific file content
  360. cat repomix-output.json | jq -r '.files["README.md"]'
  361. cat repomix-output.json | jq -r '.files["src/index.js"]'
  362. # Find files by extension
  363. cat repomix-output.json | jq -r '.files | keys[] | select(endswith(".ts"))'
  364. # Get files containing specific text
  365. cat repomix-output.json | jq -r '.files | to_entries[] | select(.value | contains("function")) | .key'
  366. # Extract directory structure
  367. cat repomix-output.json | jq -r '.directoryStructure'
  368. # Get file summary information
  369. cat repomix-output.json | jq '.fileSummary.purpose'
  370. cat repomix-output.json | jq -r '.fileSummary.generationHeader'
  371. # Extract user-provided header (if exists)
  372. cat repomix-output.json | jq -r '.userProvidedHeader // "No header provided"'
  373. # Create a file list with sizes
  374. cat repomix-output.json | jq -r '.files | to_entries[] | "\(.key): \(.value | length) characters"'
  375. ```
  376. #### Plain Text Format
  377. To generate output in plain text format, use the `--style plain` option:
  378. ```bash
  379. repomix --style plain
  380. ```
  381. ```text
  382. This file is a merged representation of the entire codebase, combining all repository files into a single document.
  383. ================================================================
  384. File Summary
  385. ================================================================
  386. (Metadata and usage AI instructions)
  387. ================================================================
  388. Directory Structure
  389. ================================================================
  390. src/
  391. cli/
  392. cliOutput.ts
  393. index.ts
  394. config/
  395. configLoader.ts
  396. (...remaining directories)
  397. ================================================================
  398. Files
  399. ================================================================
  400. ================
  401. File: src/index.js
  402. ================
  403. // File contents here
  404. ================
  405. File: src/utils.js
  406. ================
  407. // File contents here
  408. (...remaining files)
  409. ================================================================
  410. Instruction
  411. ================================================================
  412. (Custom instructions from `output.instructionFilePath`)
  413. ```
  414. ### Command Line Options
  415. #### Basic Options
  416. - `-v, --version`: Show version information and exit
  417. #### CLI Input/Output Options
  418. | Option | Description |
  419. |--------|-------------|
  420. | `--verbose` | Enable detailed debug logging (shows file processing, token counts, and configuration details) |
  421. | `--quiet` | Suppress all console output except errors (useful for scripting) |
  422. | `--stdout` | Write packed output directly to stdout instead of a file (suppresses all logging) |
  423. | `--stdin` | Read file paths from stdin, one per line (specified files are processed directly) |
  424. | `--copy` | Copy the generated output to system clipboard after processing |
  425. | `--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`) |
  426. | `--top-files-len <number>` | Number of largest files to show in summary (default: `5`) |
  427. #### Repomix Output Options
  428. | Option | Description |
  429. |--------|-------------|
  430. | `-o, --output <file>` | Output file path (default: `repomix-output.xml`, use `"-"` for stdout) |
  431. | `--style <style>` | Output format: `xml`, `markdown`, `json`, or `plain` (default: `xml`) |
  432. | `--output-file-path-style <style>` | How file paths are shown in output: `target-relative` or `cwd-relative` (default: `target-relative`) |
  433. | `--parsable-style` | Escape special characters to ensure valid XML/Markdown (needed when output contains code that breaks formatting) |
  434. | `--compress` | Extract essential code structure (classes, functions, interfaces) using Tree-sitter parsing |
  435. | `--output-show-line-numbers` | Prefix each line with its line number in the output |
  436. | `--no-file-summary` | Omit the file summary section from output |
  437. | `--no-directory-structure` | Omit the directory tree visualization from output |
  438. | `--no-files` | Generate metadata only without file contents (useful for repository analysis) |
  439. | `--remove-comments` | Strip all code comments before packing |
  440. | `--remove-empty-lines` | Remove blank lines from all files |
  441. | `--truncate-base64` | Truncate long base64 data strings to reduce output size |
  442. | `--header-text <text>` | Custom text to include at the beginning of the output |
  443. | `--instruction-file-path <path>` | Path to file containing custom instructions to include in output |
  444. | `--split-output <size>` | Split output into multiple numbered files (e.g., `repomix-output.1.xml`); size like `500kb`, `2mb`, or `1.5mb` |
  445. | `--include-empty-directories` | Include folders with no files in directory structure |
  446. | `--include-full-directory-structure` | Show complete directory tree in output, including files not matched by `--include` patterns |
  447. | `--no-git-sort-by-changes` | Don't sort files by git change frequency (default: most changed files first) |
  448. | `--include-diffs` | Add git diff section showing working tree and staged changes |
  449. | `--include-logs` | Add git commit history with messages and changed files |
  450. | `--include-logs-count <count>` | Number of recent commits to include with `--include-logs` (default: `50`) |
  451. #### File Selection Options
  452. | Option | Description |
  453. |--------|-------------|
  454. | `--include <patterns>` | Include only files matching these glob patterns (comma-separated, e.g., `"src/**/*.js,*.md"`) |
  455. | `-i, --ignore <patterns>` | Additional patterns to exclude (comma-separated, e.g., `"*.test.js,docs/**"`) |
  456. | `--no-gitignore` | Don't use `.gitignore` rules for filtering files |
  457. | `--no-dot-ignore` | Don't use `.ignore` rules for filtering files |
  458. | `--no-default-patterns` | Don't apply built-in ignore patterns (`node_modules`, `.git`, build dirs, etc.) |
  459. #### Remote Repository Options
  460. | Option | Description |
  461. |--------|-------------|
  462. | `--remote <url>` | Clone and pack a remote repository (GitHub URL or `user/repo` format) |
  463. | `--remote-branch <name>` | Specific branch, tag, or commit to use (default: repository's default branch) |
  464. | `--remote-trust-config` | Trust and load config files from remote repositories (disabled by default for security). On an interactive terminal, the config is shown and you are asked to confirm |
  465. #### Configuration Options
  466. | Option | Description |
  467. |--------|-------------|
  468. | `-c, --config <path>` | Use custom config file instead of `repomix.config.json` |
  469. | `--init` | Create a new `repomix.config.json` file with defaults |
  470. | `--global` | With `--init`, create config in home directory instead of current directory |
  471. #### Security Options
  472. - `--no-security-check`: Skip scanning for sensitive data like API keys and passwords
  473. #### Token Count Options
  474. - `--token-count-encoding <encoding>`: Tokenizer model for counting: o200k_base (GPT-4o), cl100k_base (GPT-3.5/4), etc. (default: o200k_base)
  475. - `--token-budget <number>`: Fail with a non-zero exit code when the packed output exceeds N tokens. Useful as a guard in CI pipelines and agent workflows to keep output within a target model's context window. The output is still generated; only the exit code signals the overflow.
  476. #### MCP
  477. - `--mcp`: Run as Model Context Protocol server for AI tool integration
  478. - `--sandbox [dir]`: (with `--mcp`) confine the MCP server's file tools to a workspace directory (defaults to the working directory; e.g. `--sandbox path/to/project`) โ€” every path is relative to that root, absolute/host paths are refused, and remote packing, skill generation, and attaching external outputs are disabled.
  479. #### Agent Skills Generation
  480. | Option | Description |
  481. |--------|-------------|
  482. | `--skill-generate [name]` | Generate Claude Agent Skills format output to `.claude/skills/<name>/` directory (name auto-generated if omitted) |
  483. | `--skill-project-name <name>` | Override the project name used in generated Skills descriptions |
  484. | `--skill-output <path>` | Specify skill output directory path directly (skips location prompt) |
  485. | `-f, --force` | Skip all confirmation prompts (skill directory overwrite, remote config trust) |
  486. #### Watch Mode
  487. - `-w, --watch`: Watch for file changes and automatically re-pack. Debounces rapid changes (300ms) and logs a timestamp on each rebuild. Stop with `Ctrl+C`.
  488. Watch mode only works with local directories, so it cannot be combined with `--remote`, a positional remote repository URL, `--stdout`, `--stdin`, `--split-output`, `--skill-generate`, or `--copy` (whether set on the command line or in your config file).
  489. #### Examples
  490. ```bash
  491. # Basic usage
  492. repomix
  493. # Custom output
  494. repomix -o output.xml --style xml
  495. # Output to stdout
  496. repomix --stdout > custom-output.txt
  497. # Send output to stdout, then pipe into another command (for example, simonw/llm)
  498. repomix --stdout | llm "Please explain what this code does."
  499. # Custom output with compression
  500. repomix --compress
  501. # Process specific files
  502. repomix --include "src/**/*.ts" --ignore "**/*.test.ts"
  503. # Split output into multiple files (max size per part)
  504. repomix --split-output 20mb
  505. # Remote repository with branch
  506. repomix --remote https://github.com/user/repo/tree/main
  507. # Remote repository with commit
  508. repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1
  509. # Remote repository with shorthand
  510. repomix --remote user/repo
  511. # Watch mode โ€” automatically re-pack on file changes
  512. repomix --watch
  513. repomix -w --include "src/**/*.ts"
  514. ```
  515. ### Updating Repomix
  516. To update a globally installed Repomix:
  517. ```bash
  518. # Using npm
  519. npm update -g repomix
  520. # Using yarn
  521. yarn global upgrade repomix
  522. # Using bun
  523. bun update -g repomix
  524. ```
  525. Using `npx repomix` is generally more convenient as it always uses the latest version.
  526. ### Remote Repository Processing
  527. Repomix supports processing remote Git repositories without the need for manual cloning. This feature allows you to
  528. quickly analyze any public Git repository with a single command.
  529. To process a remote repository, use the `--remote` option followed by the repository URL:
  530. ```bash
  531. repomix --remote https://github.com/yamadashy/repomix
  532. ```
  533. You can also use GitHub's shorthand format:
  534. ```bash
  535. repomix --remote yamadashy/repomix
  536. ```
  537. You can specify the branch name, tag, or commit hash:
  538. ```bash
  539. # Using --remote-branch option
  540. repomix --remote https://github.com/yamadashy/repomix --remote-branch main
  541. # Using branch's URL
  542. repomix --remote https://github.com/yamadashy/repomix/tree/main
  543. ```
  544. Or use a specific commit hash:
  545. ```bash
  546. # Using --remote-branch option
  547. repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695
  548. # Using commit's URL
  549. repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1
  550. ```
  551. > [!NOTE]
  552. > For security, config files (`repomix.config.*`) in remote repositories are not loaded by default. This prevents untrusted repositories from executing code via config files. Your global config and CLI options are still applied. To trust a remote repository's config, use `--remote-trust-config` or set `REPOMIX_REMOTE_TRUST_CONFIG=true` โ€” on an interactive terminal Repomix then shows that config and asks you to confirm before loading it. See [Remote Repository Config Trust](#remote-repository-config-trust).
  553. >
  554. > When using `--config` with `--remote`, an absolute path is required (e.g., `--config /home/user/repomix.config.json`).
  555. ### Code Compression
  556. 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.
  557. ```bash
  558. repomix --compress
  559. ```
  560. For example, this code:
  561. ```typescript
  562. import { ShoppingItem } from './shopping-item';
  563. /**
  564. * Calculate the total price of shopping items
  565. */
  566. const calculateTotal = (
  567. items: ShoppingItem[]
  568. ) => {
  569. let total = 0;
  570. for (const item of items) {
  571. total += item.price * item.quantity;
  572. }
  573. return total;
  574. }
  575. // Shopping item interface
  576. interface Item {
  577. name: string;
  578. price: number;
  579. quantity: number;
  580. }
  581. ```
  582. Will be compressed to:
  583. ```typescript
  584. import { ShoppingItem } from './shopping-item';
  585. โ‹ฎ----
  586. /**
  587. * Calculate the total price of shopping items
  588. */
  589. const calculateTotal = (
  590. items: ShoppingItem[]
  591. ) => {
  592. โ‹ฎ----
  593. // Shopping item interface
  594. interface Item {
  595. name: string;
  596. price: number;
  597. quantity: number;
  598. }
  599. ```
  600. > [!NOTE]
  601. > This is an experimental feature that we'll be actively improving based on user feedback and real-world usage
  602. ### Per-file Inclusion Levels (`output.patterns`)
  603. While `--compress` applies one level to every file, `output.patterns` lets you control the detail level **per glob** from your config file. Each entry targets files by glob (matched the same way as `include`/`ignore`) and overrides the global `output.compress` setting for matching files:
  604. ```json5
  605. {
  606. "output": {
  607. "compress": false, // global default acts as the catch-all
  608. "patterns": [
  609. { "pattern": "docs/**/*", "compress": true },
  610. { "pattern": "website/**/*", "directoryStructureOnly": true }
  611. ]
  612. }
  613. }
  614. ```
  615. There are three levels:
  616. - **Full content** (default) โ€” the file's full content is included.
  617. - **Compressed** (`compress: true`) โ€” the content is passed through the same Tree-sitter pipeline as `--compress`.
  618. - **Directory-structure-only** (`directoryStructureOnly: true`) โ€” the file is listed in the directory structure, but its content block is omitted from the output entirely.
  619. Semantics:
  620. - Patterns are evaluated in array order and the **first matching pattern wins** for a given file.
  621. - A matched pattern's flags override the global `output.compress` setting. A pattern that matches without setting either flag forces **full content** for that file (useful for whitelisting files out of a global `compress`).
  622. - `directoryStructureOnly` takes precedence over `compress` when both are set.
  623. - If no pattern matches, the global behavior applies (full content, or compressed when `output.compress` is `true`).
  624. This is a config-file-only option; there is no CLI flag for per-pattern levels.
  625. ### Token Count Optimization
  626. 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:
  627. ```bash
  628. repomix --token-count-tree
  629. ```
  630. This displays a hierarchical view of your codebase with token counts:
  631. ```
  632. ๐Ÿ”ข Token Count Tree:
  633. โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
  634. โ””โ”€โ”€ src/ (70,925 tokens)
  635. โ”œโ”€โ”€ cli/ (12,714 tokens)
  636. โ”‚ โ”œโ”€โ”€ actions/ (7,546 tokens)
  637. โ”‚ โ””โ”€โ”€ reporters/ (990 tokens)
  638. โ””โ”€โ”€ core/ (41,600 tokens)
  639. โ”œโ”€โ”€ file/ (10,098 tokens)
  640. โ””โ”€โ”€ output/ (5,808 tokens)
  641. ```
  642. You can also set a minimum token threshold to focus on larger files:
  643. ```bash
  644. repomix --token-count-tree 1000 # Only show files/directories with 1000+ tokens
  645. ```
  646. This helps you:
  647. - **Identify token-heavy files** that might exceed AI context limits
  648. - **Optimize file selection** using `--include` and `--ignore` patterns
  649. - **Plan compression strategies** by targeting the largest contributors
  650. - **Balance content vs. context** when preparing code for AI analysis
  651. ### Splitting Output for Large Codebases
  652. When working with large codebases, the packed output may exceed file size limits imposed by some AI tools (e.g., Google AI Studio's 1MB limit). Use `--split-output` to automatically split the output into multiple files:
  653. ```bash
  654. repomix --split-output 1mb
  655. ```
  656. This generates numbered files like:
  657. - `repomix-output.1.xml`
  658. - `repomix-output.2.xml`
  659. - `repomix-output.3.xml`
  660. Size can be specified with units: `500kb`, `1mb`, `2mb`, `1.5mb`, etc. Decimal values are supported.
  661. > [!NOTE]
  662. > Files are grouped by top-level directory to maintain context. A single file or directory will never be split across multiple output files.
  663. ### MCP Server Integration
  664. 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.
  665. ```bash
  666. repomix --mcp
  667. ```
  668. #### Sandbox Mode
  669. By default the MCP server can read any path the host user can. That is convenient for a trusted local assistant, but too broad when the server is exposed to an untrusted client or agent. The `--sandbox` flag confines the server's file tools to a single workspace directory:
  670. ```bash
  671. # Confine to the current working directory
  672. repomix --mcp --sandbox
  673. # Confine to a specific directory
  674. repomix --mcp --sandbox path/to/project
  675. ```
  676. When sandbox mode is on, every path is relative to the workspace root (absolute, `~`, `..`, and Windows drive/UNC paths are refused, as are paths that resolve outside the root through symlinks), config files are not loaded, and only the read-only, root-confined tools are registered; remote packing, skill generation, and attaching external outputs are disabled. The raw file tools (`file_system_read_file`, `file_system_read_directory`) are available only in sandbox mode, where the workspace root bounds what they can reach. This is an application-level confinement of the tool surface, not an OS-level sandbox.
  677. Without `--sandbox`, `pack_codebase` loads and trusts the `repomix.config.*` in the directory it packs, the same as running `repomix` there from the command line. A config file is code: it can run when loaded and read files outside the repository. If your assistant may pack directories you don't trust, such as cloned third-party repositories, use `--sandbox`. See the [MCP Server guide](https://repomix.com/guide/mcp-server) for details.
  678. #### Configuring MCP Servers
  679. To use Repomix as an MCP server with AI assistants like Claude, you need to configure the MCP settings:
  680. **For VS Code:**
  681. You can install the Repomix MCP server in VS Code using one of these methods:
  682. 1. **Using the Install Badge:**
  683. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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)
  684. [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](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)
  685. 2. **Using the Command Line:**
  686. ```bash
  687. code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'
  688. ```
  689. For VS Code Insiders:
  690. ```bash
  691. code-insiders --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'
  692. ```
  693. **For Cline (VS Code extension):**
  694. Edit the `cline_mcp_settings.json` file:
  695. ```json
  696. {
  697. "mcpServers": {
  698. "repomix": {
  699. "command": "npx",
  700. "args": [
  701. "-y",
  702. "repomix",
  703. "--mcp"
  704. ]
  705. }
  706. }
  707. }
  708. ```
  709. **For Cursor:**
  710. In Cursor, add a new MCP server from `Cursor Settings` > `MCP` > `+ Add new global MCP server` with a configuration similar to Cline.
  711. **For Claude Desktop:**
  712. Edit the `claude_desktop_config.json` file with similar configuration to Cline's config.
  713. **For Claude Code:**
  714. To configure Repomix as an MCP server in [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), use the following command:
  715. ```bash
  716. claude mcp add repomix -- npx -y repomix --mcp
  717. ```
  718. Alternatively, you can use the official Repomix plugins (see [Claude Code Plugins](#claude-code-plugins) section below).
  719. **Using Docker instead of npx:**
  720. You can use Docker as an alternative to npx for running Repomix as an MCP server:
  721. ```json
  722. {
  723. "mcpServers": {
  724. "repomix-docker": {
  725. "command": "docker",
  726. "args": [
  727. "run",
  728. "-i",
  729. "--rm",
  730. "ghcr.io/yamadashy/repomix",
  731. "--mcp"
  732. ]
  733. }
  734. }
  735. }
  736. ```
  737. Once configured, your AI assistant can directly use Repomix's capabilities to analyze codebases without manual file preparation, making code analysis workflows more efficient.
  738. #### Available MCP Tools
  739. When running as an MCP server, Repomix provides the following tools:
  740. 1. **pack_codebase**: Package a local code directory into a consolidated XML file for AI analysis
  741. - Parameters:
  742. - `directory`: Absolute path to the directory to pack
  743. - `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.
  744. - `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.
  745. - `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, .ignore, and built-in exclusions.
  746. - `outputPatterns`: (Optional) Per-file inclusion levels, mirroring the config-file `output.patterns` option. An array of `{ pattern, compress?, directoryStructureOnly? }` entries; the first matching pattern wins, `directoryStructureOnly` takes precedence over `compress`, and a match with neither flag forces full content (useful for exempting files from a global `compress`). Overrides any `output.patterns` from the target repository's `repomix.config.json`.
  747. - `topFilesLength`: (Optional, default: 10) Number of largest files by size to display in the metrics summary for codebase analysis.
  748. 2. **attach_packed_output**: Attach an existing Repomix packed output file for AI analysis
  749. - Parameters:
  750. - `path`: Path to a directory containing repomix-output.xml or direct path to a packed repository XML file
  751. - `topFilesLength`: (Optional, default: 10) Number of largest files by size to display in the metrics summary
  752. - Features:
  753. - Accepts either a directory containing a repomix-output.xml file or a direct path to an XML file
  754. - Registers the file with the MCP server and returns the same structure as the pack_codebase tool
  755. - Provides access to existing packed outputs without requiring re-processing
  756. - Useful for working with previously generated packed repositories
  757. 3. **pack_remote_repository**: Fetch, clone, and package a GitHub repository into a consolidated XML file for AI analysis
  758. - Parameters:
  759. - `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")
  760. - `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.
  761. - `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.
  762. - `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, .ignore, and built-in exclusions.
  763. - `outputPatterns`: (Optional) Per-file inclusion levels, mirroring the config-file `output.patterns` option. An array of `{ pattern, compress?, directoryStructureOnly? }` entries; the first matching pattern wins, `directoryStructureOnly` takes precedence over `compress`, and a match with neither flag forces full content (useful for exempting files from a global `compress`).
  764. - `topFilesLength`: (Optional, default: 10) Number of largest files by size to display in the metrics summary for codebase analysis.
  765. 4. **read_repomix_output**: Read the contents of a Repomix-generated output file. Supports partial reading with line range specification for large files.
  766. - Parameters:
  767. - `outputId`: ID of the Repomix output file to read
  768. - `startLine`: (Optional) Starting line number (1-based, inclusive). If not specified, reads from beginning.
  769. - `endLine`: (Optional) Ending line number (1-based, inclusive). If not specified, reads to end.
  770. - Features:
  771. - Specifically designed for web-based environments or sandboxed applications
  772. - Retrieves the content of previously generated outputs using their ID
  773. - Provides access to packed codebase without requiring file system access
  774. - Supports partial reading for large files
  775. 5. **grep_repomix_output**: Search for patterns in a Repomix output file using grep-like functionality with JavaScript RegExp syntax
  776. - Parameters:
  777. - `outputId`: ID of the Repomix output file to search
  778. - `pattern`: Search pattern (JavaScript RegExp regular expression syntax)
  779. - `contextLines`: (Optional, default: 0) Number of context lines to show before and after each match. Overridden by beforeLines/afterLines if specified.
  780. - `beforeLines`: (Optional) Number of context lines to show before each match (like grep -B). Takes precedence over contextLines.
  781. - `afterLines`: (Optional) Number of context lines to show after each match (like grep -A). Takes precedence over contextLines.
  782. - `ignoreCase`: (Optional, default: false) Perform case-insensitive matching
  783. - Features:
  784. - Uses JavaScript RegExp syntax for powerful pattern matching
  785. - Supports context lines for better understanding of matches
  786. - Allows separate control of before/after context lines
  787. - Case-sensitive and case-insensitive search options
  788. 6. **file_system_read_file**: Read a file inside the sandbox workspace. Only available in [sandbox mode](#sandbox-mode) (`--sandbox`), where the workspace root bounds what it can reach.
  789. - Parameters:
  790. - `path`: Path to the file to read, relative to the workspace root (e.g. `src/index.ts`)
  791. - Notes:
  792. - Not registered without `--sandbox`
  793. - Content matching known secret formats ([Secretlint](https://github.com/secretlint/secretlint)) is refused as an additional heuristic safeguard โ€” the access boundary is the workspace root, not the scan
  794. 7. **file_system_read_directory**: List the contents of a directory inside the sandbox workspace. Only available in [sandbox mode](#sandbox-mode) (`--sandbox`).
  795. - Parameters:
  796. - `path`: Path to the directory to list, relative to the workspace root (e.g. `.` or `src`)
  797. - Features:
  798. - Shows files and directories with clear indicators (`[FILE]` or `[DIR]`)
  799. - Useful for exploring project structure and understanding codebase organization
  800. ### Claude Code Plugins
  801. Repomix provides official plugins for [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) that integrate seamlessly with the AI-powered development environment.
  802. #### Installation
  803. **1. Add the Repomix plugin marketplace:**
  804. ```text
  805. /plugin marketplace add yamadashy/repomix
  806. ```
  807. **2. Install plugins:**
  808. ```text
  809. # Install MCP server plugin (recommended foundation)
  810. /plugin install repomix-mcp@repomix
  811. # Install commands plugin (extends functionality)
  812. /plugin install repomix-commands@repomix
  813. # Install repository explorer plugin (AI-powered analysis)
  814. /plugin install repomix-explorer@repomix
  815. ```
  816. **Note**: The `repomix-mcp` plugin is recommended as a foundation. The `repomix-commands` plugin provides convenient slash commands, while `repomix-explorer` adds AI-powered analysis capabilities. While you can install them independently, using all three provides the most comprehensive experience.
  817. **Alternatively, use the interactive plugin installer:**
  818. ```text
  819. /plugin
  820. ```
  821. This will open an interactive interface where you can browse and install available plugins.
  822. #### Available Plugins
  823. **1. repomix-mcp** (MCP Server Plugin)
  824. Foundation plugin that provides AI-powered codebase analysis through MCP server integration.
  825. **Features:**
  826. - Pack local and remote repositories
  827. - Read and search packed outputs
  828. - Automatic Tree-sitter compression (~70% token reduction)
  829. **2. repomix-commands** (Slash Commands Plugin)
  830. Provides convenient slash commands for quick operations with natural language support.
  831. **Available Commands:**
  832. - `/repomix-commands:pack-local` - Pack local codebase with various options
  833. - `/repomix-commands:pack-remote` - Pack and analyze remote GitHub repositories
  834. **Example usage:**
  835. ```text
  836. /repomix-commands:pack-local
  837. Pack this project as markdown with compression
  838. /repomix-commands:pack-remote yamadashy/repomix
  839. Pack only TypeScript files from the yamadashy/repomix repository
  840. ```
  841. **3. repomix-explorer** (AI Analysis Agent Plugin)
  842. AI-powered repository analysis agent that intelligently explores codebases using Repomix CLI.
  843. **Features:**
  844. - Natural language codebase exploration and analysis
  845. - Intelligent pattern discovery and code structure understanding
  846. - Incremental analysis using grep and targeted file reading
  847. - Automatic context management for large repositories
  848. **Available Commands:**
  849. - `/repomix-explorer:explore-local` - Analyze local codebase with AI assistance
  850. - `/repomix-explorer:explore-remote` - Analyze remote GitHub repositories with AI assistance
  851. **Example usage:**
  852. ```text
  853. /repomix-explorer:explore-local ./src
  854. Find all authentication-related code
  855. /repomix-explorer:explore-remote facebook/react
  856. Show me the main component architecture
  857. ```
  858. The agent automatically:
  859. 1. Runs `npx repomix@latest` to pack the repository
  860. 2. Uses Grep and Read tools to efficiently search the output
  861. 3. Provides comprehensive analysis without consuming excessive context
  862. #### Benefits
  863. - **Seamless Integration**: Claude can directly analyze codebases without manual preparation
  864. - **Natural Language**: Use conversational commands instead of remembering CLI syntax
  865. - **Always Latest**: Automatically uses `npx repomix@latest` for up-to-date features
  866. - **Secret Scanning**: Secretlint flags files matching known credential formats so they are left out of the output
  867. - **Token Optimization**: Tree-sitter compression for large codebases
  868. For more details, see the plugin documentation in the `.claude/plugins/` directory.
  869. ### Agent Skills Generation
  870. Repomix can generate [Claude Agent Skills](https://docs.anthropic.com/en/docs/claude-code/skills) format output, creating a structured Skills directory that can be used as a reusable codebase reference for AI assistants. This feature is particularly powerful when you want to reference implementations from remote repositories.
  871. #### Basic Usage
  872. ```bash
  873. # Generate Skills from local directory
  874. repomix --skill-generate
  875. # Generate with custom Skills name
  876. repomix --skill-generate my-project-reference
  877. # Generate with a custom project name in Skills descriptions
  878. repomix --skill-generate --skill-project-name "My Project"
  879. # Generate from remote repository
  880. repomix --remote https://github.com/user/repo --skill-generate
  881. ```
  882. When you run the command, Repomix prompts you to choose where to save the Skills:
  883. 1. **Personal Skills** (`~/.claude/skills/`) - Available across all projects on your machine
  884. 2. **Project Skills** (`.claude/skills/`) - Shared with your team via git
  885. #### Non-Interactive Usage
  886. For CI pipelines and automation scripts, you can skip all interactive prompts using `--skill-output` and `--force`:
  887. ```bash
  888. # Specify output directory directly
  889. repomix --skill-generate --skill-output ./my-skills
  890. # Skip overwrite confirmation with --force
  891. repomix --skill-generate --skill-output ./my-skills --force
  892. # Full non-interactive example
  893. repomix --remote user/repo --skill-generate my-skill --skill-output ./output --force
  894. ```
  895. #### Generated Structure
  896. The Skills are generated with the following structure:
  897. ```text
  898. .claude/skills/<skill-name>/
  899. โ”œโ”€โ”€ SKILL.md # Main Skills metadata & documentation
  900. โ””โ”€โ”€ references/
  901. โ”œโ”€โ”€ summary.md # Purpose, format, and statistics
  902. โ”œโ”€โ”€ project-structure.md # Directory tree with line counts
  903. โ”œโ”€โ”€ files.md # All file contents (grep-friendly)
  904. โ””โ”€โ”€ tech-stacks.md # Languages, frameworks, dependencies
  905. ```
  906. #### What's Included
  907. - **SKILL.md**: Contains Skills metadata, file/line/token counts, overview, and usage instructions
  908. - **summary.md**: Explains the Skills' purpose, usage guidelines, and provides statistics breakdown by file type and language
  909. - **project-structure.md**: Directory tree with line counts per file for easy file discovery
  910. - **files.md**: All file contents with syntax highlighting headers, optimized for grep-friendly searching
  911. - **tech-stacks.md**: Auto-detected tech stack per package from dependency files (`package.json`, `requirements.txt`, `Cargo.toml`, etc.)
  912. #### Auto-Generated Skills Names
  913. If no name is provided, Repomix auto-generates one:
  914. ```bash
  915. repomix src/ --skill-generate # โ†’ repomix-reference-src
  916. repomix --remote user/repo --skill-generate # โ†’ repomix-reference-repo
  917. repomix --skill-generate CustomName # โ†’ custom-name (normalized to kebab-case)
  918. ```
  919. #### Integration with Repomix Features
  920. Skills generation respects all standard Repomix options:
  921. ```bash
  922. # Generate Skills with file filtering
  923. repomix --skill-generate --include "src/**/*.ts" --ignore "**/*.test.ts"
  924. # Generate Skills with compression
  925. repomix --skill-generate --compress
  926. # Generate Skills from remote repository
  927. repomix --remote yamadashy/repomix --skill-generate
  928. ```
  929. ### Repomix Explorer Skill (Agent Skills)
  930. Repomix provides a ready-to-use **Repomix Explorer** skill that enables AI coding assistants to analyze and explore codebases using Repomix CLI. This skill is designed to work with various AI tools including Claude Code, Cursor, Codex, GitHub Copilot, and more.
  931. #### Quick Install
  932. For Claude Code, install the official Repomix Explorer plugin:
  933. ```text
  934. /plugin marketplace add yamadashy/repomix
  935. /plugin install repomix-explorer@repomix
  936. ```
  937. For Codex, Cursor, OpenClaw, and other Agent Skills-compatible assistants, install the standalone skill with the Skills CLI:
  938. ```bash
  939. npx skills add yamadashy/repomix --skill repomix-explorer
  940. ```
  941. To target a specific assistant, pass `--agent`:
  942. ```bash
  943. npx skills add yamadashy/repomix --skill repomix-explorer --agent codex
  944. npx skills add yamadashy/repomix --skill repomix-explorer --agent openclaw
  945. ```
  946. For Hermes Agent, install the single-file skill with Hermes Agent's native skills command:
  947. ```bash
  948. hermes skills install https://raw.githubusercontent.com/yamadashy/repomix/main/skills/repomix-explorer/SKILL.md
  949. ```
  950. #### What It Does
  951. Once installed, you can analyze codebases with natural language instructions.
  952. Analyze remote repositories:
  953. ```text
  954. "What's the structure of this repo?
  955. https://github.com/facebook/react"
  956. ```
  957. Explore local codebases:
  958. ```text
  959. "What's in this project?
  960. ~/projects/my-app"
  961. ```
  962. This is useful not only for understanding codebases, but also when you want to implement features by referencing your other repositories.
  963. ## โš™๏ธ Configuration
  964. Repomix supports multiple configuration file formats for flexibility and ease of use.
  965. ### Configuration File Formats
  966. Repomix will automatically search for configuration files in the following priority order:
  967. 1. **TypeScript** (`repomix.config.ts`, `repomix.config.mts`, `repomix.config.cts`)
  968. 2. **JavaScript/ES Module** (`repomix.config.js`, `repomix.config.mjs`, `repomix.config.cjs`)
  969. 3. **JSON** (`repomix.config.json5`, `repomix.config.jsonc`, `repomix.config.json`)
  970. #### JSON Configuration
  971. Create a `repomix.config.json` file in your project root:
  972. ```bash
  973. repomix --init
  974. ```
  975. This will create a `repomix.config.json` file with default settings.
  976. #### TypeScript Configuration
  977. TypeScript configuration files provide the best developer experience with full type checking and IDE support.
  978. **Installation:**
  979. To use TypeScript or JavaScript configuration with `defineConfig`, you need to install Repomix as a dev dependency:
  980. ```bash
  981. npm install -D repomix
  982. ```
  983. **Example:**
  984. ```typescript
  985. // repomix.config.ts
  986. import { defineConfig } from 'repomix';
  987. export default defineConfig({
  988. output: {
  989. filePath: 'output.xml',
  990. style: 'xml',
  991. removeComments: true,
  992. },
  993. ignore: {
  994. customPatterns: ['**/node_modules/**', '**/dist/**'],
  995. },
  996. });
  997. ```
  998. **Benefits:**
  999. - โœ… Full TypeScript type checking in your IDE
  1000. - โœ… Excellent IDE autocomplete and IntelliSense
  1001. - โœ… Use dynamic values (timestamps, environment variables, etc.)
  1002. **Dynamic Values Example:**
  1003. ```typescript
  1004. // repomix.config.ts
  1005. import { defineConfig } from 'repomix';
  1006. // Generate timestamp-based filename
  1007. const timestamp = new Date().toISOString().slice(0, 19).replace(/[:.]/g, '-');
  1008. export default defineConfig({
  1009. output: {
  1010. filePath: `output-${timestamp}.xml`,
  1011. style: 'xml',
  1012. },
  1013. });
  1014. ```
  1015. #### JavaScript Configuration
  1016. JavaScript configuration files work the same as TypeScript, supporting `defineConfig` and dynamic values.
  1017. ### Configuration Options
  1018. Here's an explanation of the configuration options:
  1019. | Option | Description | Default |
  1020. |----------------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------|
  1021. | `input.maxFileSize` | Maximum file size in bytes to process. Files larger than this will be skipped | `50000000` |
  1022. | `input.processors` | Ordered array of `{ pattern, command, timeout?, onError? }` entries that run an external command to transform matching files before packing (e.g. JSONโ†’TOON). First matching glob wins. Runs arbitrary commands, so it runs only for local CLI runs (and remote repos with `--remote-trust-config`). See [File Processors](#file-processors) | Not set |
  1023. | `output.filePath` | The name of the output file | `"repomix-output.xml"` |
  1024. | `output.style` | The style of the output (`xml`, `markdown`, `json`, `plain`) | `"xml"` |
  1025. | `output.filePathStyle` | How file paths are shown in output (`target-relative` keeps paths relative to each target root, `cwd-relative` keeps paths relative to the current working directory) | `"target-relative"` |
  1026. | `output.parsableStyle` | Whether to escape the output based on the chosen style schema. Note that this can increase token count. | `false` |
  1027. | `output.compress` | Whether to perform intelligent code extraction to reduce token count | `false` |
  1028. | `output.patterns` | Per-file inclusion levels. An ordered array of `{ pattern, compress?, directoryStructureOnly? }` entries; the first matching glob wins and overrides the global `output.compress` for that file. See [Per-file Inclusion Levels](#per-file-inclusion-levels-outputpatterns) | Not set |
  1029. | `output.headerText` | Custom text to include in the file header | `null` |
  1030. | `output.instructionFilePath` | Path to a file containing detailed custom instructions | `null` |
  1031. | `output.fileSummary` | Whether to include a summary section at the beginning of the output | `true` |
  1032. | `output.directoryStructure` | Whether to include the directory structure in the output | `true` |
  1033. | `output.files` | Whether to include file contents in the output | `true` |
  1034. | `output.removeComments` | Whether to remove comments from supported file types | `false` |
  1035. | `output.removeEmptyLines` | Whether to remove empty lines from the output | `false` |
  1036. | `output.showLineNumbers` | Whether to add line numbers to each line in the output | `false` |
  1037. | `output.truncateBase64` | Whether to truncate long base64 data strings (e.g., images) to reduce token count | `false` |
  1038. | `output.copyToClipboard` | Whether to copy the output to system clipboard in addition to saving the file | `false` |
  1039. | `output.splitOutput` | Split output into multiple numbered files by maximum size per part (e.g., `1000000` for ~1MB). Keeps each file under the limit and avoids splitting files across parts | Not set |
  1040. | `output.topFilesLength` | Number of top files to display in the summary. If set to 0, no summary will be displayed | `5` |
  1041. | `output.tokenCountTree` | Whether to display file tree with token count summaries. Can be boolean or number (minimum token count threshold) | `false` |
  1042. | `output.tokenBudget` | Fail with a non-zero exit code when the packed output exceeds this many tokens. Acts as a guard for CI/agent context limits; the output is still generated | Not set |
  1043. | `output.includeEmptyDirectories` | Whether to include empty directories in the repository structure | `false` |
  1044. | `output.includeFullDirectoryStructure` | When using `include` patterns, whether to display the complete directory tree (respecting ignore patterns) while still processing only the included files. Provides full repository context for AI analysis | `false` |
  1045. | `output.git.sortByChanges` | Whether to sort files by git change count (files with more changes appear at the bottom) | `true` |
  1046. | `output.git.sortByChangesMaxCommits` | Maximum number of commits to analyze for git changes | `100` |
  1047. | `output.git.includeDiffs` | Whether to include git diffs in the output (includes both work tree and staged changes separately) | `false` |
  1048. | `output.git.includeLogs` | Whether to include git logs in the output (includes commit history with dates, messages, and file paths) | `false` |
  1049. | `output.git.includeLogsCount` | Number of git log commits to include | `50` |
  1050. | `include` | Patterns of files to include (using [glob patterns](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax)) | `[]` |
  1051. | `ignore.useGitignore` | Whether to use patterns from the project's `.gitignore` file | `true` |
  1052. | `ignore.useDotIgnore` | Whether to use patterns from the project's `.ignore` file | `true` |
  1053. | `ignore.useDefaultPatterns` | Whether to use default ignore patterns | `true` |
  1054. | `ignore.customPatterns` | Additional patterns to ignore (using [glob patterns](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax)) | `[]` |
  1055. | `security.enableSecurityCheck` | Whether to perform security checks on files | `true` |
  1056. | `tokenCount.encoding` | Token count encoding for OpenAI-compatible tokenization (e.g., `o200k_base` for GPT-4o, `cl100k_base` for GPT-4/3.5). Powered by [gpt-tokenizer](https://github.com/nicolo-ribaudo/gpt-tokenizer). | `"o200k_base"` |
  1057. The configuration file supports [JSON5](https://json5.org/) syntax, which allows:
  1058. - Comments (both single-line and multi-line)
  1059. - Trailing commas in objects and arrays
  1060. - Unquoted property names
  1061. - More relaxed string syntax
  1062. ### Schema Validation
  1063. You can enable schema validation for your configuration file by adding the `$schema` property:
  1064. ```json
  1065. {
  1066. "$schema": "https://repomix.com/schemas/latest/schema.json",
  1067. "output": {
  1068. "filePath": "repomix-output.xml",
  1069. "style": "xml"
  1070. }
  1071. }
  1072. ```
  1073. This provides auto-completion and validation in editors that support JSON schema.
  1074. ### Example Configuration
  1075. Example configuration:
  1076. ```json5
  1077. {
  1078. "$schema": "https://repomix.com/schemas/latest/schema.json",
  1079. "input": {
  1080. "maxFileSize": 50000000,
  1081. // Optional: transform matching files with an external command before packing (local CLI only)
  1082. // "processors": [
  1083. // { "pattern": "**/*.json", "command": "npx @toon-format/cli {file}" }
  1084. // ]
  1085. },
  1086. "output": {
  1087. "filePath": "repomix-output.xml",
  1088. "style": "xml",
  1089. "filePathStyle": "target-relative",
  1090. "parsableStyle": false,
  1091. "compress": false,
  1092. // Optional: override the inclusion level per glob (first match wins)
  1093. // "patterns": [
  1094. // { "pattern": "docs/**/*", "compress": true },
  1095. // { "pattern": "website/**/*", "directoryStructureOnly": true }
  1096. // ],
  1097. "headerText": "Custom header information for the packed file.",
  1098. "fileSummary": true,
  1099. "directoryStructure": true,
  1100. "files": true,
  1101. "removeComments": false,
  1102. "removeEmptyLines": false,
  1103. "topFilesLength": 5,
  1104. "tokenCountTree": false, // or true, or a number like 10 for minimum token threshold
  1105. // "tokenBudget": 180000, // optional: fail when the packed output exceeds this many tokens
  1106. "showLineNumbers": false,
  1107. "truncateBase64": false,
  1108. "copyToClipboard": false,
  1109. // "splitOutput": 1000000, // optional: split output into multiple ~1MB files
  1110. "includeEmptyDirectories": false,
  1111. "git": {
  1112. "sortByChanges": true,
  1113. "sortByChangesMaxCommits": 100,
  1114. "includeDiffs": false,
  1115. "includeLogs": false,
  1116. "includeLogsCount": 50
  1117. }
  1118. },
  1119. "include": ["**/*"],
  1120. "ignore": {
  1121. "useGitignore": true,
  1122. "useDefaultPatterns": true,
  1123. // Patterns can also be specified in .repomixignore
  1124. "customPatterns": [
  1125. "additional-folder",
  1126. "**/*.log"
  1127. ],
  1128. },
  1129. "security": {
  1130. "enableSecurityCheck": true
  1131. },
  1132. "tokenCount": {
  1133. "encoding": "o200k_base"
  1134. }
  1135. }
  1136. ```
  1137. ### Global Configuration
  1138. To create a global configuration file:
  1139. ```bash
  1140. repomix --init --global
  1141. ```
  1142. The global configuration file will be created in:
  1143. - Windows: `%LOCALAPPDATA%\Repomix\repomix.config.json`
  1144. - macOS/Linux: `$XDG_CONFIG_HOME/repomix/repomix.config.json` or `~/.config/repomix/repomix.config.json`
  1145. Note: Local configuration (if present) takes precedence over global configuration.
  1146. ### Include and Ignore
  1147. #### Include Patterns
  1148. Repomix now supports specifying files to include
  1149. using [glob patterns](https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax). This allows for more
  1150. flexible and powerful file selection:
  1151. - Use `**/*.js` to include all JavaScript files in any directory
  1152. - Use `src/**/*` to include all files within the `src` directory and its subdirectories
  1153. - Combine multiple patterns like `["src/**/*.js", "**/*.md"]` to include JavaScript files in `src` and all Markdown
  1154. files
  1155. #### Ignore Patterns
  1156. Repomix offers multiple methods to set ignore patterns for excluding specific files or directories during the packing
  1157. process:
  1158. - **.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.
  1159. - **.ignore**: You can use a `.ignore` file in your project root, following the same format as `.gitignore`. This file is respected by tools like ripgrep and the silver searcher, reducing the need to maintain multiple ignore files. This behavior can be controlled with the `ignore.useDotIgnore` setting or the `--no-dot-ignore` cli option.
  1160. - **Default patterns**: Repomix includes a default list of commonly excluded files and directories (e.g., node_modules,
  1161. .git, binary files). This feature can be controlled with the `ignore.useDefaultPatterns` setting or the `--no-default-patterns` cli option. Please
  1162. see [defaultIgnore.ts](src/config/defaultIgnore.ts) for more details.
  1163. - **.repomixignore**: You can create a `.repomixignore` file in your project root to define Repomix-specific ignore
  1164. patterns. This file follows the same format as `.gitignore`.
  1165. - **Custom patterns**: Additional ignore patterns can be specified using the `ignore.customPatterns` option in the
  1166. configuration file. You can overwrite this setting with the `-i, --ignore` command line option.
  1167. Priority Order (from highest to lowest):
  1168. 1. Custom patterns (`ignore.customPatterns`)
  1169. 2. Ignore files (`.repomixignore`, `.ignore`, `.gitignore`, and `.git/info/exclude`):
  1170. - When in nested directories, files in deeper directories have higher priority
  1171. - When in the same directory, these files are merged in no particular order
  1172. 3. Default patterns (if `ignore.useDefaultPatterns` is true and `--no-default-patterns` is not used)
  1173. This approach allows for flexible file exclusion configuration based on your project's needs. It helps optimize the size
  1174. of the generated pack file by ensuring the exclusion of security-sensitive files and large binary files, while
  1175. preventing the leakage of confidential information.
  1176. Note: Binary files are not included in the packed output by default, but their paths are listed in the "Repository
  1177. Structure" section of the output file. This provides a complete overview of the repository structure while keeping the
  1178. packed file efficient and text-based.
  1179. ### Custom Instruction
  1180. The `output.instructionFilePath` option allows you to specify a separate file containing detailed instructions or
  1181. context about your project. This allows AI systems to understand the specific context and requirements of your project,
  1182. potentially leading to more relevant and tailored analysis or suggestions.
  1183. Here's an example of how you might use this feature:
  1184. 1. Create a file named `repomix-instruction.md` in your project root:
  1185. ```markdown
  1186. # Coding Guidelines
  1187. - Follow the Airbnb JavaScript Style Guide
  1188. - Suggest splitting files into smaller, focused units when appropriate
  1189. - Add comments for non-obvious logic. Keep all text in English
  1190. - All new features should have corresponding unit tests
  1191. # Generate Comprehensive Output
  1192. - Include all content without abbreviation, unless specified otherwise
  1193. - Optimize for handling large codebases while maintaining output quality
  1194. ```
  1195. 2. In your `repomix.config.json`, add the `instructionFilePath` option:
  1196. ```json5
  1197. {
  1198. "output": {
  1199. "instructionFilePath": "repomix-instruction.md",
  1200. // other options...
  1201. }
  1202. }
  1203. ```
  1204. When Repomix generates the output, it will include the contents of `repomix-instruction.md` in a dedicated section.
  1205. Note: The instruction content is appended at the end of the output file. This placement can be particularly effective
  1206. for AI systems. For those interested in understanding why this might be beneficial, Anthropic provides some insights in
  1207. their documentation:
  1208. https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips
  1209. > Put long-form data at the top: Place your long documents and inputs (~20K+ tokens) near the top of your prompt, above
  1210. > your query, instructions, and examples. This can significantly improve Claude's performance across all models.
  1211. > Queries at the end can improve response quality by up to 30% in tests, especially with complex, multi-document inputs.
  1212. ### Comment Removal
  1213. When `output.removeComments` is set to `true`, Repomix will attempt to remove comments from supported file types. This
  1214. feature can help reduce the size of the output file and focus on the essential code content.
  1215. Supported languages include:
  1216. HTML, CSS, JavaScript, TypeScript, Vue, Svelte, Python, PHP, Ruby, C, C#, Java, Go, Rust, Swift, Kotlin, Dart, Shell,
  1217. and YAML.
  1218. Note: The comment removal process is conservative to avoid accidentally removing code. In complex cases, some comments
  1219. might be retained.
  1220. ### File Processors
  1221. `input.processors` runs an external command to transform a file's content **before** it is packed. Each entry targets files by glob (matched like `include`/`ignore`) and replaces the matching files' content with the command's standard output โ€” useful for token-reducing or format-converting transforms such as JSONโ†’[TOON](https://github.com/toon-format/toon), SVG minification, or notebookโ†’script conversion.
  1222. ```json5
  1223. {
  1224. "input": {
  1225. "processors": [
  1226. { "pattern": "**/*.json", "command": "npx @toon-format/cli {file}" }
  1227. ]
  1228. }
  1229. }
  1230. ```
  1231. The `{file}` placeholder (required) is replaced with a temp file holding the file's content, and the command's stdout becomes the new content. Patterns are evaluated in order and the **first match wins** (one processor per file). Each entry also accepts `timeout` (ms, default `60000`) and `onError` (`"fail"` to abort the pack, default; `"skip"` to warn and keep the original content).
  1232. Example commands (each is a `command` value paired with a suitable `pattern`):
  1233. | Pattern | `command` | What it does |
  1234. | --- | --- | --- |
  1235. | `**/*.json` | `jq -c . {file}` | Compact JSON by stripping whitespace |
  1236. | `**/*.json` | `npx @toon-format/cli {file}` | Convert JSON to [TOON](https://github.com/toon-format/toon), a compact token-efficient format |
  1237. | `**/*.svg` | `npx svgo -i {file} -o -` | Minify SVG |
  1238. | `**/*.ipynb` | `jupyter nbconvert --to script --stdout {file}` | Convert a Jupyter notebook to a plain Python script |
  1239. Apply only one processor per file (first match wins), and make sure the tool it invokes is on your `PATH` (`npx`-based commands download it on first use).
  1240. > [!WARNING]
  1241. > File processors run **arbitrary commands** from your config file, so execution is default-deny:
  1242. >
  1243. > - Enabled **only for local CLI runs**, where Repomix assumes the config in your working directory is your own โ€” the same trust boundary as an npm script or a Makefile. As with those, if you run `repomix` inside a repository you obtained from someone else **without reviewing its `repomix.config.json` first**, its processor commands will execute on your machine. Review the config of untrusted repositories before packing them.
  1244. > - **Disabled** for the library API (`pack()` / `runCli()`), the MCP server, and the hosted [repomix.com](https://repomix.com).
  1245. > - For remote repositories (`--remote`), the cloned config โ€” and its processors โ€” is trusted only when you explicitly pass `--remote-trust-config`; without it the remote config is not even loaded.
  1246. >
  1247. > Active processors are printed at startup and in error messages, so reference credentials via environment variables (e.g. `$TOKEN`), which are logged unexpanded, rather than inlining them. On timeout Repomix kills the command's shell, but a command that spawns its own long-lived background processes may leave them running. See the [configuration guide](https://repomix.com/guide/configuration#file-processors) for details.
  1248. ## ๐Ÿ” Security Check
  1249. Repomix includes a security check feature that uses [Secretlint](https://github.com/secretlint/secretlint) to detect
  1250. potentially sensitive information in your files. This feature helps you identify possible security risks before sharing
  1251. your packed repository.
  1252. The security check results will be displayed in the CLI output after the packing process is complete. If any suspicious
  1253. files are detected, you'll see a list of these files along with a warning message.
  1254. Example output:
  1255. ```
  1256. ๐Ÿ” Security Check:
  1257. โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
  1258. 2 suspicious file(s) detected:
  1259. 1. src/utils/test.txt
  1260. 2. tests/utils/secretLintUtils.test.ts
  1261. Please review these files for potentially sensitive information.
  1262. ```
  1263. By default, Repomix's security check feature is enabled. You can disable it by setting `security.enableSecurityCheck` to
  1264. `false` in your configuration file:
  1265. ```json
  1266. {
  1267. "security": {
  1268. "enableSecurityCheck": false
  1269. }
  1270. }
  1271. ```
  1272. Or using the `--no-security-check` command line option:
  1273. ```bash
  1274. repomix --no-security-check
  1275. ```
  1276. > [!NOTE]
  1277. > Disabling security checks may expose sensitive information. Use this option with caution and only when necessary, such
  1278. > as when working with test files or documentation that contains example credentials.
  1279. ### Remote Repository Config Trust
  1280. A `repomix.config.*` is code, not just data: a `.ts` / `.js` config is executed when loaded, `input.processors` runs
  1281. external commands, and path options can read files outside the repository. Loading one from an unfamiliar repository is
  1282. comparable to running its `Makefile`.
  1283. For that reason, **a cloned repository's config is never loaded by default**. Your global config and CLI options still
  1284. apply.
  1285. When you opt in with `--remote-trust-config` (or `REPOMIX_REMOTE_TRUST_CONFIG=true`) on an interactive terminal, Repomix
  1286. shows the config that is about to run and asks before loading it:
  1287. - **Yes, once** โ€” trust this run only.
  1288. - **Yes, and don't ask again for this repository** โ€” the decision is *content-pinned*: it records a hash of the config
  1289. you approved, so you are asked again if that repository later ships a different one (the `direnv allow` model).
  1290. - **No** (the default selection) โ€” abort without loading the config.
  1291. The displayed config is written by the repository's author, so control, ANSI, and bidirectional characters are escaped,
  1292. the output is capped, every config line is prefixed, and symlinked configs pointing outside the clone are refused โ€” what
  1293. you review is what runs.
  1294. The prompt is skipped with `--force`, in non-interactive shells such as CI (existing automation keeps working), and once
  1295. you have chosen to always trust that repository.
  1296. > [!IMPORTANT]
  1297. > The content pin covers the entry config file only. A `.ts` / `.js` config can `import` other files and
  1298. > `input.processors` can invoke external scripts; neither is hashed. Treat "don't ask again" as trust in the repository,
  1299. > not only in the file you read.
  1300. See the [security guide](https://repomix.com/guide/security#remote-repository-config-trust) for the full trust model.
  1301. ## ๐Ÿค– Using Repomix with GitHub Actions
  1302. You can also use Repomix in your GitHub Actions workflows. This is useful for automating the process of packing your codebase for AI analysis.
  1303. Basic usage:
  1304. ```yaml
  1305. - name: Pack repository with Repomix
  1306. uses: yamadashy/repomix/.github/actions/repomix@main
  1307. with:
  1308. output: repomix-output.xml
  1309. style: xml
  1310. ```
  1311. Use `--style` to generate output in different formats:
  1312. ```yaml
  1313. - name: Pack repository with Repomix
  1314. uses: yamadashy/repomix/.github/actions/repomix@main
  1315. with:
  1316. output: repomix-output.md
  1317. style: markdown
  1318. ```
  1319. ```yaml
  1320. - name: Pack repository with Repomix (JSON format)
  1321. uses: yamadashy/repomix/.github/actions/repomix@main
  1322. with:
  1323. output: repomix-output.json
  1324. style: json
  1325. ```
  1326. Pack specific directories with compression:
  1327. ```yaml
  1328. - name: Pack repository with Repomix
  1329. uses: yamadashy/repomix/.github/actions/repomix@main
  1330. with:
  1331. directories: src tests
  1332. include: "**/*.ts,**/*.md"
  1333. ignore: "**/*.test.ts"
  1334. output: repomix-output.txt
  1335. compress: true
  1336. ```
  1337. Upload the output file as an artifact:
  1338. ```yaml
  1339. - name: Pack repository with Repomix
  1340. uses: yamadashy/repomix/.github/actions/repomix@main
  1341. with:
  1342. directories: src
  1343. output: repomix-output.txt
  1344. compress: true
  1345. - name: Upload Repomix output
  1346. uses: actions/upload-artifact@v7
  1347. with:
  1348. name: repomix-output
  1349. path: repomix-output.txt
  1350. ```
  1351. Complete workflow example:
  1352. ```yaml
  1353. name: Pack repository with Repomix
  1354. on:
  1355. workflow_dispatch:
  1356. push:
  1357. branches: [ main ]
  1358. pull_request:
  1359. branches: [ main ]
  1360. jobs:
  1361. pack-repo:
  1362. runs-on: ubuntu-latest
  1363. steps:
  1364. - name: Checkout code
  1365. uses: actions/checkout@v7
  1366. - name: Pack repository with Repomix
  1367. uses: yamadashy/repomix/.github/actions/repomix@main
  1368. with:
  1369. output: repomix-output.xml
  1370. - name: Upload Repomix output
  1371. uses: actions/upload-artifact@v7
  1372. with:
  1373. name: repomix-output.xml
  1374. path: repomix-output.xml
  1375. retention-days: 30
  1376. ```
  1377. See the complete workflow example [here](https://github.com/yamadashy/repomix/blob/main/.github/workflows/pack-repository.yml).
  1378. ### Action Inputs
  1379. | Name | Description | Default |
  1380. |------|-------------|---------|
  1381. | `directories` | Space-separated list of directories to process (e.g., `src tests docs`) | `.` |
  1382. | `include` | Comma-separated glob patterns to include files (e.g., `**/*.ts,**/*.md`) | `""` |
  1383. | `ignore` | Comma-separated glob patterns to ignore files (e.g., `**/*.test.ts,**/node_modules/**`) | `""` |
  1384. | `output` | Relative path for the packed file (extension determines format: `.txt`, `.md`, `.xml`) | `repomix-output.xml` |
  1385. | `compress` | Enable smart compression to reduce output size by pruning implementation details | `true` |
  1386. | `style` | Output style (`xml`, `markdown`, `json`, `plain`) | `xml` |
  1387. | `additional-args` | Extra raw arguments for the repomix CLI (e.g., `--no-file-summary --no-security-check`) | `""` |
  1388. | `repomix-version` | Version of the npm package to install (supports semver ranges, tags, or specific versions like `0.2.25`) | `latest` |
  1389. ### Action Outputs
  1390. | Name | Description |
  1391. |------|-------------|
  1392. | `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. |
  1393. ## ๐Ÿ“š Using Repomix as a Library
  1394. In addition to using Repomix as a CLI tool, you can also use it as a library in your Node.js applications.
  1395. ### Installation
  1396. ```bash
  1397. npm install repomix
  1398. ```
  1399. ### Basic Usage
  1400. ```javascript
  1401. import { runCli, type CliOptions } from 'repomix';
  1402. // Process current directory with custom options
  1403. async function packProject() {
  1404. const options = {
  1405. output: 'output.xml',
  1406. style: 'xml',
  1407. compress: true,
  1408. quiet: true
  1409. } as CliOptions;
  1410. const result = await runCli(['.'], process.cwd(), options);
  1411. return result.packResult;
  1412. }
  1413. ```
  1414. ### Process Remote Repository
  1415. ```javascript
  1416. import { runCli, type CliOptions } from 'repomix';
  1417. // Clone and process a GitHub repo
  1418. async function processRemoteRepo(repoUrl) {
  1419. const options = {
  1420. remote: repoUrl,
  1421. output: 'output.xml',
  1422. compress: true
  1423. } as CliOptions;
  1424. return await runCli(['.'], process.cwd(), options);
  1425. }
  1426. ```
  1427. ### Using Core Components
  1428. If you need more control, you can use the low-level APIs:
  1429. ```javascript
  1430. import { searchFiles, collectFiles, processFiles, TokenCounter } from 'repomix';
  1431. async function analyzeFiles(directory) {
  1432. // Find and collect files
  1433. const { filePaths } = await searchFiles(directory, { /* config */ });
  1434. const rawFiles = await collectFiles(filePaths, directory);
  1435. const processedFiles = await processFiles(rawFiles, { /* config */ });
  1436. // Count tokens
  1437. const tokenCounter = new TokenCounter('o200k_base');
  1438. // Return analysis results
  1439. return processedFiles.map(file => ({
  1440. path: file.path,
  1441. tokens: tokenCounter.countTokens(file.content)
  1442. }));
  1443. }
  1444. ```
  1445. 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.
  1446. ### Bundling
  1447. When bundling repomix with tools like Rolldown or esbuild, some dependencies must remain external and WASM files need to be copied:
  1448. **External dependencies (cannot be bundled):**
  1449. - `tinypool` - Spawns worker threads using file paths
  1450. **WASM files to copy:**
  1451. - `web-tree-sitter.wasm` โ†’ Same directory as bundled JS (required for code compression feature)
  1452. - Tree-sitter language files โ†’ Directory specified by `REPOMIX_WASM_DIR` environment variable
  1453. For a working example, see [website/server/scripts/bundle.mjs](https://github.com/yamadashy/repomix/blob/main/website/server/scripts/bundle.mjs).
  1454. ## ๐ŸŒ Community Projects
  1455. Discover amazing projects built by the Repomix community!
  1456. - [Repomix Runner](https://github.com/massdo/repomix-runner) - VSCode extension for bundling files into a single output for AI processing
  1457. - [Repomix Desktop](https://github.com/KevanMacGee/Repomix-Desktop) - GUI desktop application for Repomix built with Python and CustomTkinter
  1458. - [Python Repomix](https://github.com/AndersonBY/python-repomix) - Python implementation with AST-based compression
  1459. - [Rulefy](https://github.com/niklub/rulefy) - Transform GitHub repos into custom Cursor AI rules using Claude AI
  1460. - [Codebase MCP](https://github.com/DeDeveloper23/codebase-mcp) - MCP server that uses Repomix for AI-powered codebase analysis
  1461. - [vibe-tools](https://github.com/eastlondoner/vibe-tools) - CLI toolset for AI agents with web search, repo analysis, and browser automation

Lines 2,001โ€“2,026 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.