FAQ and Troubleshooting

Use this page when you need a quick answer about choosing the right Repomix workflow, reducing output size, or preparing codebase context for AI assistants.

General Questions

What is Repomix used for?

Repomix packs a repository into a single AI-friendly file so you can give an AI assistant broad codebase context without manually copying files. It is useful for code review, bug investigation, refactoring plans, onboarding, documentation, security analysis, and architecture reviews.

Does Repomix work with C#, Python, Java, Go, Rust, or other languages?

Yes. Repomix can pack repositories written in any programming language because it reads files from your project and formats them for AI tools. Repomix itself runs on Node.js, so you need Node.js 20 or later when using the CLI. Some advanced features, such as Tree-sitter code compression, depend on language parser support and may vary by language.

See Installation for runtime requirements.

When should I use Repomix instead of an IDE extension or MCP server?

Use the CLI when you want a portable file that works with any AI tool, including ChatGPT, Claude, Gemini, Grok, DeepSeek, Perplexity, or local LLM workflows. Use the MCP server or Claude Code plugins when you want an assistant to request repository context directly from your local environment during an interactive coding session.

Can I use Repomix with Hermes Agent, OpenClaw, or other MCP-compatible agents?

Yes. Repomix can run as an MCP server, so MCP-compatible agents can request packed codebase context directly:

npx -y repomix --mcp

For Hermes Agent, add Repomix as a stdio MCP server in ~/.hermes/config.yaml:

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

For OpenClaw or other MCP-compatible agents, use the same command and arguments wherever the agent lets you configure an external stdio MCP server. Check the agent's current MCP documentation for the exact config format.

If your assistant supports the Agent Skills format, you can also install the Repomix Explorer skill instead of configuring MCP:

npx skills add yamadashy/repomix --skill repomix-explorer

For Claude Code, use the dedicated Repomix Explorer plugin instead:

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

Use the MCP server when you want the agent to call Repomix tools during a session. Use Repomix Explorer Skill when you want a reusable natural-language workflow for exploring local or remote codebases; that guide also includes the Hermes Agent hermes skills install command. Use the Claude Code plugin when you want namespaced slash commands such as /repomix-explorer:explore-local.

Does Repomix work with private repositories?

Yes. For private repositories, run Repomix locally in a checkout that your machine can already access:

repomix

Repomix uses your local filesystem and git configuration. Review the generated output before sharing it with any external AI service.

Can Repomix process a public GitHub repository without cloning it?

Yes. Use the --remote option with a full URL or owner/repo shorthand:

npx repomix --remote yamadashy/repomix
npx repomix --remote https://github.com/yamadashy/repomix

You can also target a branch, tag, commit, or subdirectory from a supported GitHub URL.

How do I use Repomix to help an AI assistant understand a new library or framework?

Pack the library repository or its documentation, then ask the AI assistant to use the output as reference material:

npx repomix --remote owner/repo
npx repomix --remote owner/repo --include "docs/**,src/**"

For repeated use with Claude, generate a reusable Agent Skills directory:

npx repomix --remote owner/repo --skill-generate library-reference

See Agent Skills Generation for reusable library reference workflows.

Output Formats

Which output format should I choose?

Start with the default XML output if you are unsure:

repomix

Use XML when you want strong structure for Claude or other models that parse tagged context well. Use Markdown when humans will read or edit the packed file. Use JSON when another program will consume the output. Use plain text when you need the simplest possible format.

How do I change the output format?

Use the --style option:

repomix --style markdown
repomix --style json
repomix --style plain

See Output Formats for a detailed comparison.

Can I add custom instructions for the AI assistant?

Yes. Use output.instructionFilePath in repomix.config.json or provide header text so the generated output includes project-specific guidance. This is useful for coding standards, architecture notes, review goals, and response requirements.

See Custom Instructions for examples.

Reducing Token Usage

The generated file is too large. What should I do?

Narrow the packed context before sending it to an AI assistant:

repomix --include "src/**/*.ts,docs/**/*.md"
repomix --ignore "**/*.test.ts,dist/**"
repomix --compress
repomix --remove-comments

For large repositories, combine include and ignore patterns with code compression. You can also split the output or focus on the subsystem related to your question.

How do I exclude CSS, tests, build output, or other noisy files?

Use --ignore for one-off commands:

repomix --ignore "**/*.css,**/*.test.ts,dist/**,coverage/**"

Use --include when you want to keep only specific source or documentation paths:

repomix --include "src/**/*.ts,docs/**/*.md"

For team workflows, store these patterns in repomix.config.json so everyone generates the same output.

Is there a repository size limit?

The CLI does not have a fixed repository size limit, but very large repositories can be constrained by memory, file size, or the AI tool's upload and context limits. For large projects, start with targeted include patterns, inspect token-heavy files, and split the output when needed:

repomix --token-count-tree 1000
repomix --split-output 1mb

The hosted website is better for quick public repository checks or small uploads. For large repositories, private repositories, or repeatable team workflows, use the local CLI.

What does --compress do?

--compress uses Tree-sitter-based code compression to keep important structure such as imports, exports, classes, functions, interfaces, and method signatures while removing implementation detail. It is useful when the model needs an architectural overview more than exact line-by-line code.

See Code Compression for details.

Should I remove comments?

Use --remove-comments when comments are noisy or consume too many tokens. Keep comments when they contain domain knowledge, API contracts, warnings, or important implementation rationale.

See Comment Removal for the supported behavior.

Security and Privacy

Does Repomix upload my code?

The Repomix CLI runs locally and writes an output file on your machine. The website and browser extension have different workflows, so check Privacy Policy when using hosted or browser-based features.

How does Repomix avoid including secrets?

Repomix includes Secretlint-based safety checks to detect sensitive values before packing. Treat this as a safety net, not a replacement for reviewing the output yourself. Always inspect generated files before sending private code to an AI provider.

See Security for the security model and recommended workflow.

Should I send a full private codebase to an AI assistant?

Only send code that your organization allows you to share with that AI provider. For sensitive projects, prefer a smaller include pattern, remove unnecessary files, and review the generated output. If possible, use enterprise controls or local models approved by your team.

Troubleshooting

Why are files missing from the output?

Repomix respects ignore rules such as .gitignore, default ignore patterns, and custom patterns from your configuration. Check your repomix.config.json, CLI --ignore options, and whether the files are ignored by git.

Why does --include not include files from node_modules, build directories, or ignored paths?

--include narrows the files Repomix tries to pack, but ignore rules still apply. Files can still be excluded by .gitignore, .ignore, .repomixignore, built-in default patterns, or repomix.config.json.

If you intentionally need files from a normally ignored location, review the ignore source first. For advanced cases, options such as --no-gitignore or --no-default-patterns can disable parts of the ignore behavior, but use them carefully because they may include dependencies, build artifacts, or other noisy files.

Why did Repomix include files I did not want?

Add an ignore pattern:

repomix --ignore "dist/**,coverage/**,*.log"

For repeatable behavior, store ignore patterns in repomix.config.json.

How can I make Repomix output repeatable for a team?

Commit a repomix.config.json file with shared output settings, include patterns, ignore patterns, and custom instructions:

repomix --init

Then run repomix from the same project root in local development or CI.

How can I use Repomix in CI?

Use the GitHub Actions integration to generate packed repository output as part of a workflow. This is useful for automated review, artifact creation, or AI analysis in controlled pipelines.

See Using Repomix with GitHub Actions.

Related Resources

• Basic Usage - Common CLI workflows
• Command Line Options - Full CLI option reference
• Prompt Examples - Prompts for code review, security analysis, and documentation
• Use Cases - Practical AI workflows with Repomix