Code intelligence

A SQLite graph of symbols and call edges, built from the workspace. It answers structural questions roughly ten times cheaper than grep, and it is why the agent can find a definition without reading four files to get there.

Why not grep

grep is a good tool and Cerveau ships it. But a structural question answered with grep costs a lot of window: you search, get forty matches, read three files to work out which one is the definition, and now the window is carrying three files you did not need. The index answers the same question in one call with a few hundred characters.

The store

A SQLite database holding symbols and the edges between them. It is derived data — deleting it costs a rebuild, nothing more — and it lives outside your project directory.

Building it

curl -X POST localhost:7700/api/codegraph/index

Also triggered when the workspace changes. The four tools register only when the index is available, so a workspace with no index simply does not offer them rather than offering tools that fail.

The four tools

file_map

The shape of the repository: which files exist and what is in them. Cap 6000. The usual first call in an unfamiliar codebase — it is the cheapest way to turn "I have no idea where anything is" into a short list of candidates.

find_symbol

Where a symbol is defined. Cap 2000, because the answer is a location and not a file.

find_references

Everywhere a symbol is used. Cap 3000. This is the one that makes a rename safe: the agent can enumerate call sites instead of grepping a name that also appears in three comments and a string literal.

outline_file

One file's declarations without its bodies. Cap 4000. Reading a 2,000-line file to learn it has eleven functions is exactly the window spend this avoids.

The workflow it enables

file_map              # where does this live
outline_file          # what is in that file
find_symbol           # where is the thing defined
find_references       # what would I break
read from_line to_line # now read only the part that matters

Four cheap structural calls before one targeted read, instead of three speculative whole-file reads. On a 96K window that is the difference between finishing a task and compacting halfway through it.