repomix Documentation

File: README.md Copy Chapter

📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file.
It is perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude,
ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.

Please consider sponsoring me.

🏆 Open Source Awards Nomination Copy Chapter

We're honored! Repomix has been nominated for the Powered by AI category at the JSNation Open Source Awards 2025.

This wouldn't have been possible without all of you using and supporting Repomix. Thank you!

🎉 New: Repomix Website & Discord Community! Copy Chapter

• Try Repomix in your browser at repomix.com
• Join our Discord Server for support and discussion

We look forward to seeing you there!

🌟 Features Copy Chapter

• AI-Optimized: Formats your codebase in a way that's easy for AI to understand and process.
• Token Counting: Provides token counts for each file and the entire repository, useful for LLM context limits.
• Simple to Use: You need just one command to pack your entire repository.
• Customizable: Easily configure what to include or exclude.
• Git-Aware: Automatically respects your .gitignore, .ignore, and .repomixignore files.
• Security-Focused: Incorporates Secretlint to detect files matching known credential formats and leave them out of the output.
• Code Compression: The --compress option uses Tree-sitter to extract key code elements, reducing token count while preserving structure.

🚀 Quick Start Copy Chapter

Using the CLI Tool `>_` Copy Section

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 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 🌐 Copy Section

Want to try it quickly? Visit the official website at 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 🧩 Copy Section

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
• Firefox Add-on: Repomix - Firefox Add-ons

Features

• One-click access to Repomix for any GitHub repository
• More exciting features coming soon!

Using The VSCode Extension ⚡️ Copy Section

A community-maintained VSCode extension called Repomix Runner (created by 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!
Source code is available on GitHub.

Alternative Tools 🛠️ Copy Section

If you're using Python, you might want to check out Gitingest, which is better suited for Python ecosystem and data
science workflows:
https://github.com/cyclotruc/gitingest

📊 Usage Copy Chapter

To pack your entire repository:

repomix

To pack a specific directory:

repomix path/to/directory

To pack specific files or directories
using glob patterns:

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

To exclude specific files or directories:

repomix --ignore "**/*.log,tmp/"

To pack a remote repository:

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

# You can also use GitHub shorthand:
repomix --remote yamadashy/repomix

# You can specify the branch name, tag, or commit hash:
repomix --remote https://github.com/yamadashy/repomix --remote-branch main

# Or use a specific commit hash:
repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695

# Another convenient way is specifying the branch's URL
repomix --remote https://github.com/yamadashy/repomix/tree/main

# Commit's URL is also supported
repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1

To pack files from a file list (pipe via stdin):

# Using find command
find src -name "*.ts" -type f | repomix --stdin

# Using git to get tracked files
git ls-files "*.ts" | repomix --stdin

# Using grep to find files containing specific content
grep -l "TODO" **/*.ts | repomix --stdin

# Using ripgrep to find files with specific content
rg -l "TODO|FIXME" --type ts | repomix --stdin

# Using ripgrep (rg) to find files
rg --files --type ts | repomix --stdin

# Using sharkdp/fd to find files
fd -e ts | repomix --stdin

# Using fzf to select from all files
fzf -m | repomix --stdin

# Interactive file selection with fzf
find . -name "*.ts" -type f | fzf -m | repomix --stdin

# Using ls with glob patterns
ls src/**/*.ts | repomix --stdin

# From a file containing file paths
cat file-list.txt | repomix --stdin

# Direct input with echo
echo -e "src/index.ts\nsrc/utils.ts" | repomix --stdin

The --stdin option allows you to pipe a list of file paths to Repomix, giving you ultimate flexibility in selecting which files to pack.

When using --stdin, the specified files are effectively added to the include patterns. This means that the normal include and ignore behavior still applies - files specified via stdin will still be excluded if they match ignore patterns.

[!NOTE]
When using --stdin, file paths can be relative or absolute, and Repomix will automatically handle path resolution and deduplication.

To include git logs in the output:

# Include git logs with default count (50 commits)
repomix --include-logs

# Include git logs with specific commit count
repomix --include-logs --include-logs-count 10

# Combine with diffs for comprehensive git context
repomix --include-logs --include-diffs

The git logs include commit dates, messages, and file paths for each commit, providing valuable context for AI analysis of code evolution and development patterns.

To compress the output:

repomix --compress

# You can also use it with remote repositories:
repomix --remote yamadashy/repomix --compress

To initialize a new configuration file (repomix.config.json):

repomix --init

Once you have generated the packed file, you can use it with Generative AI tools like ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.

Docker Usage 🐳 Copy Section

You can also run Repomix using Docker.
This is useful if you want to run Repomix in an isolated environment or prefer using containers.

Basic usage (current directory):

docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix

To pack a specific directory:

docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix path/to/directory

Process a remote repository and output to a output directory:

docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote https://github.com/yamadashy/repomix

Prompt Examples Copy Section

Once you have generated the packed file with Repomix, you can use it with AI tools like ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.
Here are some example prompts to get you started:

Code Review and Refactoring

For a comprehensive code review and refactoring suggestions:

This file contains my entire codebase. Please review the overall structure and suggest any improvements or refactoring opportunities, focusing on maintainability and scalability.

Documentation Generation

To generate project documentation:

Based on the codebase in this file, please generate a detailed README.md that includes an overview of the project, its main features, setup instructions, and usage examples.

Test Case Generation

For generating test cases:

Analyze the code in this file and suggest a comprehensive set of unit tests for the main functions and classes. Include edge cases and potential error scenarios.

Code Quality Assessment

Evaluate code quality and adherence to best practices:

Review the codebase for adherence to coding best practices and industry standards. Identify areas where the code could be improved in terms of readability, maintainability, and efficiency. Suggest specific changes to align the code with best practices.

Library Overview

Get a high-level understanding of the library

This file contains the entire codebase of library. Please provide a comprehensive overview of the library, including its main purpose, key features, and overall architecture.

Feel free to modify these prompts based on your specific needs and the capabilities of the AI tool you're using.

Community Discussion Copy Section

Check out our community discussion where users share:

• Which AI tools they're using with Repomix
• Effective prompts they've discovered
• How Repomix has helped them
• Tips and tricks for getting the most out of AI code analysis

Feel free to join the discussion and share your own experiences! Your insights could help others make better use of
Repomix.

Output File Format Copy Section

Repomix generates a single file with clear separators between different parts of your codebase.
To enhance AI comprehension, the output file begins with an AI-oriented explanation, making it easier for AI models to
understand the context and structure of the packed repository.

XML Format (default)

The XML format structures the content in a hierarchical manner:

This file is a merged representation of the entire codebase, combining all repository files into a single document.

<file_summary>
  (Metadata and usage AI instructions)
</file_summary>

<directory_structure>
src/
cli/
cliOutput.ts
index.ts

(...remaining directories)
</directory_structure>

<files>
<file path="src/index.js">
  // File contents here
</file>

(...remaining files)
</files>


(Custom instructions from `output.instructionFilePath`)

For those interested in the potential of XML tags in AI contexts:
https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags

When your prompts involve multiple components like context, instructions, and examples, XML tags can be a
game-changer. They help Claude parse your prompts more accurately, leading to higher-quality outputs.

This means that the XML output from Repomix is not just a different format, but potentially a more effective way to feed
your codebase into AI systems for analysis, code review, or other tasks.

Markdown Format

To generate output in Markdown format, use the --style markdown option:

repomix --style markdown

The Markdown format structures the content in a hierarchical manner:

This file is a merged representation of the entire codebase, combining all repository files into a single document.

# File Summary

(Metadata and usage AI instructions)

# Repository Structure

```
src/
  cli/
    cliOutput.ts
    index.ts
```

(...remaining directories)

# Repository Files

## File: src/index.js

```
// File contents here
```

(...remaining files)

# Instruction

(Custom instructions from `output.instructionFilePath`)

This format provides a clean, readable structure that is both human-friendly and easily parseable by AI systems.

JSON Format

To generate output in JSON format, use the --style json option:

repomix --style json

The JSON format structures the content as a hierarchical JSON object with camelCase property names:

{
  "fileSummary": {
    "generationHeader": "This file is a merged representation of the entire codebase, combined into a single document by Repomix.",
    "purpose": "This file contains a packed representation of the entire repository's contents...",
    "fileFormat": "The content is organized as follows...",
    "usageGuidelines": "- This file should be treated as read-only...",
    "notes": "- Some files may have been excluded based on .gitignore, .ignore, and .repomixignore rules..."
  },
  "userProvidedHeader": "Custom header text if specified",
  "directoryStructure": "src/\n  cli/\n    cliOutput.ts\n    index.ts\n  config/\n    configLoader.ts",
  "files": {
    "src/index.js": "// File contents here",
    "src/utils.js": "// File contents here"
  },
  "instruction": "Custom instructions from instructionFilePath"
}

This format is ideal for:

• Programmatic processing: Easy to parse and manipulate with JSON libraries
• API integration: Direct consumption by web services and applications
• AI tool compatibility: Structured format for machine learning and AI systems
• Data analysis: Straightforward extraction of specific information using tools like jq

Working with JSON Output Using `jq`

The JSON format makes it easy to extract specific information programmatically:

# List all file paths
cat repomix-output.json | jq -r '.files | keys[]'

# Count total number of files
cat repomix-output.json | jq '.files | keys | length'

# Extract specific file content
cat repomix-output.json | jq -r '.files["README.md"]'
cat repomix-output.json | jq -r '.files["src/index.js"]'

# Find files by extension
cat repomix-output.json | jq -r '.files | keys[] | select(endswith(".ts"))'

# Get files containing specific text
cat repomix-output.json | jq -r '.files | to_entries[] | select(.value | contains("function")) | .key'

# Extract directory structure
cat repomix-output.json | jq -r '.directoryStructure'

# Get file summary information
cat repomix-output.json | jq '.fileSummary.purpose'
cat repomix-output.json | jq -r '.fileSummary.generationHeader'

# Extract user-provided header (if exists)
cat repomix-output.json | jq -r '.userProvidedHeader // "No header provided"'

# Create a file list with sizes
cat repomix-output.json | jq -r '.files | to_entries[] | "\(.key): \(.value | length) characters"'

Plain Text Format

To generate output in plain text format, use the --style plain option:

repomix --style plain

This file is a merged representation of the entire codebase, combining all repository files into a single document.

================================================================
File Summary
================================================================
(Metadata and usage AI instructions)

================================================================
Directory Structure
================================================================
src/
  cli/
    cliOutput.ts
    index.ts
  config/
    configLoader.ts

(...remaining directories)

================================================================
Files
================================================================

================
File: src/index.js
================
// File contents here

================
File: src/utils.js
================
// File contents here

(...remaining files)

================================================================
Instruction
================================================================
(Custom instructions from `output.instructionFilePath`)

Command Line Options Copy Section

Basic Options

• -v, --version: Show version information and exit

CLI Input/Output Options

Repomix Output Options

File Selection Options

Remote Repository Options

Configuration Options

Security Options

• --no-security-check: Skip scanning for sensitive data like API keys and passwords

Token Count Options

• --token-count-encoding <encoding>: Tokenizer model for counting: o200k_base (GPT-4o), cl100k_base (GPT-3.5/4), etc. (default: o200k_base)
• --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.

MCP

• --mcp: Run as Model Context Protocol server for AI tool integration
• --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.

Agent Skills Generation

Watch Mode

• -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.

  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).

Examples

# Basic usage
repomix

# Custom output
repomix -o output.xml --style xml

# Output to stdout
repomix --stdout > custom-output.txt

# Send output to stdout, then pipe into another command (for example, simonw/llm)
repomix --stdout | llm "Please explain what this code does."

# Custom output with compression
repomix --compress

# Process specific files
repomix --include "src/**/*.ts" --ignore "**/*.test.ts"

# Split output into multiple files (max size per part)
repomix --split-output 20mb

# Remote repository with branch
repomix --remote https://github.com/user/repo/tree/main

# Remote repository with commit
repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1

# Remote repository with shorthand
repomix --remote user/repo

# Watch mode — automatically re-pack on file changes
repomix --watch
repomix -w --include "src/**/*.ts"

Updating Repomix Copy Section

To update a globally installed Repomix:

# Using npm
npm update -g repomix

# Using yarn
yarn global upgrade repomix

# Using bun
bun update -g repomix

Using npx repomix is generally more convenient as it always uses the latest version.

Remote Repository Processing Copy Section

Repomix supports processing remote Git repositories without the need for manual cloning. This feature allows you to
quickly analyze any public Git repository with a single command.

To process a remote repository, use the --remote option followed by the repository URL:

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

You can also use GitHub's shorthand format:

repomix --remote yamadashy/repomix

You can specify the branch name, tag, or commit hash:

# Using --remote-branch option
repomix --remote https://github.com/yamadashy/repomix --remote-branch main

# Using branch's URL
repomix --remote https://github.com/yamadashy/repomix/tree/main

Or use a specific commit hash:

# Using --remote-branch option
repomix --remote https://github.com/yamadashy/repomix --remote-branch 935b695

# Using commit's URL
repomix --remote https://github.com/yamadashy/repomix/commit/836abcd7335137228ad77feb28655d85712680f1

[!NOTE]
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.

When using --config with --remote, an absolute path is required (e.g., --config /home/user/repomix.config.json).

Code Compression Copy Section

The --compress option utilizes 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.

repomix --compress

For example, this code:

import { ShoppingItem } from './shopping-item';

/**
 * Calculate the total price of shopping items
 */
const calculateTotal = (
  items: ShoppingItem[]
) => {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
  }
  return total;
}

// Shopping item interface
interface Item {
  name: string;
  price: number;
  quantity: number;
}

Will be compressed to:

import { ShoppingItem } from './shopping-item';
⋮----
/**
 * Calculate the total price of shopping items
 */
const calculateTotal = (
  items: ShoppingItem[]
) => {
⋮----
// Shopping item interface
interface Item {
  name: string;
  price: number;
  quantity: number;
}

[!NOTE]
This is an experimental feature that we'll be actively improving based on user feedback and real-world usage

Per-file Inclusion Levels (`output.patterns`) Copy Section

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:

{
  "output": {
    "compress": false, // global default acts as the catch-all
    "patterns": [
      { "pattern": "docs/**/*", "compress": true },
      { "pattern": "website/**/*", "directoryStructureOnly": true }
    ]
  }
}

There are three levels:

• Full content (default) — the file's full content is included.
• Compressed (compress: true) — the content is passed through the same Tree-sitter pipeline as --compress.
• Directory-structure-only (directoryStructureOnly: true) — the file is listed in the directory structure, but its content block is omitted from the output entirely.

Semantics:

• Patterns are evaluated in array order and the first matching pattern wins for a given file.
• 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).
• directoryStructureOnly takes precedence over compress when both are set.
• If no pattern matches, the global behavior applies (full content, or compressed when output.compress is true).

This is a config-file-only option; there is no CLI flag for per-pattern levels.

Token Count Optimization Copy Section

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:

repomix --token-count-tree

This displays a hierarchical view of your codebase with token counts:

🔢 Token Count Tree:
────────────────────
└── src/ (70,925 tokens)
    ├── cli/ (12,714 tokens)
    │   ├── actions/ (7,546 tokens)
    │   └── reporters/ (990 tokens)
    └── core/ (41,600 tokens)
        ├── file/ (10,098 tokens)
        └── output/ (5,808 tokens)

You can also set a minimum token threshold to focus on larger files:

repomix --token-count-tree 1000  # Only show files/directories with 1000+ tokens

This helps you:

• Identify token-heavy files that might exceed AI context limits
• Optimize file selection using --include and --ignore patterns
• Plan compression strategies by targeting the largest contributors
• Balance content vs. context when preparing code for AI analysis

Splitting Output for Large Codebases Copy Section

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:

repomix --split-output 1mb

This generates numbered files like:

• repomix-output.1.xml
• repomix-output.2.xml
• repomix-output.3.xml

Size can be specified with units: 500kb, 1mb, 2mb, 1.5mb, etc. Decimal values are supported.

[!NOTE]
Files are grouped by top-level directory to maintain context. A single file or directory will never be split across multiple output files.

MCP Server Integration Copy Section

Repomix supports the Model Context Protocol (MCP), 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.

repomix --mcp

Sandbox Mode

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:

# Confine to the current working directory
repomix --mcp --sandbox

# Confine to a specific directory
repomix --mcp --sandbox path/to/project

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), 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. See the MCP Server guide for details.

Configuring MCP Servers

To use Repomix as an MCP server with AI assistants like Claude, you need to configure the MCP settings:

For VS Code:

You can install the Repomix MCP server in VS Code using one of these methods:

1. Using the Install Badge:

2. Using the Command Line:

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

For VS Code Insiders:

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

For Cline (VS Code extension):

Edit the cline_mcp_settings.json file:

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

For Cursor:

In Cursor, add a new MCP server from Cursor Settings > MCP > + Add new global MCP server with a configuration similar to Cline.

For Claude Desktop:

Edit the claude_desktop_config.json file with similar configuration to Cline's config.

For Claude Code:

To configure Repomix as an MCP server in Claude Code, use the following command:

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

Alternatively, you can use the official Repomix plugins (see Claude Code Plugins section below).

Using Docker instead of npx:

You can use Docker as an alternative to npx for running Repomix as an MCP server:

{
  "mcpServers": {
    "repomix-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/yamadashy/repomix",
        "--mcp"
      ]
    }
  }
}

Once configured, your AI assistant can directly use Repomix's capabilities to analyze codebases without manual file preparation, making code analysis workflows more efficient.

Available MCP Tools

When running as an MCP server, Repomix provides the following tools:

1. pack_codebase: Package a local code directory into a consolidated XML file for AI analysis

• Parameters:
  • directory: Absolute path to the directory to pack
  • compress: (Optional, default: false) Enable Tree-sitter compression to extract essential code signatures and structure while removing implementation details. Reduces token usage by ~70% while preserving semantic meaning. Generally not needed since grep_repomix_output allows incremental content retrieval. Use only when you specifically need the entire codebase content for large repositories.
  • includePatterns: (Optional) Specify files to include using fast-glob patterns. Multiple patterns can be comma-separated (e.g., "/*.{js,ts}", "src/,docs/**"). Only matching files will be processed.
  • ignorePatterns: (Optional) Specify additional files to exclude using fast-glob patterns. Multiple patterns can be comma-separated (e.g., "test/,*.spec.js", "node_modules/,dist/**"). These patterns supplement .gitignore, .ignore, and built-in exclusions.
  • 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.
  • topFilesLength: (Optional, default: 10) Number of largest files by size to display in the metrics summary for codebase analysis.

2. attach_packed_output: Attach an existing Repomix packed output file for AI analysis

• Parameters:
  • path: Path to a directory containing repomix-output.xml or direct path to a packed repository XML file
  • topFilesLength: (Optional, default: 10) Number of largest files by size to display in the metrics summary
• Features:
  • Accepts either a directory containing a repomix-output.xml file or a direct path to an XML file
  • Registers the file with the MCP server and returns the same structure as the pack_codebase tool
  • Provides access to existing packed outputs without requiring re-processing
  • Useful for working with previously generated packed repositories

3. pack_remote_repository: Fetch, clone, and package a GitHub repository into a consolidated XML file for AI analysis

• Parameters:
  • remote: GitHub repository URL or user/repo format (e.g., "yamadashy/repomix", "https://github.com/user/repo", or "https://github.com/user/repo/tree/branch")
  • compress: (Optional, default: false) Enable Tree-sitter compression to extract essential code signatures and structure while removing implementation details. Reduces token usage by ~70% while preserving semantic meaning. Generally not needed since grep_repomix_output allows incremental content retrieval. Use only when you specifically need the entire codebase content for large repositories.
  • includePatterns: (Optional) Specify files to include using fast-glob patterns. Multiple patterns can be comma-separated (e.g., "/*.{js,ts}", "src/,docs/**"). Only matching files will be processed.
  • ignorePatterns: (Optional) Specify additional files to exclude using fast-glob patterns. Multiple patterns can be comma-separated (e.g., "test/,*.spec.js", "node_modules/,dist/**"). These patterns supplement .gitignore, .ignore, and built-in exclusions.
  • 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).
  • topFilesLength: (Optional, default: 10) Number of largest files by size to display in the metrics summary for codebase analysis.

4. read_repomix_output: Read the contents of a Repomix-generated output file. Supports partial reading with line range specification for large files.

• Parameters:
  • outputId: ID of the Repomix output file to read
  • startLine: (Optional) Starting line number (1-based, inclusive). If not specified, reads from beginning.
  • endLine: (Optional) Ending line number (1-based, inclusive). If not specified, reads to end.
• Features:
  • Specifically designed for web-based environments or sandboxed applications
  • Retrieves the content of previously generated outputs using their ID
  • Provides access to packed codebase without requiring file system access
  • Supports partial reading for large files

5. grep_repomix_output: Search for patterns in a Repomix output file using grep-like functionality with JavaScript RegExp syntax

• Parameters:
  • outputId: ID of the Repomix output file to search
  • pattern: Search pattern (JavaScript RegExp regular expression syntax)
  • contextLines: (Optional, default: 0) Number of context lines to show before and after each match. Overridden by beforeLines/afterLines if specified.
  • beforeLines: (Optional) Number of context lines to show before each match (like grep -B). Takes precedence over contextLines.
  • afterLines: (Optional) Number of context lines to show after each match (like grep -A). Takes precedence over contextLines.
  • ignoreCase: (Optional, default: false) Perform case-insensitive matching
• Features:
  • Uses JavaScript RegExp syntax for powerful pattern matching
  • Supports context lines for better understanding of matches
  • Allows separate control of before/after context lines
  • Case-sensitive and case-insensitive search options

6. file_system_read_file: Read a file inside the sandbox workspace. Only available in sandbox mode (--sandbox), where the workspace root bounds what it can reach.

• Parameters:
  • path: Path to the file to read, relative to the workspace root (e.g. src/index.ts)
• Notes:
  • Not registered without --sandbox
  • Content matching known secret formats (Secretlint) is refused as an additional heuristic safeguard — the access boundary is the workspace root, not the scan

7. file_system_read_directory: List the contents of a directory inside the sandbox workspace. Only available in sandbox mode (--sandbox).

• Parameters:
  • path: Path to the directory to list, relative to the workspace root (e.g. . or src)
• Features:
  • Shows files and directories with clear indicators ([FILE] or [DIR])
  • Useful for exploring project structure and understanding codebase organization

Claude Code Plugins Copy Section

Repomix provides official plugins for Claude Code that integrate seamlessly with the AI-powered development environment.

Installation

1. Add the Repomix plugin marketplace:

/plugin marketplace add yamadashy/repomix

2. Install plugins:

# Install MCP server plugin (recommended foundation)
/plugin install repomix-mcp@repomix

# Install commands plugin (extends functionality)
/plugin install repomix-commands@repomix

# Install repository explorer plugin (AI-powered analysis)
/plugin install repomix-explorer@repomix

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.

Alternatively, use the interactive plugin installer:

/plugin

This will open an interactive interface where you can browse and install available plugins.

Available Plugins

1. repomix-mcp (MCP Server Plugin)

Foundation plugin that provides AI-powered codebase analysis through MCP server integration.

Features:

• Pack local and remote repositories
• Read and search packed outputs
• Automatic Tree-sitter compression (~70% token reduction)

2. repomix-commands (Slash Commands Plugin)

Provides convenient slash commands for quick operations with natural language support.

Available Commands:

• /repomix-commands:pack-local - Pack local codebase with various options
• /repomix-commands:pack-remote - Pack and analyze remote GitHub repositories

Example usage:

/repomix-commands:pack-local
Pack this project as markdown with compression

/repomix-commands:pack-remote yamadashy/repomix
Pack only TypeScript files from the yamadashy/repomix repository

3. repomix-explorer (AI Analysis Agent Plugin)

AI-powered repository analysis agent that intelligently explores codebases using Repomix CLI.

Features:

• Natural language codebase exploration and analysis
• Intelligent pattern discovery and code structure understanding
• Incremental analysis using grep and targeted file reading
• Automatic context management for large repositories

Available Commands:

• /repomix-explorer:explore-local - Analyze local codebase with AI assistance
• /repomix-explorer:explore-remote - Analyze remote GitHub repositories with AI assistance

Example usage:

/repomix-explorer:explore-local ./src
Find all authentication-related code

/repomix-explorer:explore-remote facebook/react
Show me the main component architecture

The agent automatically:

1. Runs npx repomix@latest to pack the repository
2. Uses Grep and Read tools to efficiently search the output
3. Provides comprehensive analysis without consuming excessive context

Benefits

• Seamless Integration: Claude can directly analyze codebases without manual preparation
• Natural Language: Use conversational commands instead of remembering CLI syntax
• Always Latest: Automatically uses npx repomix@latest for up-to-date features
• Secret Scanning: Secretlint flags files matching known credential formats so they are left out of the output
• Token Optimization: Tree-sitter compression for large codebases

For more details, see the plugin documentation in the .claude/plugins/ directory.

Agent Skills Generation Copy Section

Repomix can generate Claude Agent 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.

Basic Usage

# Generate Skills from local directory
repomix --skill-generate

# Generate with custom Skills name
repomix --skill-generate my-project-reference

# Generate with a custom project name in Skills descriptions
repomix --skill-generate --skill-project-name "My Project"

# Generate from remote repository
repomix --remote https://github.com/user/repo --skill-generate

When you run the command, Repomix prompts you to choose where to save the Skills:

1. Personal Skills (~/.claude/skills/) - Available across all projects on your machine
2. Project Skills (.claude/skills/) - Shared with your team via git

Non-Interactive Usage

For CI pipelines and automation scripts, you can skip all interactive prompts using --skill-output and --force:

# Specify output directory directly
repomix --skill-generate --skill-output ./my-skills

# Skip overwrite confirmation with --force
repomix --skill-generate --skill-output ./my-skills --force

# Full non-interactive example
repomix --remote user/repo --skill-generate my-skill --skill-output ./output --force

Generated Structure

The Skills are generated with the following structure:

.claude/skills/<skill-name>/
├── SKILL.md                 # Main Skills metadata & documentation
└── references/
    ├── summary.md           # Purpose, format, and statistics
    ├── project-structure.md # Directory tree with line counts
    ├── files.md             # All file contents (grep-friendly)
    └── tech-stacks.md       # Languages, frameworks, dependencies

What's Included

• SKILL.md: Contains Skills metadata, file/line/token counts, overview, and usage instructions
• summary.md: Explains the Skills' purpose, usage guidelines, and provides statistics breakdown by file type and language
• project-structure.md: Directory tree with line counts per file for easy file discovery
• files.md: All file contents with syntax highlighting headers, optimized for grep-friendly searching
• tech-stacks.md: Auto-detected tech stack per package from dependency files (package.json, requirements.txt, Cargo.toml, etc.)

Auto-Generated Skills Names

If no name is provided, Repomix auto-generates one:

repomix src/ --skill-generate                # → repomix-reference-src
repomix --remote user/repo --skill-generate  # → repomix-reference-repo
repomix --skill-generate CustomName          # → custom-name (normalized to kebab-case)

Integration with Repomix Features

Skills generation respects all standard Repomix options:

# Generate Skills with file filtering
repomix --skill-generate --include "src/**/*.ts" --ignore "**/*.test.ts"

# Generate Skills with compression
repomix --skill-generate --compress

# Generate Skills from remote repository
repomix --remote yamadashy/repomix --skill-generate

Repomix Explorer Skill (Agent Skills) Copy Section

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.

Quick Install

For Claude Code, install the official Repomix Explorer plugin:

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

For Codex, Cursor, OpenClaw, and other Agent Skills-compatible assistants, install the standalone skill with the Skills CLI:

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

To target a specific assistant, pass --agent:

npx skills add yamadashy/repomix --skill repomix-explorer --agent codex
npx skills add yamadashy/repomix --skill repomix-explorer --agent openclaw

For Hermes Agent, install the single-file skill with Hermes Agent's native skills command:

hermes skills install https://raw.githubusercontent.com/yamadashy/repomix/main/skills/repomix-explorer/SKILL.md

What It Does

Once installed, you can analyze codebases with natural language instructions.

Analyze remote repositories:

"What's the structure of this repo?
https://github.com/facebook/react"

Explore local codebases:

"What's in this project?
~/projects/my-app"

This is useful not only for understanding codebases, but also when you want to implement features by referencing your other repositories.

⚙️ Configuration Copy Chapter

Repomix supports multiple configuration file formats for flexibility and ease of use.

Configuration File Formats Copy Section

Repomix will automatically search for configuration files in the following priority order:

1. TypeScript (repomix.config.ts, repomix.config.mts, repomix.config.cts)
2. JavaScript/ES Module (repomix.config.js, repomix.config.mjs, repomix.config.cjs)
3. JSON (repomix.config.json5, repomix.config.jsonc, repomix.config.json)

JSON Configuration

Create a repomix.config.json file in your project root:

repomix --init

This will create a repomix.config.json file with default settings.

TypeScript Configuration

TypeScript configuration files provide the best developer experience with full type checking and IDE support.

Installation:

To use TypeScript or JavaScript configuration with defineConfig, you need to install Repomix as a dev dependency:

npm install -D repomix

Example:

// repomix.config.ts
import { defineConfig } from 'repomix';

export default defineConfig({
  output: {
    filePath: 'output.xml',
    style: 'xml',
    removeComments: true,
  },
  ignore: {
    customPatterns: ['**/node_modules/**', '**/dist/**'],
  },
});

Benefits:

• ✅ Full TypeScript type checking in your IDE
• ✅ Excellent IDE autocomplete and IntelliSense
• ✅ Use dynamic values (timestamps, environment variables, etc.)

Dynamic Values Example:

// repomix.config.ts
import { defineConfig } from 'repomix';

// Generate timestamp-based filename
const timestamp = new Date().toISOString().slice(0, 19).replace(/[:.]/g, '-');

export default defineConfig({
  output: {
    filePath: `output-${timestamp}.xml`,
    style: 'xml',
  },
});

JavaScript Configuration

JavaScript configuration files work the same as TypeScript, supporting defineConfig and dynamic values.

Configuration Options Copy Section

Here's an explanation of the configuration options:

The configuration file supports JSON5 syntax, which allows:

• Comments (both single-line and multi-line)
• Trailing commas in objects and arrays
• Unquoted property names
• More relaxed string syntax

Schema Validation Copy Section

You can enable schema validation for your configuration file by adding the $schema property:

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml"
  }
}

This provides auto-completion and validation in editors that support JSON schema.

Example Configuration Copy Section

Example configuration:

/* Detailed source-code truncated for AI context efficiency. */

Global Configuration Copy Section

To create a global configuration file:

repomix --init --global

The global configuration file will be created in:

• Windows: %LOCALAPPDATA%\Repomix\repomix.config.json
• macOS/Linux: $XDG_CONFIG_HOME/repomix/repomix.config.json or ~/.config/repomix/repomix.config.json

Note: Local configuration (if present) takes precedence over global configuration.

Include and Ignore Copy Section

Include Patterns

Repomix now supports specifying files to include
using glob patterns. This allows for more
flexible and powerful file selection:

• Use **/*.js to include all JavaScript files in any directory
• Use src/**/* to include all files within the src directory and its subdirectories
• Combine multiple patterns like ["src/**/*.js", "**/*.md"] to include JavaScript files in src and all Markdown
  files

Ignore Patterns

Repomix offers multiple methods to set ignore patterns for excluding specific files or directories during the packing
process:

• .gitignore: By default, patterns listed in your project's .gitignore files and .git/info/exclude are used. This behavior can be controlled with the ignore.useGitignore setting or the --no-gitignore cli option.
• .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.
• Default patterns: Repomix includes a default list of commonly excluded files and directories (e.g., node_modules,
  .git, binary files). This feature can be controlled with the ignore.useDefaultPatterns setting or the --no-default-patterns cli option. Please
  see defaultIgnore.ts for more details.
• .repomixignore: You can create a .repomixignore file in your project root to define Repomix-specific ignore
  patterns. This file follows the same format as .gitignore.
• Custom patterns: Additional ignore patterns can be specified using the ignore.customPatterns option in the
  configuration file. You can overwrite this setting with the -i, --ignore command line option.

Priority Order (from highest to lowest):

1. Custom patterns (ignore.customPatterns)
2. Ignore files (.repomixignore, .ignore, .gitignore, and .git/info/exclude):
   • When in nested directories, files in deeper directories have higher priority
   • When in the same directory, these files are merged in no particular order
3. Default patterns (if ignore.useDefaultPatterns is true and --no-default-patterns is not used)

This approach allows for flexible file exclusion configuration based on your project's needs. It helps optimize the size
of the generated pack file by ensuring the exclusion of security-sensitive files and large binary files, while
preventing the leakage of confidential information.

Note: Binary files are not included in the packed output by default, but their paths are listed in the "Repository
Structure" section of the output file. This provides a complete overview of the repository structure while keeping the
packed file efficient and text-based.

Custom Instruction Copy Section

The output.instructionFilePath option allows you to specify a separate file containing detailed instructions or
context about your project. This allows AI systems to understand the specific context and requirements of your project,
potentially leading to more relevant and tailored analysis or suggestions.

Here's an example of how you might use this feature:

1. Create a file named repomix-instruction.md in your project root:

# Coding Guidelines

- Follow the Airbnb JavaScript Style Guide
- Suggest splitting files into smaller, focused units when appropriate
- Add comments for non-obvious logic. Keep all text in English
- All new features should have corresponding unit tests

# Generate Comprehensive Output

- Include all content without abbreviation, unless specified otherwise
- Optimize for handling large codebases while maintaining output quality

2. In your repomix.config.json, add the instructionFilePath option:

{
  "output": {
    "instructionFilePath": "repomix-instruction.md",
    // other options...
  }
}

When Repomix generates the output, it will include the contents of repomix-instruction.md in a dedicated section.

Note: The instruction content is appended at the end of the output file. This placement can be particularly effective
for AI systems. For those interested in understanding why this might be beneficial, Anthropic provides some insights in
their documentation:
https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips

Put long-form data at the top: Place your long documents and inputs (~20K+ tokens) near the top of your prompt, above
your query, instructions, and examples. This can significantly improve Claude's performance across all models.
Queries at the end can improve response quality by up to 30% in tests, especially with complex, multi-document inputs.

Comment Removal Copy Section

When output.removeComments is set to true, Repomix will attempt to remove comments from supported file types. This
feature can help reduce the size of the output file and focus on the essential code content.

Supported languages include:
HTML, CSS, JavaScript, TypeScript, Vue, Svelte, Python, PHP, Ruby, C, C#, Java, Go, Rust, Swift, Kotlin, Dart, Shell,
and YAML.

Note: The comment removal process is conservative to avoid accidentally removing code. In complex cases, some comments
might be retained.

File Processors Copy Section

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, SVG minification, or notebook→script conversion.

{
  "input": {
    "processors": [
      { "pattern": "**/*.json", "command": "npx @toon-format/cli {file}" }
    ]
  }
}

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).

Example commands (each is a command value paired with a suitable pattern):

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).

[!WARNING]
File processors run arbitrary commands from your config file, so execution is default-deny:

• 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.
• Disabled for the library API (pack() / runCli()), the MCP server, and the hosted repomix.com.
• 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.

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 for details.

🔍 Security Check Copy Chapter

Repomix includes a security check feature that uses Secretlint to detect
potentially sensitive information in your files. This feature helps you identify possible security risks before sharing
your packed repository.

The security check results will be displayed in the CLI output after the packing process is complete. If any suspicious
files are detected, you'll see a list of these files along with a warning message.

Example output:

🔍 Security Check:
──────────────────
2 suspicious file(s) detected:
1. src/utils/test.txt
2. tests/utils/secretLintUtils.test.ts

Please review these files for potentially sensitive information.

By default, Repomix's security check feature is enabled. You can disable it by setting security.enableSecurityCheck to
false in your configuration file:

{
  "security": {
    "enableSecurityCheck": false
  }
}

Or using the --no-security-check command line option:

repomix --no-security-check

[!NOTE]
Disabling security checks may expose sensitive information. Use this option with caution and only when necessary, such
as when working with test files or documentation that contains example credentials.

Remote Repository Config Trust Copy Section

A repomix.config.* is code, not just data: a .ts / .js config is executed when loaded, input.processors runs
external commands, and path options can read files outside the repository. Loading one from an unfamiliar repository is
comparable to running its Makefile.

For that reason, a cloned repository's config is never loaded by default. Your global config and CLI options still
apply.

When you opt in with --remote-trust-config (or REPOMIX_REMOTE_TRUST_CONFIG=true) on an interactive terminal, Repomix
shows the config that is about to run and asks before loading it:

• Yes, once — trust this run only.
• Yes, and don't ask again for this repository — the decision is content-pinned: it records a hash of the config
  you approved, so you are asked again if that repository later ships a different one (the direnv allow model).
• No (the default selection) — abort without loading the config.

The displayed config is written by the repository's author, so control, ANSI, and bidirectional characters are escaped,
the output is capped, every config line is prefixed, and symlinked configs pointing outside the clone are refused — what
you review is what runs.

The prompt is skipped with --force, in non-interactive shells such as CI (existing automation keeps working), and once
you have chosen to always trust that repository.

[!IMPORTANT]
The content pin covers the entry config file only. A .ts / .js config can import other files and
input.processors can invoke external scripts; neither is hashed. Treat "don't ask again" as trust in the repository,
not only in the file you read.

See the security guide for the full trust model.

🤖 Using Repomix with GitHub Actions Copy Chapter

You can also use Repomix in your GitHub Actions workflows. This is useful for automating the process of packing your codebase for AI analysis.

Basic usage:

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.xml
    style: xml

Use --style to generate output in different formats:

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.md
    style: markdown

- name: Pack repository with Repomix (JSON format)
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    output: repomix-output.json
    style: json

Pack specific directories with compression:

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    directories: src tests
    include: "**/*.ts,**/*.md"
    ignore: "**/*.test.ts"
    output: repomix-output.txt
    compress: true

Upload the output file as an artifact:

- name: Pack repository with Repomix
  uses: yamadashy/repomix/.github/actions/repomix@main
  with:
    directories: src
    output: repomix-output.txt
    compress: true

- name: Upload Repomix output
  uses: actions/upload-artifact@v7
  with:
    name: repomix-output
    path: repomix-output.txt

Complete workflow example:

name: Pack repository with Repomix

on:
  workflow_dispatch:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  pack-repo:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Pack repository with Repomix
        uses: yamadashy/repomix/.github/actions/repomix@main
        with:
          output: repomix-output.xml

      - name: Upload Repomix output
        uses: actions/upload-artifact@v7
        with:
          name: repomix-output.xml
          path: repomix-output.xml
          retention-days: 30

See the complete workflow example here.

Action Inputs Copy Section

Action Outputs Copy Section

📚 Using Repomix as a Library Copy Chapter

In addition to using Repomix as a CLI tool, you can also use it as a library in your Node.js applications.

Installation Copy Section

npm install repomix

Basic Usage Copy Section

import { runCli, type CliOptions } from 'repomix';

// Process current directory with custom options
async function packProject() {
  const options = {
    output: 'output.xml',
    style: 'xml',
    compress: true,
    quiet: true
  } as CliOptions;
  
  const result = await runCli(['.'], process.cwd(), options);
  return result.packResult;
}

Process Remote Repository Copy Section

import { runCli, type CliOptions } from 'repomix';

// Clone and process a GitHub repo
async function processRemoteRepo(repoUrl) {
  const options = {
    remote: repoUrl,
    output: 'output.xml',
    compress: true
  } as CliOptions;
  
  return await runCli(['.'], process.cwd(), options);
}

Using Core Components Copy Section

If you need more control, you can use the low-level APIs:

import { searchFiles, collectFiles, processFiles, TokenCounter } from 'repomix';

async function analyzeFiles(directory) {
  // Find and collect files
  const { filePaths } = await searchFiles(directory, { /* config */ });
  const rawFiles = await collectFiles(filePaths, directory);
  const processedFiles = await processFiles(rawFiles, { /* config */ });
  
  // Count tokens
  const tokenCounter = new TokenCounter('o200k_base');
  
  // Return analysis results
  return processedFiles.map(file => ({
    path: file.path,
    tokens: tokenCounter.countTokens(file.content)
  }));
}

For more examples, check the source code at website/server/src/remoteRepo.ts which demonstrates how repomix.com uses the library.

Bundling Copy Section

When bundling repomix with tools like Rolldown or esbuild, some dependencies must remain external and WASM files need to be copied:

External dependencies (cannot be bundled):

• tinypool - Spawns worker threads using file paths

WASM files to copy:

• web-tree-sitter.wasm → Same directory as bundled JS (required for code compression feature)
• Tree-sitter language files → Directory specified by REPOMIX_WASM_DIR environment variable

For a working example, see website/server/scripts/bundle.mjs.

🌍 Community Projects Copy Chapter

Discover amazing projects built by the Repomix community!

• Repomix Runner - VSCode extension for bundling files into a single output for AI processing
• Repomix Desktop - GUI desktop application for Repomix built with Python and CustomTkinter
• Python Repomix - Python implementation with AST-based compression
• Rulefy - Transform GitHub repos into custom Cursor AI rules using Claude AI
• Codebase MCP - MCP server that uses Repomix for AI-powered codebase analysis
• vibe-tools - CLI toolset for AI agents with web search, repo analysis, and browser automation

For more details, visit our Community Projects page.

🤝 Contribution Copy Chapter

We welcome contributions from the community! To get started, please refer to our Contributing Guide.

Contributors Copy Section

🔒 Privacy Policy Copy Chapter

See our Privacy Policy.

📜 License Copy Chapter

This project is licensed under the MIT License.

File: browser/README.md Copy Chapter

Repomix Extension

A browser extension that adds a Repomix button to GitHub repository pages.

🚀 Features Copy Chapter

• Adds a "Repomix" button to GitHub repository pages
• One-click redirect to Repomix (https://repomix.com)
• Seamlessly integrates with GitHub's UI design
• Works on Chrome, Firefox, and Edge

🛠️ Usage Copy Chapter

1. Install the browser extension
2. Navigate to any GitHub repository page
3. A "Repomix" button will appear in the page header action area
4. Click the button to open the repository in Repomix

💻 Development Copy Chapter

Prerequisites Copy Section

• Node.js 22 or higher

Setup Copy Section

# Install dependencies
npm install

# Generate icons
npm run generate-icons

# Development mode for Chrome
npm run dev chrome

# Development mode for Firefox
npm run dev firefox

# Development mode for Edge
npm run dev edge

Build Copy Section

# Build for all browsers
npm run build-all

# Build for specific browsers
npm run build chrome
npm run build firefox
npm run build edge

Built files will be generated in the dist/ folder.

Manual Installation Copy Section

1. Run npm run build chrome to build
2. Open chrome://extensions/ in Chrome
3. Enable "Developer mode"
4. Click "Load unpacked extension"
5. Select the dist/chrome folder

📝 Technical Specifications Copy Chapter

• Manifest V3 - Latest browser extension specification
• Content Scripts - Direct button injection into GitHub pages
• Internationalization - English and Japanese support
• Cross-browser - Chrome, Firefox, Edge support

🔒 Privacy Copy Chapter

This extension:

• Does not collect any data
• Does not track user behavior
• Only accesses github.com
• Requires minimal permissions

File: src/core/treeSitter/queries/README.md Copy Chapter

Credits

Repomix uses modified versions of tree-sitter queries from Aider and Cline:

• https://github.com/Aider-AI/aider — licensed under the Apache License 2.0.
• https://github.com/cline/cline — licensed under the Apache License 2.0.

Aider uses modified versions of the tags.scm files from these open source
tree-sitter language implementations:

• https://github.com/tree-sitter/tree-sitter-c — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-c-sharp — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-cpp — licensed under the MIT License.
• https://github.com/Wilfred/tree-sitter-elisp — licensed under the MIT License.
• https://github.com/elixir-lang/tree-sitter-elixir — licensed under the Apache License, Version 2.0.
• https://github.com/elm-tooling/tree-sitter-elm — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-go — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-java — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-javascript — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-ocaml — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-php — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-python — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-ql — licensed under the MIT License.
• https://github.com/r-lib/tree-sitter-r — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-ruby — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-rust — licensed under the MIT License.
• https://github.com/tree-sitter/tree-sitter-typescript — licensed under the MIT License.

File: website/client/src/zh-tw/guide/development/index.md Copy Chapter

title: 參與 Repomix 開發 Copy Chapter

參與 Repomix 開發

感謝您對 Repomix 的興趣！🚀 我們非常歡迎您的幫助，讓它變得更好。本指南將幫助您開始為專案做貢獻。

如何貢獻 Copy Chapter

• 為儲存庫加星: 通過為儲存庫加星來表示您的支持！
• 建立問題: 發現了bug？有新功能的想法？通過建立問題讓我們知道。
• 提交拉取請求: 找到了可以修復或改進的地方？提交PR吧！
• 傳播訊息: 在社交媒體、部落格或技術社群中分享您使用Repomix的經驗。
• 使用Repomix: 最有價值的反饋來自實際使用，請隨時將Repomix整合到您自己的專案中！
• 贊助: 通過成為贊助者來支持Repomix的開發。

快速開始 Copy Chapter

git clone https://github.com/yamadashy/repomix.git
cd repomix
npm install

開發命令 Copy Chapter

# 運行 CLI
npm run repomix

# 運行測試
npm run test
npm run test-coverage

# 程式碼檢查
npm run lint

程式碼風格 Copy Chapter

• 使用 Biome 進行程式碼檢查和格式化
• 使用依賴注入以提高可測試性
• 保持文件不超過 250 行
• 為新功能添加測試用例

Pull Request 提交指南 Copy Chapter

1. 運行所有測試
2. 通過程式碼檢查
3. 更新文檔
4. 遵循現有程式碼風格

開發環境設置 Copy Chapter

前提條件 Copy Section

• Node.js ≥ 22.0.0
• Git
• npm
• Docker（可選，用於運行網站或容器化開發）

本地開發 Copy Section

要為Repomix設置本地開發環境：

# 克隆儲存庫
git clone https://github.com/yamadashy/repomix.git
cd repomix

# 安裝依賴
npm install

# 運行CLI
npm run repomix

Nix開發 Copy Section

如果您啟用了 Nix flakes，可以進入預裝了 Node.js 24 和 Git 的可重現開發 shell：

nix develop

在 shell 中，標準的 npm 工作流可以正常使用：

npm ci
npm run build
npm run test
npm run lint

注意：此 shell 用於開發 Repomix 本身，不是用於將其作為 CLI 安裝。

Docker開發 Copy Section

您也可以使用Docker運行Repomix：

# 構建鏡像
docker build -t repomix .

# 運行容器
docker run -v ./:/app -it --rm repomix

項目結構 Copy Section

項目組織為以下目錄：

src/
├── cli/          # CLI實現
├── config/       # 配置處理
├── core/         # 核心功能
│   ├── file/     # 文件處理
│   ├── metrics/  # 指標計算
│   ├── output/   # 輸出生成
│   ├── security/ # 安全檢查
├── mcp/          # MCP服務器集成
└── shared/       # 共享工具
tests/            # 反映src/結構的測試
website/          # 文檔網站
├── client/       # 前端（VitePress）
└── server/       # 後端API

網站開發 Copy Chapter

Repomix網站使用VitePress構建。要在本地運行網站：

# 先決條件：系統上必須安裝Docker

# 啟動網站開發服務器
npm run website

# 在http://localhost:5173/訪問網站

更新文檔時，您只需先更新英文版本。維護者將處理其他語言的翻譯。

發布流程 Copy Chapter

對於維護者和有興趣的貢獻者的發布流程：

1. 更新版本

npm version patch  # 或minor/major

2. 運行測試和構建

npm run test-coverage
npm run build

3. 發布

npm publish

新版本由維護者管理。如果您認為需要發布，請打開一個Issue進行討論。

需要幫助？ Copy Chapter

• 提交 Issue
• 加入 Discord

File: website/client/src/zh-tw/guide/development/using-repomix-as-a-library.md Copy Chapter

title: 作為庫使用 Repomix Copy Chapter

作為庫使用 Repomix

除了作為 CLI 工具使用 Repomix 外，您還可以將其功能直接集成到 Node.js 應用程序中。

安裝 Copy Chapter

在您的項目中安裝 Repomix 作為依賴項：

npm install repomix

基本用法 Copy Chapter

使用 Repomix 最簡單的方法是通過 runCli 函數，它提供與命令行界面相同的功能：

import { runCli, type CliOptions } from 'repomix';

// 使用自定義選項處理當前目錄
async function packProject() {
  const options = {
    output: 'output.xml',
    style: 'xml',
    compress: true,
    quiet: true
  } as CliOptions;
  
  const result = await runCli(['.'], process.cwd(), options);
  return result.packResult;
}

result.packResult 包含有關處理文件的信息，包括：

• totalFiles：處理的文件數量
• totalCharacters：總字符數
• totalTokens：總令牌數（對 LLM 上下文限制有用）
• fileCharCounts：每個文件的字符數
• fileTokenCounts：每個文件的令牌數

處理遠端倉庫 Copy Chapter

您可以克隆並處理遠端倉庫：

import { runCli, type CliOptions } from 'repomix';

// 克隆並處理 GitHub 倉庫
async function processRemoteRepo(repoUrl) {
  const options = {
    remote: repoUrl,
    output: 'output.xml',
    compress: true
  } as CliOptions;
  
  return await runCli(['.'], process.cwd(), options);
}

[!NOTE]
基於安全考量，遠端倉庫中的設定檔預設不會被載入。如需信任遠端倉庫的設定，請在選項中加入 remoteTrustConfig: true，或設定環境變數 REPOMIX_REMOTE_TRUST_CONFIG=true。

使用核心組件 Copy Chapter

要獲得更多控制，您可以直接使用 Repomix 的低級 API：

import { searchFiles, collectFiles, processFiles, TokenCounter } from 'repomix';

async function analyzeFiles(directory) {
  // 查找並收集文件
  const { filePaths } = await searchFiles(directory, { /* 配置 */ });
  const rawFiles = await collectFiles(filePaths, directory);
  const processedFiles = await processFiles(rawFiles, { /* 配置 */ });
  
  // 計算令牌
  const tokenCounter = new TokenCounter('o200k_base');
  
  // 返回分析結果
  return processedFiles.map(file => ({
    path: file.path,
    tokens: tokenCounter.countTokens(file.content)
  }));
}

打包 Copy Chapter

使用 Rolldown 或 esbuild 等工具打包 repomix 時，某些依賴項必須保持為 external，並且需要複製 WASM 文件：

External 依賴項（無法打包）：

• tinypool - 使用文件路徑生成 worker 線程

需要複製的 WASM 文件：

• web-tree-sitter.wasm → 與打包後的 JS 相同的目錄（代碼壓縮功能需要）
• Tree-sitter 語言文件 → REPOMIX_WASM_DIR 環境變數指定的目錄

有關實際示例，請參閱 website/server/scripts/bundle.mjs。

實際示例 Copy Chapter

Repomix 網站（repomix.com）使用 Repomix 作為庫來處理遠端倉庫。您可以在 website/server/src/remoteRepo.ts 中查看實現。

File: website/client/src/zh-tw/guide/tips/best-practices.md Copy Chapter

title: AI 輔助開發最佳實踐：從實踐經驗談起 Copy Chapter

AI 輔助開發最佳實踐：從實踐經驗談起

雖然我還沒有完成一個大型的 AI 輔助開發項目，但我想分享一下到目前為止從與 AI 合作開發中學到的經驗。

基本開發方法 Copy Chapter

在與 AI 合作時，試圖一次性實現所有功能可能會導致意外問題和項目停滯。因此，從核心功能開始，一步一步穩紮穩打地構建每個功能是更有效的方法。

現有程式碼的重要性 Copy Section

這種方法之所以有效，是因為通過核心功能的實現，你可以將你理想中的設計和編碼風格具體化為實際程式碼。向 AI 傳達項目願景的最有效方式就是通過反映你的標準和偏好的程式碼本身。

從核心功能開始，確保每個功能在進入下一個功能之前都能正常工作，這樣整個項目就能保持一致性，使 AI 更容易生成更合適的程式碼。

模組化方法 Copy Chapter

將程式碼分解成更小的模組至關重要。根據經驗，將文件限制在 250 行左右的程式碼使得向 AI 提供清晰的指示更容易，並使試錯過程更有效。雖然令牌計數會是更準確的指標，但對人類開發者來說，行數更容易判斷，所以我們使用行數作為參考。

這不僅僅是關於前端、後端和數據庫等大單元的分離，而是關於更精細層面的功能劃分。例如，在一個功能內部，也要將驗證、錯誤處理等具體功能分離成獨立模組。

當然，大單元的分離也很重要，逐步實施模組化方法不僅讓指令更清晰，也讓 AI 能生成更合適的程式碼。這種方法不僅對 AI，對人類開發者來說也是有效的。

通過測試確保質量 Copy Chapter

我認為測試在 AI 輔助開發中尤為重要。測試不僅作為質量保證手段，還作為清晰展示程式碼意圖的文檔。當要求 AI 實現新功能時，現有的測試程式碼有效地充當了規範文檔。

測試也是驗證 AI 生成程式碼正確性的絕佳工具。例如，當讓 AI 為某個模組實現新功能時，預先編寫測試用例可以客觀評估生成的程式碼是否符合預期。這與測試驅動開發（TDD）的理念高度契合，在與 AI 協作時特別有效。

規劃與實現的平衡 Copy Chapter

在實現大規模功能之前，建議先與 AI 討論計劃。整理需求並考慮架構可以使後續實現更順暢。先整理需求，然後在新的對話中進行實現是個好方法。

此外，AI 的輸出必須經過人工審查，並在必要時進行調整。雖然 AI 輸出的質量通常處於中等水準，但與從頭開始編寫程式碼相比，仍然可以提高開發速度。

結語 Copy Chapter

通過實踐這些方法，你可以充分發揮 AI 的優勢，同時構建一個連貫的、高質量的程式碼庫。即使項目規模增長，每個部分都能保持清晰定義和易於管理的狀態。

File: website/client/src/zh-tw/guide/code-compress.md Copy Chapter

title: 程式碼壓縮 Copy Chapter

程式碼壓縮

程式碼壓縮是一個強大的功能，它能夠在移除實現細節的同時智能提取關鍵程式碼結構。在需要減少令牌數量的同時保持程式碼庫的重要結構信息時，這個功能特別有用。

[!NOTE]
這是一個實驗性功能，我們將根據用戶反饋和實際使用情況積極改進。

基本用法 Copy Chapter

使用 --compress 標誌啟用程式碼壓縮：

repomix --compress

也可以在遠端倉庫中使用：

repomix --remote user/repo --compress

工作原理 Copy Chapter

壓縮算法使用 Tree-sitter 解析處理程式碼，提取並保留基本結構元素，同時移除實現細節。

壓縮會保留：

• 函數和方法簽名
• 介面和類型定義
• 類結構和屬性
• 重要的結構元素

同時會移除：

• 函數和方法實現
• 迴圈和條件邏輯細節
• 內部變量聲明
• 具體實現程式碼

示例 Copy Section

原始 TypeScript 程式碼：

import { ShoppingItem } from './shopping-item';

/**
 * Calculate the total price of shopping items
 */
const calculateTotal = (
  items: ShoppingItem[]
) => {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
  }
  return total;
}

