Repository map
In a large project, finding where a function is defined can take many searches. The repository map helps the agent navigate: it relates files, definitions, and references in the code. It is an optional aid for finding files worth reading. The map does not replace reading the source or decide how to implement a change.
When the agent uses it
Section titled “When the agent uses it”| Moment | How the map can help |
|---|---|
| Understanding an existing project | Find relevant code when recording the architecture. |
| Planning a delivery | Identify where current behavior is implemented. |
| Implementing a task | Locate a definition or check which files the task may affect. |
The agent uses it in three simple steps:
- When recording an existing project’s architecture, planning a delivery, or starting implementation, the agent checks whether a map exists and needs updating.
- When the map helps, the agent consults the overview or asks for a specific file or symbol.
- With the paths it found, the agent reads the actual source and confirms the behavior before planning or changing code.
For example, you can ask: “Find where create_account is defined and check
the flow before changing it.” The agent chooses the appropriate navigation
tools; you do not need to generate or query the map yourself.
Enabling it
Section titled “Enabling it”The map needs an optional library to analyze code. In a project that already
contains compatible code, helmit:env may offer to install it. The agent
installs it only with your authorization. The library lives in an environment
separate from system Python and can be shared across projects.
If it is unavailable, HelmIt continues normally: the agent searches and reads files directly. This fail-open behavior means that architecture, planning, implementation, and commits are not blocked. You can also ask the agent to work without the map.
See usage in the dashboard
Section titled “See usage in the dashboard”The dashboard has a “Repo map — health” block. Its “Generated × consumed” figures count recorded index updates and queries that returned map content. The event table shows recent queries, including whether they requested the whole map, selected files, or a symbol.
These are records of map commands. A recorded query means text was handed over; it does not prove that the agent read it fully or made a good decision from it. The dashboard displays the records available when it is updated; an isolated query does not immediately publish a new dashboard snapshot.
What the map shows — and what it does not
Section titled “What the map shows — and what it does not”The index is generated locally and stored as derived data in .helmit/map/.
Generating it makes no model calls and uses no model tokens. An excerpt the
agent reads later uses context, just like any other text it consults.
The overview is limited so it does not flood the context; it may show only some relevant files. Files without recognized symbols can still appear by name. The map is therefore a starting point, not a complete inventory or proof that a file is unimportant. The agent confirms conclusions in the source and through the project’s normal checks.