How to Increase the Token Budget for OpenClaude Repo Map: 3 Configuration Methods

You can increase the OpenClaude repo map token budget using the --repo-map-token-budget CLI flag, the REPO_MAP_TOKEN_BUDGET environment variable, or by setting repoMap.tokenBudget in your .openclaude/config.json configuration file.

The repo map feature in OpenClaude constructs a ranked summary of your project's most important files and injects it into the model's context at the start of each session. By default, this summary is limited to approximately 2,000 tokens to keep session payloads small, but you can increase this budget to give the model a richer view of your codebase. This article explains the three methods to raise the token limit based on the Gitlawb/openclaude source code.

Understanding the Repo Map Token Budget

The token budget determines how many files and method signatures the repo map can include before truncation occurs. In src/context/repoMap/renderer.ts, the renderRepoMap function repeatedly adds ranked files to the map until currentTokens + nextFileTokens > tokenBudget, at which point it stops. The tokenBudget value used in this comparison is sourced from the RepoMapRenderOptions interface defined in src/context/repoMap/types.ts. Raising this value allows the renderer to include more files and longer signatures in the initial context.

Three Methods to Increase the Token Budget

CLI Flag (Temporary Override)

For a one-time increase, pass the token budget directly via the command line. This flag is parsed in src/commands/repomap/repomap.ts and applied only to the current invocation.

# Increase the repo map token budget to 8,000 tokens for this run only

openclaude --repo-map-token-budget 8000

This approach is ideal for testing different budget sizes without modifying persistent configuration files.

Environment Variable (Global Persistent)

To apply a custom budget across all sessions, set the REPO_MAP_TOKEN_BUDGET environment variable. The value is processed at startup by the configuration loader in src/utils/config.ts and stored in the global config.

# Bash/Zsh: Set and export the variable

export REPO_MAP_TOKEN_BUDGET=8000

# Subsequent OpenClaude invocations will use the 8,000-token budget

openclaude

This method affects all OpenClaude sessions in the current shell environment until the variable is unset.

Configuration File (Project-Level Persistent)

For project-specific settings that persist across reboots, add the token budget to your OpenClaude configuration file. The renderer in src/context/repoMap/renderer.ts consumes this value when constructing the map.

Create or edit ~/.openclaude/config.json:

{
  "repoMap": {
    "tokenBudget": 8000
  }
}

After saving the file, any new OpenClaude session automatically uses the specified 8,000-token limit.

How the Token Budget is Applied in the Source Code

When you invoke /repomap or start a new session, the renderRepoMap function in src/context/repoMap/renderer.ts executes the budget enforcement logic. It iterates through ranked files, calculating token counts using currentTokens + nextFileTokens, and stops inclusion when the sum would exceed the tokenBudget parameter. The interface RepoMapRenderOptions in src/context/repoMap/types.ts defines the tokenBudget field as a number, ensuring type safety when the configuration is passed from src/commands/repomap/repomap.ts or loaded from src/utils/config.ts.

Summary

• The default repo map token budget is approximately 2,000 tokens to minimize context window usage.
• You can override this via three methods: the --repo-map-token-budget CLI flag, the REPO_MAP_TOKEN_BUDGET environment variable, or the repoMap.tokenBudget JSON configuration key.
• The enforcement logic resides in the renderRepoMap function within src/context/repoMap/renderer.ts, which truncates content when the token limit is reached.
• All configuration methods ultimately populate the tokenBudget field in the RepoMapRenderOptions interface defined in src/context/repoMap/types.ts.

Frequently Asked Questions

What is the default token budget for OpenClaude repo map?

The default token budget is approximately 2,000 tokens. This conservative limit keeps session payloads small and ensures compatibility with models that have restricted context windows, while still providing a ranked summary of the most important files in your repository.

Which source file enforces the token limit when generating the repo map?

The renderRepoMap function in src/context/repoMap/renderer.ts enforces the limit. It iteratively adds files to the map and checks if currentTokens + nextFileTokens > tokenBudget before including each subsequent file, stopping immediately when the budget would be exceeded.

Can I use different token budgets for different projects?

Yes. While the environment variable REPO_MAP_TOKEN_BUDGET and global config file ~/.openclaude/config.json apply universally, you can create project-specific configurations by placing a .openclaude/config.json file in individual project directories. The configuration loader merges these values, allowing per-project repo map budgets.

Does increasing the token budget affect API costs?

Yes. Since the repo map is injected into every session's context, increasing the token budget sends more tokens to the language model with each request. This increases both the input token count and associated API costs proportionally to the size of the expanded repository map.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}