How to Enable Auto-Injection of the Repo Map in OpenClaude: 3 Configuration Methods

Add "repoMap": true to your ~/.openclaude.json configuration file, pass the --repo-map CLI flag, or set the OPENCLAUDE_REPO_MAP=1 environment variable to automatically build and inject the repository map into every session's system context.

OpenClaude uses a repo map—a token-budgeted, PageRank-weighted representation of your codebase—to give the model instant awareness of file structures and relationships. When you enable auto-injection via the repoMap flag, the map is built at startup by buildRepoMap in src/context/repoMap/renderer.ts and embedded directly into the system context under the key repoMap (as defined in src/context.ts), eliminating the need to manually trigger the /repomap command.

What Is the Repo Map and Why Auto-Inject It?

The repo map is a compressed summary of your repository that includes filenames, tags, and a PageRank-style relevance score for each file. It is constructed by crawling the git file tree in src/context/repoMap/gitFiles.ts and ranking components using a token-budgeted algorithm in src/context/repoMap/renderer.ts.

Without auto-injection, you must manually request the map during each session. By enabling the flag, the map is automatically attached to the systemContext object that is supplied to every Session instance in src/assistant/sessionHistory.ts. This allows the model to reference files, imports, and dependencies immediately without explicit commands.

Configuration Methods to Enable Auto-Injection

You can enable auto-injection of the repo map through three complementary interfaces. All methods reference the same settings schema defined in src/utils/settings/settings.ts.

1. JSON Configuration File (Persistent)

The recommended approach for daily usage is editing the global configuration file.

1. Open or create ~/.openclaude.json (or the file pointed to by OPENCLAUDE_CONFIG_DIR):

nano ~/.openclaude.json

2. Add the repoMap key with a boolean or string value:

{
  "repoMap": true
}

Set "repoMap": "auto" to allow OpenClaude to decide whether to inject the map based on the current token budget constraints.

3. Save the file. On the next startup, src/context.ts reads this value into the has_repo_map property and merges the repoMap object into the system context.

2. CLI Flag (Per-Session Override)

For one-off invocations where you need the map without changing global settings, use the commander-based CLI entrypoint in src/entrypoints/cli.ts:

openclaude --repo-map chat "Explain the dependencies in src/utils/git.ts"

To explicitly disable the map for a single run:

openclaude --no-repo-map chat "General programming question"

3. Environment Variable (CI/CD and Scripts)

In automated environments or shell scripts, export OPENCLAUDE_REPO_MAP before invoking the CLI. The startup environment builder in src/utils/subprocessEnv.ts injects this variable, which src/context.ts checks during context construction.

export OPENCLAUDE_REPO_MAP=1
openclaude chat "What files import the Tree-sitter parser?"

Use OPENCLAUDE_REPO_MAP=auto for budget-aware injection in CI pipelines.

How Auto-Injection Works Under the Hood

Understanding the implementation helps debug injection failures. The process involves three distinct phases:

1. Map Construction – When the flag is enabled, buildRepoMap (in src/context/repoMap/renderer.ts) executes a PageRank algorithm over the file graph produced by src/context/repoMap/gitFiles.ts. The output is a RepoMapResult object (defined in src/context/repoMap/types.ts) containing the compressed file tree.

2. Context Assembly – In src/context.ts, the system gathers context:

const [gitStatus, repoMap] = await Promise.all([ … ]);
const systemContext = {
    …,
    has_repo_map: repoMap !== null,
    ...(repoMap && { repoMap })
};

The spread operator conditionally inserts the repoMap key only when the flag is truthy and the build succeeds.

3. Session Injection – The assembled systemContext is passed to every new Session instance. Because the map resides in the system prompt, the model can reference RepoMapTool (exposed via src/tools/RepoMapTool/RepoMapTool.ts) and answer questions about file relationships without explicit /repomap calls.

Practical Configuration Examples

Enable Globally via Config

// ~/.openclaude.json
{
  "repoMap": true,
  "smartRouting": "auto",
  "autoUpdates": false
}

Now any chat automatically includes the map:

openclaude chat "Which file contains the authentication logic?"

One-Off Repository Analysis

openclaude --repo-map chat "Show me the PageRank-ranked list of TypeScript files"

CI Pipeline Integration

#!/usr/bin/env bash
set -e
export OPENCLAUDE_REPO_MAP=auto
openclaude review --pr=123

Troubleshooting Auto-Injection Failures

If the model does not recognize repository files during sessions, verify the flag state:

• Symptom: The model responds with "I don't have access to repository files."

  • Cause: The repoMap flag is unset or falsy.
  • Fix: Check ~/.openclaude.json for the repoMap key, or verify OPENCLAUDE_REPO_MAP is exported in your shell.

• Symptom: Slow startup or RepoMapResult errors.

  • Cause: Missing Tree-sitter parsers or graph library dependencies.
  • Fix: Run bun install to ensure tree-sitter is compiled and verify externals.ts includes the repo-map graph algorithm dependencies.

• Symptom: Map missing in Docker or CI environments.

  • Cause: Environment variable not propagated to the subprocess.
  • Fix: Explicitly pass OPENCLAUDE_REPO_MAP=1 in your container environment block.

Summary

• Set "repoMap": true in ~/.openclaude.json for persistent auto-injection.
• Use --repo-map for temporary per-session enablement.
• Export OPENCLAUDE_REPO_MAP=1 for shell scripts and CI/CD pipelines.
• The map is built by src/context/repoMap/renderer.ts and injected via src/context.ts into every session's system context.
• When enabled, the model gains immediate access to RepoMapTool without manual /repomap commands.

Frequently Asked Questions

What values does the repoMap setting accept?

The setting accepts true (always inject), false (never inject), or "auto" (inject only when the token budget allows). These values are validated against the schema in src/utils/settings/settings.ts.

Does enabling auto-injection slow down OpenClaude startup?

Yes, marginally. The buildRepoMap function runs a PageRank analysis over the repository graph, which requires parsing files through Tree-sitter. The impact depends on repository size, but the result is cached for the session duration.

Can I manually trigger the repo map if auto-injection is disabled?

Yes. Even with repoMap: false, you can run the /repomap command at any time. This command is handled in src/commands/repomap/repomap.ts and will generate a fresh map on demand without modifying the global configuration.

Why does the environment variable use 1 instead of true?

Environment variables are strings; OpenClaude interprets OPENCLAUDE_REPO_MAP=1 as truthy in src/utils/subprocessEnv.ts and src/context.ts. The value auto is also recognized as a special string constant, matching the JSON configuration behavior.

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