Project map: agents know where to look before they read

The map is built with tree-sitter. In TypeScript, TSX, JavaScript, Python and Go files, functions, classes, methods, interfaces, types, enums and constants are extracted with their line ranges, signatures and the first sentence of their docs. About 30 more languages, such as Rust, Java, PHP and Ruby, are on the map by file path.

• Imports are resolved to project files; tests are linked to the files they import and to source files with matching names.
• Change together: files that changed together in at least two of the last 500 commits are paired; commits touching more than 40 files are ignored.
• Files are found with git ls-files and .gitignore is respected; folders like node_modules, dist and build, files over 1 MB, generated and minified files are skipped.
• In repositories with more than 20,000 files, only source folders (src, lib, app, packages/*/src…) are indexed.

The map is added to the agent as an MCP server. Its instructions tell the agent to start a task with map_related, check map_outline before reading a file and map_usages before changing code. A new agent’s instructions also get a short summary of the project’s modules, entry points and test command.

• map_related: the files a task most likely involves, ranked with reasons. Turkish task words (sepet, kupon, ödeme…) also match their English names in code.
• map_outline: a file’s symbols with line ranges, how many files import it, and its tests.
• map_usages: where a symbol is defined and called, the files importing it and its tests; for a file, its importers and their importers.
• map_find: fuzzy search over symbol and file names, with kind, file:line and signature.
• map_overview: modules, entry points and the test command. map_api reads the real API of the installed version of a package in node_modules from its .d.ts files.

There is one map per folder (a project or a worktree), shared by every agent working there. File changes are watched, commits trigger a recount of files that change together, and a file an agent asks about is re-checked before the answer. The map is built on your computer and costs no tokens; each agent can read only its own folder’s map.

The Project map tab on a project’s Details page draws files as a graph coloured by module: imports in grey, files that change together as dashed orange lines. Type a task and press “Show” to see the files an agent would look at, with reasons. The “Project map impact” card in the AI ROI tab compares conversations that used the map with those that didn’t, by success, first-time pass, tokens per task and follow-ups.