Docs › Context › Codebase index

Codebase index

How AstraCode indexes your project so the agent can search code by meaning, what is sent and stored, its limits, and how to turn it off.

On this page

Exact text search finds refreshToken. It does not find the code that answers "where do we renew a session before it expires?" when it uses different words. The codebase index lets the agent search by meaning as well as by text.

What it does for you

It works in Agent, Plan, Ask and Debug. There is nothing to start: it is on by default.

How it is built

  1. A few seconds after the window opens, AstraCode lists the project's source files, honouring .gitignore.
  2. It splits them into function-sized pieces and sends each piece through AstraCode to be turned into a vector, the same path a file the agent reads already takes.
  3. The vectors are stored on your machine under ~/.astracode/index. The text is not stored anywhere else.
  4. After that, a file is re-indexed when you save it, and the whole project is brought up to date every 30 minutes. A reload part-way through keeps what was finished.

A first build of a large project takes a few minutes. Until it finishes, search_code says the index is still building, and the agent uses exact search meanwhile, so a run that starts early is slower, not wrong.

Limits

Reordering results

With astracode.index.rerank on (the default), the twenty best matches and the question go once to a small, fast model, which puts them in the order a developer would want. It is one short extra request per search; if it fails, the original order is kept. Turn it off to rank by the combined score alone.

Turn it off

Set astracode.index.enabled to false. The agent then searches text only, and search_code answers that the index is off. Your existing index stays on disk, so turning it back on brings it up to date instead of starting again. To remove it, delete ~/.astracode/index.

Settings

SettingDefaultWhat it does
astracode.index.enabledonIndex the workspace so the agent can search code by meaning.
astracode.index.rerankonLet a small model reorder the top search results.

If something goes wrong

Run AstraCode: Show Agent Log. After each update the log has a line starting code index: with how many files and pieces are indexed, or code index: sync failed with the reason. The agent is also told the index's state at the start of every run, so in Ask mode you can simply ask it whether the index is ready.

← Memories Workspaces →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference