Code index

The shape of your source tree. For each project, the code index records which files exist, what each one exports, how their imports connect, and the comments that describe them. Agents use it to find their way before they edit.

Part of the brain.

It answers the questions grep is bad at:

Which files export this symbol?
Which files import this one?
What does this file depend on?
Which files does everything else lean on?
Where is this concept handled?

An agent that can ask those before it starts editing spends far less of a session rediscovering the codebase.

Find where something lives#

search matches your query two ways. It matches as a substring of file paths and exported names. It also matches as full text over exported names, the doc comments on exports, and each file's leading comment.

Full-text matching is forgiving about form. Words are stemmed, and camelCase and snake_case identifiers are split into their words, so "retry handling" finds retryWithBackoff.

toryo code-index search --project <id> --query "retry"

Results are ranked and bounded. An exported name equal to the query comes first. Then names that contain it, then file names, then directories, then files that matched only on full text. Ties go to the files more of the codebase imports. % and _ match literally.

The CLI returns 50 results by default (--limit N). The agent tool, code_search, returns 25, up to 100. Both report the total matches and whether the list was cut.

There are no embeddings of code. Vectors go stale with every branch and cost a re-embed on every change, and word search plus a ranked map serves agents without them. Meaning-based retrieval is memory and library's job.

Get oriented in an unfamiliar codebase#

map, and the agent tool code_map, answers "where do I start" when you have no name to search for. It lists files ranked by how much of the codebase depends on them, grouped by directory, each with up to 20 of its exported names. Test files are left out of the list.

toryo code-index map --project <id>

The output fits a budget. --max-chars sets it, 8000 by default, about 2000 tokens. What is shown is always the top of the ranking, never a sample.

Search the code you are editing#

The index describes the project's base: your registered checkout, or for a team project the default branch. Your branch may differ from it.

--worktree <absolute path> on search, map, file, exporters and importers answers for that checkout instead. It lays the checkout's changes over the base for one query, uncommitted and untracked files included. Nothing is written or stored.

An agent session you start yourself inside a linked git worktree of one of your projects gets this automatically.

A team project's index is never built from anyone's working tree, so it never holds one person's branch or uncommitted edits. It tracks the remote's default branch. The project needs a git remote.

Every team member's machine checks it hourly and indexes only the files that changed. Two machines refreshing at once cannot leave it wrong.

Your own branch is answered by the worktree overlay above. It is computed on your machine for each query and never sent to the shared index.

A team index has no working tree to compare against. So a search without --worktree reports its freshness as unknown. With your worktree laid over it, the answer is fresh.

What a team's index stores#

For a team project the shared index holds file paths, exported symbol names, the import graph, and comment text: each file's leading comment and the doc comments on its exports, capped at 8 KB per file. It also keeps a hash of each file, used to tell when it changed. It does not hold whole file contents: function bodies and code that is not exported are never stored.

A project on your own machine keeps the same things, locally.

Keep it current#

A reindex takes the cheapest valid path per file. A file whose modification time is unchanged is skipped outright. Otherwise its contents are hashed, because a git checkout churns modification times without changing bytes and hashing avoids a pointless re-parse. Only a file that genuinely changed is parsed.

Files that vanished from disk are dropped. A --full reindex ignores both fast paths and re-parses everything.

Imports are resolved once every file has a row, so each import points at the file it actually reaches. Imports of another workspace package in the same project resolve too. Third-party package imports are not resolved: the index tracks your code, not your dependencies.

For your own projects, an incremental refresh runs hourly per indexed project, with a full integrity sweep once a month on the scheduler's system lane. A new project is picked up automatically. Team projects have no monthly sweep: they are read from commits, which do not drift the way a working tree does.

Turn indexing off for a project#

Indexing is on by default. Two cases want it off:

Customer parents, whose child repositories already cover the same trees. Indexing the parent directory counts every file twice.
Non-source repositories: config, YAML, or docs-only.

Turn it off from board's Projects screen, or with toryo project update <ref> --no-index. That refuses future reindexes. toryo code-index forget --project <id> clears the existing rows. It is a separate step, so nothing is deleted by accident.

Check how current an answer is#

Every search reports whether the index is fresh, drifted (with counts of files added, changed or removed since the last pass), or unknown (the check could not run, never a claim of freshness). The check only reads and never fails the search.

Use --freshness refresh to reindex drifted projects before searching, or --freshness off to skip the check. For one project's verdict, run toryo code-index status --project <id> --check. Agents see the same verdict in code_search.

How agents use it#

In an unfamiliar area, call code_map first.
For a concept or symbol whose file is unknown, call code_search.
For a known path, read the file directly.

This guidance is in the tool descriptions and in what every supported harness receives at session start.

In board#

The Code Index screen shows per-project index status and file counts, and is where a reindex is triggered by hand. Projects with indexing disabled are hidden.

Full command surface: CLI & contract reference.