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

> Learn 3 easy ways to enable auto-injection of the repo map in OpenClaude. Configure via JSON, CLI flag, or environment variable for seamless integration.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/Gitlawb/openclaude/blob/main/src/context/repoMap/renderer.ts) and embedded directly into the system context under the key `repoMap` (as defined in [`src/context.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/context/repoMap/gitFiles.ts) and ranking components using a token-budgeted algorithm in [`src/context/repoMap/renderer.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`):

```bash
nano ~/.openclaude.json

```

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

```json
{
  "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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/entrypoints/cli.ts):

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

```

To explicitly disable the map for a single run:

```bash
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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/subprocessEnv.ts) injects this variable, which [`src/context.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/context.ts) checks during context construction.

```bash
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`](https://github.com/Gitlawb/openclaude/blob/main/src/context/repoMap/renderer.ts)) executes a PageRank algorithm over the file graph produced by [`src/context/repoMap/gitFiles.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/context/repoMap/gitFiles.ts). The output is a `RepoMapResult` object (defined in [`src/context/repoMap/types.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/context/repoMap/types.ts)) containing the compressed file tree.

2. **Context Assembly** – In [`src/context.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/context.ts), the system gathers context:

```typescript
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`](https://github.com/Gitlawb/openclaude/blob/main/src/tools/RepoMapTool/RepoMapTool.ts)) and answer questions about file relationships without explicit `/repomap` calls.

## Practical Configuration Examples

### Enable Globally via Config

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

```

Now any chat automatically includes the map:

```bash
openclaude chat "Which file contains the authentication logic?"

```

### One-Off Repository Analysis

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

```

### CI Pipeline Integration

```bash
#!/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/context/repoMap/renderer.ts) and injected via [`src/context.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/subprocessEnv.ts) and [`src/context.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/context.ts). The value `auto` is also recognized as a special string constant, matching the JSON configuration behavior.