Configuration

Repomix can be configured using a configuration file or command-line options. The configuration file allows you to customize various aspects of how Repomix processes and outputs your codebase.

Configuration File Formats

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

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

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

JSON Configuration

Create a configuration file in your project directory:

bash

repomix --init

This will create a repomix.config.json file with default settings. You can also create a global configuration file that will be used as a fallback when no local configuration is found:

bash

repomix --init --global

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:

bash

npm install -D repomix

Example:

typescript

// 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:

typescript

// 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

Option	Description	Default
`input.maxFileSize`	Maximum file size in bytes to process. Files larger than this will be skipped. Useful for excluding large binary files or data files	`50000000`
`input.processors`	Ordered array of `{ pattern, command, timeout?, onError? }` entries that run an external command to transform matching files before packing (e.g. JSON→TOON). The first matching glob wins. Runs arbitrary commands, so it runs only for local CLI runs (and remote repositories with `--remote-trust-config`). See File Processors	Not set
`output.filePath`	The name of the output file. Supports XML, Markdown, and plain text formats	`"repomix-output.xml"`
`output.style`	The style of the output (`xml`, `markdown`, `json`, `plain`). Each format has its own advantages for different AI tools	`"xml"`
`output.filePathStyle`	How file paths are shown in output (`target-relative` keeps paths relative to each target root, `cwd-relative` keeps paths relative to the current working directory)	`"target-relative"`
`output.parsableStyle`	Whether to escape the output based on the chosen style schema. Enables better parsing but may increase token count	`false`
`output.compress`	Whether to perform intelligent code extraction using Tree-sitter to reduce token count while preserving structure	`false`
`output.patterns`	Per-file inclusion levels. An ordered array of `{ pattern, compress?, directoryStructureOnly? }` entries; the first matching glob wins and overrides the global `output.compress` for that file. See Per-file Inclusion Levels	Not set
`output.headerText`	Custom text to include in the file header. Useful for providing context or instructions for AI tools	`null`
`output.instructionFilePath`	Path to a file containing detailed custom instructions for AI processing	`null`
`output.fileSummary`	Whether to include a summary section at the beginning showing file counts, sizes, and other metrics	`true`
`output.directoryStructure`	Whether to include the directory structure in the output. Helps AI understand the project organization	`true`
`output.files`	Whether to include file contents in the output. Set to false to only include structure and metadata	`true`
`output.removeComments`	Whether to remove comments from supported file types. Can reduce noise and token count	`false`
`output.removeEmptyLines`	Whether to remove empty lines from the output to reduce token count	`false`
`output.showLineNumbers`	Whether to add line numbers to each line. Helpful for referencing specific parts of code	`false`
`output.truncateBase64`	Whether to truncate long base64 data strings (e.g., images) to reduce token count	`false`
`output.copyToClipboard`	Whether to copy the output to system clipboard in addition to saving the file	`false`
`output.splitOutput`	Split output into multiple numbered files by maximum size per part (e.g., `1000000` for ~1MB). CLI accepts human-readable sizes like `500kb` or `2mb`. Keeps each file under the limit and avoids splitting files across parts	Not set
`output.tokenBudget`	Fail with a non-zero exit code when the packed output exceeds this many tokens. Acts as a guard for CI/agent context limits; the output is still generated	Not set
`output.topFilesLength`	Number of top files to display in the summary. If set to 0, no summary will be displayed	`5`
`output.includeEmptyDirectories`	Whether to include empty directories in the repository structure	`false`
`output.includeFullDirectoryStructure`	When using `include` patterns, whether to display the complete directory tree (respecting ignore patterns) while still processing only the included files. Provides full repository context for AI analysis	`false`
`output.git.sortByChanges`	Whether to sort files by git change count. Files with more changes appear at the bottom	`true`
`output.git.sortByChangesMaxCommits`	Maximum number of commits to analyze for git changes. Limits the history depth for performance	`100`
`output.git.includeDiffs`	Whether to include git diffs in the output. Shows both work tree and staged changes separately	`false`
`output.git.includeLogs`	Whether to include git logs in the output. Shows commit history with dates, messages, and file paths	`false`
`output.git.includeLogsCount`	Number of git log commits to include in the output	`50`
`include`	Patterns of files to include using glob patterns	`[]`
`ignore.useGitignore`	Whether to use patterns from the project's `.gitignore` file	`true`
`ignore.useDotIgnore`	Whether to use patterns from the project's `.ignore` file	`true`
`ignore.useDefaultPatterns`	Whether to use default ignore patterns (node_modules, .git, etc.)	`true`
`ignore.customPatterns`	Additional patterns to ignore using glob patterns	`[]`
`security.enableSecurityCheck`	Whether to perform security checks using Secretlint to detect sensitive information	`true`
`tokenCount.encoding`	Token count encoding for OpenAI-compatible tokenization (e.g., `o200k_base` for GPT-4o, `cl100k_base` for GPT-4/3.5). Powered by gpt-tokenizer.	`"o200k_base"`

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

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

json

{
  "$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 File

Here's an example of a complete configuration file (repomix.config.json):

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": "Custom header information for the packed file.",
    "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,
    // Patterns can also be specified in .repomixignore
    "customPatterns": [
      "additional-folder",
      "**/*.log"
    ],
  },
  "security": {
    "enableSecurityCheck": true
  },
  "tokenCount": {
    "encoding": "o200k_base"
  }
}

Configuration File Locations

Repomix looks for configuration files in the following order:

Local configuration file in the current directory (priority order: 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
Global configuration file (priority order: 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

Command-line options take precedence over configuration file settings.

Include Patterns

Repomix 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

You can specify include patterns in your configuration file:

json

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

Or use the --include command-line option for one-time filtering.

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

Custom patterns (ignore.customPatterns)
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
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. See Binary Files Handling for more details.

Example of .repomixignore:

text

# Cache directories
.cache/
tmp/

# Build outputs
dist/
build/

# Logs
*.log

Default Ignore Patterns

When ignore.useDefaultPatterns is true, Repomix automatically ignores common patterns:

text

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

For the complete list, see defaultIgnore.ts

Binary Files Handling

Binary files (such as images, PDFs, compiled binaries, archives, etc.) are handled specially to maintain an efficient, text-based output:

File Contents: Binary files are not included in the packed output to keep the file text-based and efficient for AI processing
Directory Structure: Binary file paths are listed in the directory structure section, providing a complete overview of your repository

This approach ensures you get a complete view of your repository structure while maintaining an efficient, text-based output optimized for AI consumption.

Example:

If your repository contains logo.png and app.jar:

They will appear in the Directory Structure section
Their contents will not be included in the Files section

Directory Structure Output:

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

This way, AI tools can understand that these binary files exist in your project structure without processing their binary contents.

Note: You can control the maximum file size threshold using the input.maxFileSize configuration option (default: 50MB). Files larger than this limit will be skipped entirely.

Advanced Features

Code Compression

The code compression feature, enabled with output.compress: true, uses Tree-sitter to intelligently extract essential code structures while removing implementation details. This helps reduce token count while maintaining important structural information.

Key benefits:

Reduces token count significantly
Preserves class and function signatures
Maintains imports and exports
Keeps type definitions and interfaces
Removes function bodies and implementation details

For more details and examples, see the Code Compression Guide.

Per-file Inclusion Levels

While output.compress applies a single level to every file, output.patterns lets you control the detail level per glob from your configuration file. Each entry targets files by glob (matched the same way as include/ignore) and overrides the global output.compress setting for matching files.

json5

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

Each file resolves to one of 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 output.compress.
Directory-structure-only (directoryStructureOnly: true): the file is listed in the directory structure, but its content block is omitted from the output entirely.

The rules:

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 a flag forces full content for that file, which is handy for whitelisting files out of a global compress.
directoryStructureOnly takes precedence over compress when both are set on the same pattern.
If no pattern matches, the global behavior applies (full content, or compressed when output.compress is true).

This option is config-file only; there is no equivalent CLI flag.

File Processors

input.processors runs an external command to transform a file's content before it is packed. Each entry targets files by glob (matched the same way as include/ignore) and replaces the matching files' content with the command's standard output. This is useful for token-reducing or format-converting transforms, for example converting JSON to TOON, minifying SVGs, or converting notebooks to plain scripts.

json5

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

How it works:

Repomix writes each matching file's content to a temporary file and substitutes its path for the {file} placeholder in the command (the placeholder is required).
The command runs through the shell, so pipes and tools like npx work. Its standard output becomes the file's new content, which then flows through the rest of the pipeline (security check, token counting, and output generation) like any other file.
Patterns are evaluated in array order and the first matching pattern wins — a file is transformed by at most one processor (no chaining).

Per-processor options:

timeout: Maximum time in milliseconds to wait for the command. Default: 60000 (60s). Note that npx may need extra time to download a package on a cold cache.
onError: What to do when the command exits with a non-zero status or times out. "fail" (default) aborts the whole pack; "skip" logs a warning and falls back to the file's original content.

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

Pattern	`command`	What it does
`*/.json`	`jq -c . {file}`	Compact JSON by stripping whitespace
`*/.json`	`npx @toon-format/cli {file}`	Convert JSON to TOON, a compact token-efficient format
`*/.svg`	`npx svgo -i {file} -o -`	Minify SVG
`*/.ipynb`	`jupyter nbconvert --to script --stdout {file}`	Convert a Jupyter notebook to a plain Python script

Since the first matching pattern wins, apply only one processor per file — for example pick either jq or the TOON converter for **/*.json. The command must write the transformed content to standard output, and the tool it invokes must be available on your PATH (npx-based commands download the tool on first use).

Security

File processors run arbitrary commands from your configuration file, so they follow a strict trust model:

They run 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.
They are disabled for the library API (pack() / runCli()), the MCP server, and the hosted repomix.com, so none of these can run commands from a config.
For remote repositories (--remote), the cloned repository's config — and therefore its processors — is trusted only when you explicitly pass --remote-trust-config. Without it the remote config is not even loaded.

Active processors are logged at startup so unexpected processors from an unfamiliar config are visible. Because the command is printed at startup and in error messages, reference credentials via environment variables (e.g. $TOKEN), which are logged unexpanded, rather than inlining them in the command.

Notes:

Combining a format-changing processor with output.compress, output.removeComments, or an output.patterns compress on the same file is not recommended: those steps dispatch by the file's original extension, so they would run the wrong language handler on the transformed content. For the same reason, Markdown output labels the code fence by the original extension (e.g. a JSON→TOON file is fenced as json). Compression is best-effort and quietly falls back to the transformed content on a parse failure.
With --watch, matching files are re-processed on every rebuild, which re-runs the command each time.
On timeout, Repomix kills the command's shell; a command that spawns its own long-lived background processes may leave them running.
Processors only see text files (binary files are excluded before processing), and their output is read as UTF-8.

Git Integration

The output.git configuration provides powerful Git-aware features:

sortByChanges: When true, files are sorted by the number of Git changes (commits that modified the file). Files with more changes appear at the bottom of the output. This helps prioritize more actively developed files. Default: true
sortByChangesMaxCommits: The maximum number of commits to analyze when counting file changes. Default: 100
includeDiffs: When true, includes Git differences in the output (includes both work tree and staged changes separately). This allows the reader to see pending changes in the repository. Default: false
includeLogs: When true, includes Git commit history in the output. Shows commit dates, messages, and file paths for each commit. This helps AI understand development patterns and file relationships. Default: false
includeLogsCount: The number of recent commits to include in the git logs. Default: 50

Example configuration:

json

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

Security Checks

When security.enableSecurityCheck is enabled, Repomix uses Secretlint to detect sensitive information in your codebase before including it in the output. This helps prevent accidental exposure of:

API keys
Access tokens
Private keys
Passwords
Other sensitive credentials

Comment Removal

When output.removeComments is set to true, comments are removed from supported file types to reduce output size and focus on essential code content. This can be particularly useful when:

Working with heavily documented code
Trying to reduce token count
Focusing on code structure and logic

For supported languages and detailed examples, see the Comment Removal Guide.

Command Line Options - Full CLI reference (CLI options override config file settings)
Output Formats - Details on each output format
Security - How Repomix detects sensitive information
Code Compression - Reduce token count with Tree-sitter
GitHub Repository Processing - Options for remote repos

Configuration ​

Configuration File Formats ​

JSON Configuration ​

TypeScript Configuration ​

JavaScript Configuration ​

Configuration Options ​

Schema Validation ​

Example Configuration File ​

Configuration File Locations ​

Include Patterns ​

Ignore Patterns ​

Default Ignore Patterns ​

Binary Files Handling ​

Advanced Features ​

Code Compression ​

Per-file Inclusion Levels ​

File Processors ​

Git Integration ​

Security Checks ​

Comment Removal ​

Related Resources ​

Configuration

Configuration File Formats

JSON Configuration

TypeScript Configuration

JavaScript Configuration

Configuration Options

Schema Validation

Example Configuration File

Configuration File Locations

Include Patterns

Ignore Patterns

Default Ignore Patterns

Binary Files Handling

Advanced Features

Code Compression

Per-file Inclusion Levels

File Processors

Git Integration

Security Checks

Comment Removal

Related Resources