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
- What it does for you
- How it is built
- Limits
- Reordering results
- Turn it off
- Settings
- If something goes wrong
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
- The agent gets a
search_codetool that takes a description and returns the closest pieces of code, beside the exact-textsearch_files. - Each new request also carries up to five pointers (file, lines and symbol, not the code) to the places the index ranks closest to it, so the agent knows where to look first.
- Results combine a meaning-based ranking with an exact-word one, so both the exact name and a paraphrase come up.
It works in Agent, Plan, Ask and Debug. There is nothing to start: it is on by default.
How it is built
- A few seconds after the window opens, AstraCode lists the project's source files, honouring
.gitignore. - 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.
- The vectors are stored on your machine under
~/.astracode/index. The text is not stored anywhere else. - 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
- Up to 4,000 files and 40,000 pieces per project. Recently changed files come first, then source, then tests, then documentation and generated code, so the most useful part is searchable first. A partial index says so, and the agent knows exact search still covers everything.
- Files over 200 KB, binary files and folders such as dependencies and build output are skipped.
- With several folders open, the first folder is indexed. A parallel agent searches its own worktree.
- Nothing is indexed in a folder you have not trusted, or while you are signed out.
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
| Setting | Default | What it does |
|---|---|---|
astracode.index.enabled | on | Index the workspace so the agent can search code by meaning. |
astracode.index.rerank | on | Let 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.
- The index stays off in a folder you just cloned: it is not indexed until you trust it. See Workspace trust.
- Nothing is indexed after signing out: sign in again. See Signing in.
- sync failed: usually a network problem; it tries again on the next save or within 30 minutes. See Usage, billing and network errors.
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems