Repomix: Pack a Repo for AI, Plus Its MCP Server

Repomix packs your whole repository into one AI-friendly file, with a directory tree, every file's contents and token counts. Run npx repomix@latest in a project and it writes repomix-output.xml. It is MIT licensed and also runs as an MCP server (repomix --mcp) and as a Claude Code plugin. We checked the README and package file on 31 October 2026.

Quick facts

What problem it solves

You want to ask an AI a question that needs the whole codebase: "where does auth happen", "refactor this module", "write docs for this library". Chat tools do not read your folder, and copying twenty files by hand is slow and error-prone.

Repomix does the copying. It walks the repo, applies your ignore rules, and writes a single file that contains a summary, the directory structure and each file's content. You give that file to an assistant, or let an assistant call Repomix itself.

For a coding agent that already has file tools, the case is different. Claude Code and Codex can read the repo directly. Repomix still helps when you want:

• a token count before you paste anything into a model with a context limit;
• one snapshot of an open source repo you do not want to clone;
• a compressed overview of a very large codebase;
• a file to send to a chat product that cannot read your disk;
• a way to turn a repo into a skill for a coding agent.

Quick start

npx repomix@latest

That is the whole install. Repomix writes repomix-output.xml. The README suggests attaching it to an assistant with a prompt such as:

This file contains all the files in the repository combined into one.
I want to refactor the code, so please review it first.

Install it globally for repeated use:

npm install -g repomix
repomix

Update with the same package manager you used to install.

The options you will use

Examples from the README:

repomix --include "src/**/*.ts" --compress -o review.xml
repomix --remote yamadashy/repomix
repomix --remote https://github.com/user/repo/tree/main
repomix --stdout | llm "Explain this codebase"

Token awareness

Repomix counts tokens per file and for the whole repo. Use --token-count-tree to see which folders are heavy, then ignore or compress them. The count uses the o200k_base encoding by default, and --token-count-encoding changes it. A count is an estimate for the tokenizer you chose, not for every model.

Compression

--compress runs Tree-sitter over supported languages and keeps the structure: signatures, classes, interfaces. The README says it reduces token count while preserving structure, and the MCP tool docs say compression reduces token usage by about 70%. That figure is the project's own claim, and it will vary by codebase. Try it on your repo and look at the count rather than assuming.

There is also a per-file option, output.patterns, which lets you keep important files in full and compress or list-only the rest.

Output formats

The file has a summary of what it is, the directory structure, the file contents and, if you add them, instructions at the end. Files are sorted by git change frequency by default, with the most changed files first.

Use it as an MCP server

repomix --mcp

This lets an assistant call Repomix itself. The README lists four tools:

Install in each agent

Claude Code, from the README:

claude mcp add repomix -- npx -y repomix --mcp

Or use the official plugins:

/plugin marketplace add yamadashy/repomix
/plugin install repomix-mcp@repomix
/plugin install repomix-commands@repomix
/plugin install repomix-explorer@repomix

VS Code, from the README:

code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}'

Cursor, Cline and Claude Desktop use the standard block:

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

Codex and Gemini CLI are not covered in the README's MCP section. The same command and args work in their formats:

[mcp_servers.repomix]
command = "npx"
args = ["-y", "repomix", "--mcp"]

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

The Codex block goes in ~/.codex/config.toml and the JSON in Gemini CLI's settings.json. They are our adaptation of the standard form.

A Docker form exists too, with the image ghcr.io/yamadashy/repomix and the --mcp argument.

Compatibility at a glance

Skills: Repomix Explorer and skill generation

Two features connect Repomix to agent skills.

• Repomix Explorer is a ready-made skill that lets an assistant analyse a codebase using the Repomix CLI. For Claude Code: /plugin install repomix-explorer@repomix. For Codex, Cursor and others that follow the Agent Skills format: npx skills add yamadashy/repomix --skill repomix-explorer, optionally with --agent codex. See our skills guide.
• Skill generation with repomix --skill-generate [name] writes a Claude Agent Skills structure into .claude/skills/<name>/ from a local directory or a remote repo. It is a quick way to turn a library's source into a reference skill for an agent.

The npx skills installer is a third-party tool; read what it does before you run it.

Real tasks with copy-ready prompts

Onboard to a repo

repomix --compress --style markdown -o overview.md

Read overview.md. Explain the architecture in ten bullet points, then
list the five files I should read first and why.

Prepare a focused review

repomix --include "src/auth/**" --include-diffs -o auth-review.xml

Review auth-review.xml for security problems. Quote the line for each
finding.

Read an open source library without cloning

repomix --remote user/repo --compress --token-count-tree 2000

Guard context in CI

repomix --compress --token-budget 150000

Write documentation

Using the packed repository, write a README with install steps,
a usage example and a list of public functions.

Security and privacy

Repomix puts your code in one file, so treat the output as sensitive.

