# CodeDB: smarter code navigation (/docs/developers/codedb)



CodeDB is a semantic index of your codebase that your AI coworker can query during a session — search by meaning, trace git history, and navigate cross-references, instead of falling back on grep and a stack of file reads.

What CodeDB indexes [#what-codedb-indexes]

CodeDB builds a local database from your repository: code symbols, git history, and (optionally) GitHub activity. Your AI coworker queries it during sessions to navigate with precision rather than guessing at file names.

| Source                | Content                                        |
| --------------------- | ---------------------------------------------- |
| Code symbols          | Functions, types, classes                      |
| Git history           | Commits, diffs, file changes                   |
| GitHub PRs and issues | Titles, descriptions, comments, review threads |

The index lives in your repository's `.sageox/cache/codedb/` directory and never leaves your machine. SageOx servers never see your source code.

Index your repo [#index-your-repo]

Run the index once. It updates incrementally after that — only new commits since the last run are processed.

<Terminal>
  <TerminalComment>
    Build or update the code index (run once, updates automatically)
  </TerminalComment>

  <TerminalCommand>
    ox code index
  </TerminalCommand>
</Terminal>

Force a full rebuild after a major refactor or when results look stale:

<Terminal>
  <TerminalCommand>
    ox code index --full
  </TerminalCommand>
</Terminal>

Check what's indexed and when it last ran:

<Terminal>
  <TerminalCommand>
    ox code status
  </TerminalCommand>
</Terminal>

Search by meaning [#search-by-meaning]

Once indexed, query CodeDB with natural language. Search matches on what code does, not on a text pattern alone.

<Terminal>
  <TerminalComment>
    Find code by intent, not by name
  </TerminalComment>

  <TerminalCommand>
    ox code search "authentication middleware"
  </TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>
    Limit results and get JSON for scripting
  </TerminalComment>

  <TerminalCommand>
    ox code search "database migration" --limit 10 --full-json
  </TerminalCommand>
</Terminal>

What your AI coworker gains [#what-your-ai-coworker-gains]

When a session starts, your AI coworker gains access to CodeDB queries. That turns a few common questions from slow file-spelunking into direct lookups:

* **Semantic search** — find functions and types by what they do, not by guessing the name
* **History queries** — "when did this behavior change?" answered from git history instantly
* **Cross-reference navigation** — understand how modules connect across the codebase
* **PR and issue context** — reference decisions from code review threads

Without CodeDB, your AI coworker relies on grep and file reads. With it, the agent has a map of your codebase — and spends its turns reasoning instead of searching.

<Callout type="info">
  CodeDB is local-only by design. Your code and git history stay on your machine; the index is rebuilt from your repo, never uploaded.
</Callout>

What's next [#whats-next]

* [Supported coding agents](/docs/developers/coding-agents) — which agents can query CodeDB
* [SageOx + Claude Code](/docs/developers/claude-code) — CodeDB in a live coding session
* [ox index](/docs/cli/commands/index-cmd) — full indexing reference, flags, and GitHub activity