// Shopping item interface
interface Item {
  name: string;
  price: number;
  quantity: number;
}

壓縮後：

import { ShoppingItem } from './shopping-item';
⋮----
/**
 * Calculate the total price of shopping items
 */
const calculateTotal = (
  items: ShoppingItem[]
) => {
⋮----
// Shopping item interface
interface Item {
  name: string;
  price: number;
  quantity: number;
}

配置 Copy Chapter

你可以在配置文件中啟用壓縮：

{
  "output": {
    "compress": true
  }
}

使用場景 Copy Chapter

程式碼壓縮在以下情況特別有用：

• 分析程式碼結構和架構
• 減少用於 LLM 處理的令牌數量
• 建立高層次文件
• 理解程式碼模式和簽名
• 共享 API 和介面設計

相關選項 Copy Chapter

你可以將壓縮與其他選項結合使用：

• --remove-comments: 移除程式碼註釋（參見註釋移除）
• --remove-empty-lines: 移除空行
• --output-show-line-numbers: 在輸出中添加行號

相關資源 Copy Chapter

• 註釋移除 - 移除註釋以進一步減少令牌數量
• 設定 - 在設定檔中設定 output.compress
• 命令列選項 - 完整的 CLI 參考

File: website/client/src/zh-tw/guide/command-line-options.md Copy Chapter

title: 命令列選項 Copy Chapter

命令列選項

基本選項 Copy Chapter

• -v, --version: 顯示版本資訊並退出

CLI 輸入/輸出選項 Copy Chapter

Repomix 輸出選項 Copy Chapter

檔案選擇選項 Copy Chapter

遠端儲存庫選項 Copy Chapter

組態選項 Copy Chapter

安全選項 Copy Chapter

• --no-security-check: 跳過敏感資料（如 API 金鑰和密碼）的掃描

權杖計數選項 Copy Chapter

• --token-count-encoding <encoding>: 計數用的分詞器模型：o200k_base（GPT-4o）、cl100k_base（GPT-3.5/4）等（預設：o200k_base）
• --token-budget <number>: 當打包輸出超過 N 個權杖時以非零退出碼失敗。可在 CI 流水線和 agent 工作流程中作為防護，使輸出保持在目標模型的上下文視窗內。輸出仍會產生，僅由退出碼標示溢位

MCP 選項 Copy Chapter

• --mcp: 作為 Model Context Protocol 伺服器運行，用於 AI 工具整合
• --sandbox [dir]: （搭配 --mcp 使用）將 MCP 伺服器的檔案工具限制在一個工作區目錄內（預設為目前工作目錄；例如：--sandbox path/to/project）。所有路徑皆相對於該根目錄解析，絕對路徑／主機路徑會被拒絕，同時遠端打包、Skills 生成以及附加外部輸出功能皆會被停用。詳見 MCP 伺服器

Agent Skills 生成選項 Copy Chapter

監視模式選項 Copy Chapter

• -w, --watch: 監視檔案變更並自動重新打包。會偵測新增、修改和刪除的檔案，對快速連續的變更進行防抖處理（300 毫秒），並在每次重新建構後印出時間戳記。按 Ctrl+C 停止。

監視模式僅適用於本機目錄，因此無法與 --remote、作為位置參數傳入的遠端儲存庫 URL、--stdout、--stdin、--split-output、--skill-generate 或 --copy 組合使用。無論該選項是在命令列還是在組態檔中設定，這些限制都適用。

相關資源 Copy Chapter

• 設定 - 透過設定檔而非 CLI 旗標設定選項
• 輸出格式 - XML、Markdown、JSON 和純文字格式詳解
• 程式碼壓縮 - --compress 與 Tree-sitter 的運作原理
• 安全 - --no-security-check 停用的功能

範例 Copy Chapter

# 基本使用
repomix

# 自訂輸出檔案和格式
repomix -o my-output.xml --style xml

# 輸出到標準輸出
repomix --stdout > custom-output.txt

# 輸出到標準輸出，然後管道到另一個命令（例如，simonw/llm）
repomix --stdout | llm "請解釋這段程式碼的作用。"

# 使用壓縮的自訂輸出
repomix --compress

# 使用模式處理特定檔案
repomix --include "src/**/*.ts,*.md" --ignore "*.test.js,docs/**"

# 帶分支的遠端儲存庫
repomix --remote https://github.com/user/repo/tree/main

# 帶提交的遠端儲存庫
repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1

# 使用簡寫的遠端儲存庫
repomix --remote user/repo

# 使用簡寫的遠端儲存庫（自動檢測，無需 --remote）
repomix user/repo

# 使用stdin的檔案清單
find src -name "*.ts" -type f | repomix --stdin
git ls-files "*.js" | repomix --stdin
echo -e "src/index.ts\nsrc/utils.ts" | repomix --stdin

# Git整合
repomix --include-diffs  # 包含git差異用於未提交的變更
repomix --include-logs   # 包含git記錄（預設為最後50次提交）
repomix --include-logs --include-logs-count 10  # 包含最後10次提交
repomix --include-diffs --include-logs  # 同時包含差異和記錄

# 權杖計數分析
repomix --token-count-tree
repomix --token-count-tree 1000  # 僅顯示擁有1000+權杖的檔案/目錄

# 監視模式：檔案變更時自動重新打包
repomix --watch
repomix -w --include "src/**/*.ts"

File: website/client/src/zh-tw/guide/comment-removal.md Copy Chapter

title: 註釋移除 Copy Chapter

註釋移除

Repomix 可以在生成輸出文件時自動移除程式碼中的註釋。這有助於減少干擾，讓程式碼更加簡潔。

使用方法 Copy Chapter

要啟用註釋移除，在 repomix.config.json 中將 removeComments 選項設置為 true：

{
  "output": {
    "removeComments": true
  }
}

支援的語言 Copy Chapter

Repomix 支援移除多種程式設計語言的註釋，包括：

• JavaScript/TypeScript (//, /* */)
• Python (#, """, ''')
• Java (//, /* */)
• C/C++ (//, /* */)
• HTML (``)
• CSS (/* */)
• 以及更多語言...

示例 Copy Chapter

以下是 JavaScript 程式碼示例：

// 這是單行註釋
function test() {
  /* 這是
     多行註釋 */
  return true;
}

啟用註釋移除後，輸出將變為：

function test() {
  return true;
}

注意事項 Copy Chapter

• 註釋移除在其他處理步驟（如行號添加）之前執行
• 某些註釋，例如 JSDoc 註釋，可能會根據語言和上下文保留
• 如果你需要保留某些重要註釋，請考慮使用其他方式記錄這些信息，例如使用自定義指令

建議用法 Copy Chapter

1. 選擇性使用：

• 對於需要向 AI 展示實現細節的程式碼，保留註釋
• 對於主要關注程式碼結構的分析，移除註釋

2. 配合其他功能：

• 與 --remove-empty-lines 選項組合使用，獲得更簡潔的輸出
• 使用自定義指令提供額外的上下文信息

3. 效能考慮：

• 移除註釋可以減少輸出文件大小
• 對於大型程式碼庫特別有用

相關資源 Copy Chapter

• 程式碼壓縮 - 透過提取程式碼結構進一步減少令牌數量
• 設定 - 在設定檔中設定 output.removeComments
• 命令列選項 - 使用 --remove-comments 旗標

File: website/client/src/zh-tw/guide/configuration.md Copy Chapter

title: 設定 Copy Chapter

設定

Repomix可以透過設定檔或命令列選項進行設定。設定檔允許您自訂程式碼庫的處理和輸出方式。

設定檔格式 Copy Chapter

Repomix支援多種設定檔格式，以提供靈活性和易用性。

Repomix將按以下優先順序自動搜尋設定檔：

1. TypeScript (repomix.config.ts, repomix.config.mts, repomix.config.cts)
2. JavaScript/ES Module (repomix.config.js, repomix.config.mjs, repomix.config.cjs)
3. JSON (repomix.config.json5, repomix.config.jsonc, repomix.config.json)

JSON設定 Copy Section

在專案目錄中建立設定檔：

repomix --init

這將建立一個帶有預設設定的repomix.config.json檔案。您還可以建立一個全域設定檔，在找不到本地設定時將使用它作為後備：

repomix --init --global

TypeScript設定 Copy Section

TypeScript設定檔提供最佳的開發體驗，具有完整的型別檢查和IDE支援。

安裝：

要使用帶有defineConfig的TypeScript或JavaScript設定，您需要將Repomix安裝為開發依賴：

npm install -D repomix

範例：

// repomix.config.ts
import { defineConfig } from 'repomix';

export default defineConfig({
  output: {
    filePath: 'output.xml',
    style: 'xml',
    removeComments: true,
  },
  ignore: {
    customPatterns: ['**/node_modules/**', '**/dist/**'],
  },
});

優勢：

• ✅ IDE中的完整TypeScript型別檢查
• ✅ 出色的IDE自動完成和IntelliSense
• ✅ 使用動態值（時間戳記、環境變數等）

動態值範例：

// repomix.config.ts
import { defineConfig } from 'repomix';

// 產生基於時間戳記的檔案名稱
const timestamp = new Date().toISOString().slice(0, 19).replace(/[:.]/g, '-');

export default defineConfig({
  output: {
    filePath: `output-${timestamp}.xml`,
    style: 'xml',
  },
});

JavaScript設定 Copy Section

JavaScript設定檔的工作方式與TypeScript相同，支援defineConfig和動態值。

設定選項 Copy Chapter

設定檔支援JSON5語法，允許：

• 註解（單行和多行）
• 物件和陣列中的尾隨逗號
• 無引號屬性名
• 更靈活的字串語法

模式验证 Copy Chapter

您可以透過添加$schema屬性為設定檔啟用模式验证：

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "output": {
    "filePath": "repomix-output.md",
    "style": "markdown"
  }
}

這在支援JSON結構描述的編輯器中提供自動完成和驗證功能。

設定檔範例 Copy Chapter

以下是完整設定檔（repomix.config.json）的範例：

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "input": {
    "maxFileSize": 50000000,
    // "processors": [
    //   { "pattern": "**/*.json", "command": "npx @toon-format/cli {file}" }
    // ]
  },
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml",
    "filePathStyle": "target-relative",
    "parsableStyle": false,
    "compress": false,
    "headerText": "打包檔案的自訂頭部資訊",
    "fileSummary": true,
    "directoryStructure": true,
    "files": true,
    "removeComments": false,
    "removeEmptyLines": false,
    "topFilesLength": 5,
    "showLineNumbers": false,
    // "patterns": [
    //   { "pattern": "docs/**/*", "compress": true },
    //   { "pattern": "website/**/*", "directoryStructureOnly": true }
    // ],
    "truncateBase64": false,
    "copyToClipboard": false,
    "includeEmptyDirectories": false,
    "git": {
      "sortByChanges": true,
      "sortByChangesMaxCommits": 100,
      "includeDiffs": false,
      "includeLogs": false,
      "includeLogsCount": 50
    }
  },
  "include": ["**/*"],
  "ignore": {
    "useGitignore": true,
    "useDefaultPatterns": true,
    // 模式也可以在 .repomixignore 中指定
    "customPatterns": [
      "additional-folder",
      "**/*.log"
    ],
  },
  "security": {
    "enableSecurityCheck": true
  },
  "tokenCount": {
    "encoding": "o200k_base"
  }
}

設定檔位置 Copy Chapter

Repomix按以下順序尋找設定檔：

1. 當前目錄中的本地設定檔（優先順序：TS > JS > JSON）
   • TypeScript: repomix.config.ts, repomix.config.mts, repomix.config.cts
   • JavaScript: repomix.config.js, repomix.config.mjs, repomix.config.cjs
   • JSON: repomix.config.json5, repomix.config.jsonc, repomix.config.json
2. 全域設定檔（優先順序：TS > JS > JSON）
   • Windows：
     • TypeScript: %LOCALAPPDATA%\Repomix\repomix.config.ts, .mts, .cts
     • JavaScript: %LOCALAPPDATA%\Repomix\repomix.config.js, .mjs, .cjs
     • JSON: %LOCALAPPDATA%\Repomix\repomix.config.json5, .jsonc, .json
   • macOS/Linux：
     • TypeScript: ~/.config/repomix/repomix.config.ts, .mts, .cts
     • JavaScript: ~/.config/repomix/repomix.config.js, .mjs, .cjs
     • JSON: ~/.config/repomix/repomix.config.json5, .jsonc, .json

命令列選項優先於設定檔設定。

包含模式 Copy Chapter

Repomix支援使用glob模式指定要包含的檔案。這允許更靈活和強大的檔案選擇：

• 使用**/*.js包含任何目錄中的所有JavaScript檔案
• 使用src/**/*包含src目錄及其子目錄中的所有檔案
• 組合多個模式，如["src/**/*.js", "**/*.md"]以包含src中的JavaScript檔案和所有Markdown檔案

您可以在設定檔中指定包含模式：

{
  "include": ["src/**/*", "tests/**/*.test.js"]
}

或使用--include命令列選項進行一次性過濾。

忽略模式 Copy Chapter

Repomix提供多種方法來設定忽略模式，以在打包過程中排除特定檔案或目錄：

• .gitignore：預設情況下，使用專案的.gitignore檔案和.git/info/exclude中列出的模式。此行為可以透過ignore.useGitignore設定或--no-gitignore CLI選項控制。
• .ignore：您可以在專案根目錄中使用.ignore檔案，格式與.gitignore相同。ripgrep和the silver searcher等工具也會使用此檔案，減少維護多個忽略檔案的需求。此行為可以透過ignore.useDotIgnore設定或--no-dot-ignore CLI選項控制。
• 預設模式：Repomix包含常見排除檔案和目錄的預設清單（例如node_modules、.git、二進制檔案）。此功能可以透過ignore.useDefaultPatterns設定或--no-default-patterns CLI選項控制。有關詳細資訊，請參閱defaultIgnore.ts。
• .repomixignore：您可以在專案根目錄中建立.repomixignore檔案來定義Repomix特定的忽略模式。此檔案遵循與.gitignore相同的格式。
• 自訂模式：可以使用設定檔中的ignore.customPatterns選項指定其他忽略模式。您可以使用-i, --ignore命令列選項覆寫此設定。

優先順序（從高到低）：

1. 自訂模式（ignore.customPatterns）
2. 忽略檔案（.repomixignore、.ignore、.gitignore和.git/info/exclude）：
   • 在巢狀目錄中時，更深層目錄中的檔案具有更高優先順序
   • 在同一目錄中時，這些檔案以不特定的順序合併
3. 預設模式（如果ignore.useDefaultPatterns為true且未使用--no-default-patterns）

這種方法允許根據專案需求靈活設定檔案排除。它透過確保排除安全敏感檔案和大型二進制檔案來幫助優化產生的打包檔案的大小，同時防止機密資訊外洩。

**注意：**預設情況下，二進制檔案不包含在打包輸出中，但它們的路徑列在輸出檔案的「倉庫結構」部分。這提供了倉庫結構的完整概覽，同時保持打包檔案高效且基於文字。有關詳細資訊，請參閱二進制檔案處理。

.repomixignore範例：

# 快取目錄
.cache/
tmp/

# 建置輸出
dist/
build/

# 日誌
*.log

預設忽略模式 Copy Chapter

當ignore.useDefaultPatterns為true時，Repomix自動忽略以下常見模式：

node_modules/**
.git/**
coverage/**
dist/**

完整列表請參見defaultIgnore.ts

二進制檔案處理 Copy Chapter

二進制檔案（如圖像、PDF、編譯的二進制檔案、歸檔檔案等）經過特殊處理以保持高效的基於文字的輸出：

• 檔案內容：二進制檔案不包含在打包輸出中，以保持檔案基於文字且對AI處理高效
• 目錄結構：二進制檔案路徑被列出在目錄結構部分，提供倉庫的完整概覽

這種方法確保您獲得倉庫結構的完整視圖，同時保持針對AI消費優化的高效的基於文字的輸出。

範例：

如果您的倉庫包含logo.png和app.jar：

• 它們將出現在目錄結構部分
• 它們的內容將不會包含在檔案部分

目錄結構輸出：

src/
  index.ts
  utils.ts
assets/
  logo.png
build/
  app.jar

這樣，AI工具可以理解這些二進制檔案存在於您的專案結構中，而無需處理其二進制內容。

**注意：**您可以使用input.maxFileSize設定選項（預設值：50MB）控制最大檔案大小閾值。大於此限制的檔案將被完全跳過。

進階功能 Copy Chapter

程式碼壓縮 Copy Section

程式碼壓縮功能（透過output.compress: true啟用）使用Tree-sitter智慧提取基本程式碼結構，同時移除實作細節。這有助於在保持重要的結構資訊的同時減少令牌數量。

主要優點：

• 顯著減少令牌數量
• 保留類別和函式簽名
• 保持匯入和匯出
• 保留型別定義和介面
• 移除函式本體和實作細節

更多詳細資訊和範例，請參閱程式碼壓縮指南。

每個檔案的包含層級 Copy Section

output.compress 會對每個檔案套用單一層級，而 output.patterns 則讓您可以從設定檔中依 glob 控制細節層級。每個項目透過 glob 鎖定檔案（比對方式與 include/ignore 相同），並針對符合的檔案覆寫全域 output.compress 設定。

{
  "output": {
    "compress": false, // 全域預設值作為萬用後備
    "patterns": [
      { "pattern": "docs/**/*", "compress": true },
      { "pattern": "website/**/*", "directoryStructureOnly": true }
    ]
  }
}

