One of the persistent friction points with AI coding assistants is the gap between “here’s my whole codebase” and “here’s the specific context the model needs to help me.” Drag-and-dropping individual files works for simple questions, but the moment you’re dealing with cross-file dependencies, shared types, or unfamiliar code you’re trying to understand, you spend more time curating context than asking questions.

Repomix solves this problem directly. It’s a CLI tool that packages your entire repository — or a specific subset of it — into a single, structured file optimised for LLM consumption. You paste or upload that file, and the model gets your full codebase in one context load.

What Repomix Produces

Run repomix in a repository root and it generates a single output file (default: repomix-output.txt) that contains:

  • A summary of the file structure (as a directory tree)
  • The contents of every included file, with clear file path separators between them
  • Token count statistics so you know whether the output fits in your model’s context window

The output is formatted for readability by LLMs rather than humans. File contents are separated by consistent markers (===== File: path/to/file.ts =====), and the structure encourages models to orient themselves within the codebase before answering.

npx repomix
# or install globally:
npm install -g repomix
repomix

The output file can be uploaded to Claude.ai, GPT-4, Gemini, or any model with file upload. For API use, you read the file content and pass it as a context message.

Controlling What Gets Included

By default, Repomix respects your .gitignore, so node_modules, build outputs, and other excluded directories are automatically omitted. This is one of the most useful defaults — it means the output stays focused on your actual code.

For additional control, create a repomix.config.json file:

{
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml",
    "removeComments": false,
    "removeEmptyLines": false,
    "showLineNumbers": true
  },
  "include": ["src/**", "tests/**", "*.ts"],
  "ignore": {
    "useGitignore": true,
    "customPatterns": ["**/*.test.ts", "**/__mocks__/**"]
  }
}

The include field lets you scope to specific directories or file types — useful when you only want to share your src/ directory and skip configuration files, documentation, or test fixtures. The ignore.customPatterns field extends your gitignore with Repomix-specific exclusions.

Output Formats

Repomix supports three output styles:

Plain text (default): Human-readable, simple file separators. Works well for most chat-based workflows.

XML: Structured output with tags wrapping each file section. Claude handles this particularly well — Anthropic’s models are trained extensively on XML-structured content and tend to parse and reference it more accurately.

Markdown: Code blocks with language tags for each file. Good for markdown-aware interfaces.

For API use with Claude, the XML format is worth trying:

repomix --style xml

The structured output helps the model track which file it’s reading when files span multiple passages in a long context.

Token Count Awareness

One of Repomix’s most practical features is the token count report it prints after generating the output:

📊 Repomix Stats:
  Total Files: 47
  Total Characters: 142,840
  Total Tokens: 38,921 (estimated)

This tells you immediately whether your repo fits in your target model’s context window. A typical mid-size TypeScript project generates 30,000-80,000 tokens. GPT-4o and Claude have 128,000-token and 200,000-token context windows respectively, so most real-world projects fit. Larger monorepos may need scoping with --include to stay under limits.

The token count estimate uses cl100k_base tokenization (OpenAI’s), which is close enough to other models’ tokenizers for planning purposes.

When Repomix Beats Other Approaches

For unfamiliar codebases: When you join a project or inherit code, passing the full repo to an AI and asking “explain the architecture” or “what does this module do and how does it connect to the rest?” gives you a comprehensive answer. Individual file uploads force you to know which files to share before you know the codebase well enough to pick them.

For cross-file refactoring: “Rename this type and update all usages” or “move this function to a shared utility module” requires the model to see all the files that reference the thing being changed. Repomix ensures nothing gets missed.

For code review with full context: Pasting a diff is often insufficient for meaningful review. The reviewer needs to see how the changed code relates to the files it imports and exports. Repomix gives the model that context.

For onboarding documentation: Use Repomix to generate a codebase snapshot, pass it to an LLM with a prompt like “write an architecture overview and module guide for a new developer joining this project,” and get a first draft of documentation that actually reflects the real code.

The --remote Flag for GitHub Repos

Repomix can pack a remote GitHub repository without cloning it locally:

repomix --remote https://github.com/some-org/some-repo

This is useful for examining open-source dependencies, understanding a library’s internals before adding it, or reviewing a colleague’s public repository.

Security Note

Before using Repomix on any repository, be aware that the output will contain everything in the included files — API keys, database URLs, secrets in .env files, and anything else in your code. The .gitignore default helps (since .env is usually gitignored), but check what gets included before pasting the output into any cloud-based AI service. For sensitive codebases, run against a sanitised copy or pipe the output to a local model via Ollama rather than to a cloud API.

Repomix is a small tool, but it eliminates a genuine friction point in AI-assisted development workflows. The result is fewer “the model didn’t have enough context” dead ends and more productive conversations about real problems.