• Secret scanning. It uses Secretlint to detect and leave out files that match known credential formats. The README calls this security-focused, not a guarantee. Do not rely on it to catch everything, and keep .env files in your ignore rules.
• Ignore files. It respects .gitignore, .ignore and .repomixignore, plus built-in patterns for node_modules, .git and build folders.
• A config file is code. The README warns that a repomix.config.* file can run when loaded. By default it does not trust config files from remote repositories (--remote-trust-config turns that on, with a confirmation on an interactive terminal). Without --sandbox, the MCP pack_codebase tool loads and trusts the config in the directory it packs, the same as running repomix there.
• MCP sandbox mode. repomix --mcp --sandbox [dir] confines the MCP server's file tools to a workspace directory. Paths must be relative to the root, and absolute, ~, .. and Windows drive paths are refused, as are paths that escape through symlinks. By default the MCP server can read any path your user can, so use --sandbox when the client is an agent you do not fully trust.
• Where the file goes. Once you attach the output to a chat product, it goes to that provider. Check your company's rules first.
• The hosted website and browser extension process repos through Repomix's own services. Read their privacy terms before you use them on private code.

Will it fit? A token budget worked through

The first question about any packed repository is whether the output fits in the model's context with room left for the conversation. You can estimate it before you pack. As a rough rule, source code runs at about 3 to 4 characters per token, which makes a 1 MB codebase roughly 250,000 to 330,000 tokens. That is a rule of thumb. Repomix's own count, shown by --token-count-tree, is the number to trust.

The sizes are examples, and the windows differ by model. The pattern is the useful part. If a repository is over the window, the answer is rarely a bigger window. It is a smaller selection. Compression helps because it keeps signatures and structure and drops bodies, which suits questions about architecture and interfaces. It suits poorly a question about what a specific function does, where you need the body. In that case include that file in full.

A pass that works for most mid-size projects:

repomix --token-count-tree 1000      # see which folders are heavy
repomix --include "src/api/**" --compress -o api-overview.xml
repomix --include "src/api/billing.ts" -o billing-full.xml

Attach the overview first for orientation, then the one file in full for detail. Two small packs with a clear purpose beat one big pack that the model skims.

Using the token budget in CI

The --token-budget option exits with an error when the output passes a limit. That is a cheap guard for a pipeline that feeds a packed repository to a model, since it turns a surprise bill into a failed job. Set the number a little under the model's window, and treat a failure as a prompt to tighten the include patterns, not to raise the limit. A pipeline that packs weekly can also watch the trend: if the token count grows 20 percent a month, a generated folder or vendored library has probably slipped past your ignore rules.

What to leave out

The best pack is the smallest one that answers the question. Common exclusions:

Put the permanent ones in .repomixignore, which works like .gitignore, and use -i for one-off exclusions. When you add a pattern, run --token-count-tree again to confirm the number dropped.

Pack, or let the agent search?

Coding agents can already search a repository on their own, so packing is not always the right move. The choice depends on the task.

In short, packing is for tools that cannot browse, and for questions about the whole. Agents that can read files usually do better by choosing what to open. If you find yourself packing a repository to give it to Claude Code or Codex, ask whether a good CLAUDE.md or AGENTS.md and a pointer to the right folder would do the same job for less money.

Limits and known issues

• Node 22 or newer is required by the package file, newer than many machines have.
• Size. A big repo makes a big file. Use --compress, --include and --split-output or you will blow through a model's context.
• Token counts are estimates for one tokenizer.
• Packing is a snapshot. The output goes stale as soon as you edit. Watch mode (repomix --watch) re-packs on change, but only for local directories.
• Not a search tool. For finding a symbol in a large repo, a language server tool such as Serena MCP gives the agent targeted answers without a huge file.
• Open issues. The repo had 153 open issues and pull requests when we looked. Check the tracker for your platform.
• Sponsor placements. The README opens with sponsor banners. They do not change the tool, but you should know they are there.

Alternatives

Our take

We read the README and package file; we did not benchmark Repomix on any repo.

The tool does one thing, and does it with unusual care. The token tree, the compress option, the secret scan and the sandbox flag are all things you would otherwise discover the hard way. For a chat product with no file access, it is the best way we know to hand over a repo.

For a coding agent with file tools, we would not run it by default. Reading the files directly keeps results fresh and uses fewer tokens than a full snapshot. The cases that make sense are the ones above: a size check, a remote repo, a compressed map, or a generated skill.

If you do use it, set a token budget and check the tree before you attach anything. The README's own advice is to understand your token distribution.

Frequently asked questions

What does Repomix do? It packs a repo into one AI-friendly file with a tree, contents and token counts.

How do I run it? npx repomix@latest in your project.

Does it have an MCP server? Yes, repomix --mcp.

How does it keep secrets out? Ignore files plus a Secretlint scan.

What does --compress do? It keeps structure with Tree-sitter and drops implementation detail.

*Product names are used descriptively. We are not affiliated with the Repomix project.*