每個檔案會解析為以下三種層級之一：

• 完整內容（預設）：包含檔案的完整內容。
• 壓縮（compress: true）：內容會通過與 output.compress 相同的 Tree-sitter 處理流程。
• 僅目錄結構（directoryStructureOnly: true）：檔案會列在目錄結構中，但其內容區塊會完全從輸出中省略。

規則如下：

• 模式會依陣列順序評估，對於指定的檔案，第一個符合的模式優先。
• 符合的模式的旗標會覆寫全域 output.compress 設定。若模式符合但未設定任何旗標，則會強制該檔案使用完整內容，這對於將檔案從全域 compress 中加入白名單很方便。
• 當同一個模式同時設定 directoryStructureOnly 與 compress 時，directoryStructureOnly 優先。
• 若沒有任何模式符合，則套用全域行為（完整內容，或當 output.compress 為 true 時為壓縮）。

此選項僅限設定檔使用；沒有對應的 CLI 旗標。

檔案處理器 Copy Section

input.processors 會執行外部命令，在檔案內容被打包之前進行轉換。每個項目透過 glob 鎖定檔案（比對方式與 include/ignore 相同），並以該命令的標準輸出取代符合檔案的內容。這對於縮減令牌數量或轉換格式的處理很有用，例如將 JSON 轉換為 TOON、壓縮 SVG，或將 notebook 轉換為純腳本。

