Skip to main content
Source Code: src/gaia/agents/base/project_map.py
Without a project map the agent opens every task blind. It guesses directory names, guesses which programs are installed, and guesses which shell it is talking to — and every wrong guess costs a full round trip to learn something one orientation pass establishes once. The GAIA agent now runs that pass at the start of every task and puts the result in its system prompt.

​
What it contains

​
The token budget

600 tokens. That is 1.8% of the NPU profile’s 32,768-token window (NPU_CTX_SIZE) and 0.9% of the GPU profile’s 65,536. It is sized against the smaller window on purpose — a budget that only holds on 64K is not a budget. Measured with GAIA’s shared estimator (count_tokens — cl100k, or a character ratio when tiktoken is absent), so it bounds the map to within that estimator’s error of the model’s own count rather than to the exact token. render_project_map() enforces it on every render. Sections are emitted in priority order and the directory listing carries its own sub-cap, so on a 2,000-directory monorepo the platform quirks and the command list still survive while the tree is what gets trimmed.

​
Which directories count as a code repository

The predicate is testable, not a judgement call. is_code_repository(path) is true when a version-control directory or a recognised manifest sits at the root — non-recursive, so a home directory full of repositories is not itself one.
.git, .hg, .svn
pyproject.toml, setup.py, setup.cfg, requirements.txt, package.json, Cargo.toml, go.mod, pom.xml, build.gradle, build.gradle.kts, CMakeLists.txt, Makefile, Gemfile, composer.json

​
Platform quirks

Three, and only three — the differences that change the text of a command the model emits. A contributor can check the list off:
  1. Path separator — \ on Windows, / elsewhere.
  2. Path quoting for spaces — double quotes on Windows, single quotes on POSIX.
  3. Shell dialect — cmd.exe or PowerShell on Windows; $SHELL’s basename otherwise.

​
Automatic code indexing

When the root is a code repository and no code index exists, the map calls index_codebase in a background thread and says so in the prompt, so the model knows to grep until it lands. It fires at most once per session. Turn it off on a monorepo where a full embedding pass is not worth it:

​
Choosing the root

Resolution order:
  1. project_root on GaiaAgentConfig
  2. the GAIA_PROJECT_ROOT environment variable
  3. the working directory, or the nearest repository up to four levels above it
A working directory anywhere inside GAIA’s own source tree is rejected — in dev mode the agent sidecar is launched from its package directory inside the GAIA checkout, and mapping (and auto-indexing) its own source is never what the user asked for. An explicitly configured root is exempt: pointing GAIA at GAIA is fine when you mean it. Only a source or editable checkout counts as GAIA’s own tree. Installing GAIA into a virtualenv inside your own project — the embedded-SDK layout — leaves your project mapped normally. If none of those is a repository the agent gets no map at all. That is the right answer, not a degraded one — an agent answering questions from a home directory is not in a project, and a map of ~ would spend tokens describing nothing.
A GAIA_PROJECT_ROOT that does not exist raises at startup rather than being quietly ignored.

​
Caching

The map is built once per root and reused. It is rebuilt when a fingerprint over four things changes: the top-level directory listing, every manifest’s size and mtime, the VCS head, and PATH. Between changes, repeated queries reuse one walk.

Code Index

The semantic index the map triggers.

Memory

Day-0 system facts, from the same binary probe.