Code-map defaults

The code map is an index of your symbols and references. It is built by parsers, with no model, so the same commit always gives the same map. It works on an Overlane-native repository and on a connected GitHub repository alike, because the map belongs to the project and not to a hosting provider.

There are two separate settings, and they have different defaults because they were measured separately.

The map as context

The map is a short block of file paths, symbols and call edges, capped at 4,000 tokens. The cap is checked at about 2.3 characters per token, which is what this dense text measures. It is delivered once per session, on the first prompt, by a UserPromptSubmit hook in the plugin, for Claude Code and Codex. The hook ranks the map by the words of that prompt, with no model: the symbols the prompt names or describes come first, with their callers and callees, then the files nearest to them. A client with no prompt hook would get the map at session start instead, ranked by the call graph alone.

The intent comes from task intake: OVERLANE_TASK_INTENT (read-only or edit), the words of the prompt (or OVERLANE_TASK_PROMPT), or an active task, which counts as an edit. A request to explain and then change something counts as an edit, so doubt keeps the map opt-in. Any edit verb counts, even in the negative: a prompt that ends “Do not modify any files” is read as an edit, so the map stays off for it unless you set OVERLANE_CODE_MAP_CONTEXT=on or the project to on.

To choose for one session, set OVERLANE_CODE_MAP_CONTEXT=on or off. The map is delivered on the first prompt that turns it on and not again in that session; OVERLANE_CODE_MAP_DELIVERY=every-prompt repeats it on every prompt. To choose for a project, set codeMapContext to default, on or off with PATCH /v1/tenants/{tenantId}/projects/{projectId}. The project setting overrides the defaults above in both directions.

The block is labelled as reference data and says it holds no instructions. It names the revision it was built at, how many files it covers and whether it is current, stale or built before uncommitted changes. It also carries one fixed line for changes to constants and limits: search for the literal value too, because a hard-coded copy can sit in another file and the map lists names, not literals.

The map is built before the session: the index builder’s map command, run in the checkout, writes .overlane/state/code-index.json (what the hook ranks by the prompt) and .overlane/state/code-map.json (the task-free fallback). With no index the hook uses the fallback; with neither, or a damaged file, it adds nothing to the session and writes one line to .overlane/state/misses.log. On Codex the hook needs the one-time trust step for plugin hooks, and its entry raises Codex’s default limit of about 2,500 tokens per hook output so the whole map arrives.

What was measured

Measured on navigation questions in a 1,196-file synthetic TypeScript repository, Claude Code headless, with the map delivered by the plugin’s prompt hook on the first prompt and ranked by that prompt, median tokens 52% of the baseline (90% interval 43% to 80%) at equal completion, about 88% of the cost (90% interval 79% to 109%); no saving on edits.

• The repository is generated for the test, not real code. This says nothing about a real repository until the map has been measured on real repositories.
• The saving comes from skipped search turns. It is largest on multi-hop questions such as call chains and class hierarchies, and absent when one grep answers the question.
• This is the shipped form: the plugin’s own hook delivered the map on the first prompt, ranked by it, in 110 of 110 runs, and loading the plugin with the map off cost the same as no plugin. The saving holds where the map is on; the default does not turn it on for a prompt that says not to modify files (see above). The cost saving is not established: its interval includes no saving. The earlier test (49% to 70%) ranked the map by the question in the test rig and printed it at session start; the task-free session-start map is now only the fallback and is not measured.
• Codex has the same kind of hook and is not measured; nor is an interactive session.
• For edits there was no saving, and on one task the map led the agent past a hard-coded copy of a limit that it did not list. That is why edits are opt-in, and why the injected text now carries the constants line. A fresh set of 60 edit runs (2026-10-10) completed all 30 with the map and all 30 without, but used 105% of the baseline’s tokens, so edits stay opt-in.
• The old tool-based map showed no saving: the agent called a code tool in 1 run of 80. That is why codeLayer stays off.

The counts and the runs that did not finish are kept with the results of the test. The product page states the same number with the same conditions.

Code tools

The code tools follow the latest measurement for each setting. A local agent with grep got no saving from them and the agent rarely called them, so codeLayer is off there. Where there is no checkout the tool default is on, provisional until an agent re-run says otherwise. A failed re-run turns a setting off; a passed one turns it on.

overlane code-map status

The status lists every supported client in its local and cloud setting, with two lines for each: whether the code tools are on, and what the map as context does, each with the reason. The project settings are shown first. OVERLANE_CODE_MAP=on or off is an explicit choice for the local code tools.

Related

• overlane code-map status shows, per client, both settings and why.
• How review works uses the map for the callers a change touches.
• Memory scopes and precedence covers memories linked to symbols.
• The code map product page is the short version of this page.