{
  "input": {
    "processors": [
      {
        "pattern": "**/*.json",
        "command": "npx @toon-format/cli {file}"
      }
    ]
  }
}

運作方式：

• Repomix 會將每個符合的檔案內容寫入暫存檔案，並以其路徑取代命令中的 {file} 佔位符（此佔位符為必要）。
• 此命令會透過 shell 執行，因此管線與 npx 等工具都能運作。其標準輸出會成為該檔案的新內容，接著會像其他檔案一樣流經管線的其餘部分（安全檢查、令牌計數與輸出產生）。
• 模式會依陣列順序評估，第一個符合的模式優先——一個檔案最多只會被一個處理器轉換（不會串聯處理）。

各處理器的選項：

• timeout：等待命令執行的最長時間（毫秒）。預設值：60000（60 秒）。請注意，npx 在快取為空時可能需要額外時間下載套件。
• onError：命令以非零狀態退出或逾時時的處理方式。"fail"（預設）會中止整個打包過程；"skip" 會記錄警告並回退使用該檔案的原始內容。

範例命令（每個都是與合適的 pattern 搭配的 command 值）：

由於第一個符合的模式優先，因此每個檔案只套用一個處理器——例如，對於 **/*.json 只選擇 jq 或 TOON 轉換器其中之一。命令必須將轉換後的內容寫入標準輸出，而且它呼叫的工具必須在你的 PATH 上可用（基於 npx 的命令會在首次使用時下載工具）。

::: warning 安全性
檔案處理器會執行來自您設定檔的任意命令，因此遵循嚴格的信任模型：

• 僅在本地 CLI 執行時啟用 —— Repomix 會假設您工作目錄中的設定檔屬於您自己，這與 npm 腳本或 Makefile 的信任邊界相同。同樣地，如果您在他人提供的儲存庫中執行 repomix，卻事先未檢查其 repomix.config.json，其處理器命令就會在您的機器上執行。在打包不受信任的儲存庫之前，請先檢查其設定檔。
• 在函式庫 API（pack() / runCli()）、MCP 伺服器，以及託管的 repomix.com 中皆為停用狀態，因此這些管道都無法從設定檔執行命令。
• 對於遠端儲存庫（--remote），複製儲存庫的設定 —— 以及其處理器 —— 只有在您明確傳入 --remote-trust-config 時才會被信任。若未傳入，遠端設定甚至不會被載入。

啟動時會記錄目前啟用的處理器，讓來自不熟悉設定檔的意外處理器變得可見。由於命令會在啟動時與錯誤訊息中被印出，請透過環境變數（例如 $TOKEN）參照憑證，而非直接寫在命令中，因為環境變數在記錄時不會被展開。
:::

注意事項：

• 不建議在同一個檔案上同時使用會改變格式的處理器與 output.compress、output.removeComments 或 output.patterns 的 compress：這些步驟是依檔案的原始副檔名來分派的，因此會對轉換後的內容執行錯誤的語言處理器。基於同樣的原因，Markdown 輸出中的程式碼區塊也會依原始副檔名標記（例如，JSON→TOON 轉換後的檔案會標記為 json）。壓縮是盡力而為，解析失敗時會靜默回退為轉換後的內容。
• 使用 --watch 時，符合的檔案會在每次重新建置時重新處理，也就是每次都會重新執行該命令。
• 逾時時，Repomix 會終止該命令所在的 shell；若命令自行產生了長期執行的背景程序，這些程序可能會繼續執行。
• 處理器只會看到文字檔案（二進位檔案會在處理前被排除），其輸出會以 UTF-8 讀取。

Git整合 Copy Section

output.git設定提供強大的Git感知功能：

• sortByChanges：當設定為true時，檔案按Git更改次數（修改該檔案的提交數）排序。更改次數較多的檔案出現在輸出的底部。這有助於優先處理更活躍開發的檔案。預設值：true
• sortByChangesMaxCommits：計算檔案更改次數時要分析的最大提交數。預設值：100
• includeDiffs：當設定為true時，在輸出中包含Git差異（同時分別包含工作樹和暫存區的更改）。這允許讀者查看儲存庫中的待處理更改。預設值：false
• includeLogs：當設定為true時，在輸出中包含Git記錄。顯示提交歷史包括日期、訊息和檔案路徑。這有助於AI理解開發模式和檔案關係。預設值：false
• includeLogsCount：在git記錄中包含的最近提交數量。預設值：50

設定範例：

{
  "output": {
    "git": {
      "sortByChanges": true,
      "sortByChangesMaxCommits": 100,
      "includeDiffs": true,
      "includeLogs": true,
      "includeLogsCount": 25
    }
  }
}

安全檢查 Copy Section

當security.enableSecurityCheck啟用時，Repomix使用Secretlint在將程式碼庫包含在輸出中之前檢測敏感資訊。這有助於防止意外暴露：

• API金鑰
• 存取令牌
• 私密金鑰
• 密碼
• 其他敏感憑證

註解移除 Copy Section

當output.removeComments設定為true時，將從支援的檔案類型中移除註解，以減少輸出大小並專注於核心程式碼內容。這在以下情況特別有用：

• 處理大量文件化的程式碼
• 嘗試減少令牌數量
• 專注於程式碼結構和邏輯

有關支援的語言和詳細範例，請參閱註解移除指南。

相關資源 Copy Chapter

• 命令列選項 - 完整的 CLI 參考（CLI 選項優先於設定檔設定）
• 輸出格式 - 各種輸出格式的詳細說明
• 安全 - Repomix 如何偵測敏感資訊
• 程式碼壓縮 - 透過 Tree-sitter 減少令牌數量
• GitHub 倉庫處理 - 遠端倉庫處理選項