ox index
Build searchable indexes from code, GitHub PRs, issues, and other project data. ox index creates CodeDB -- a local database of commits, symbols, diffs, PRs, and issues that your AI coworker can query during sessions.
Usage
Run from any initialized repository. With no subcommand, ox index indexes all available sources; use a subcommand to index one source.
| Flag | Description |
|---|---|
--full | Wipe all indexes and rebuild from scratch |
-d, --days | Max days of GitHub history to fetch |
--prs-only | Index only pull requests (GitHub) |
--issues-only | Index only issues (GitHub) |
--no-push | Extract to the Ledger without pushing |
What gets indexed
| Source | Content | Command |
|---|---|---|
| Git history | Commits, diffs, file changes | ox index code |
| Code symbols | Functions, types, classes | ox index code |
| GitHub PRs | Titles, descriptions, comments, review threads | ox index github |
| GitHub issues | Titles, descriptions, labels, comments | ox index github |
Subcommands
ox index code
Index git history and code symbols from your repository.
| Flag | Description |
|---|---|
--full | Wipe the index and rebuild from scratch |
Without --full, indexing is incremental -- only new commits since the last index are processed.
ox index github
Fetch recent PRs and issues from GitHub and make them searchable. The data is extracted to the project Ledger and indexed into CodeDB, where ox code search type:pr and ox code search type:issue find it.
Requires a GitHub token (GITHUB_TOKEN, GH_TOKEN, or gh CLI config). The github_sync, github_sync_prs, and github_sync_issues settings in .sageox/config.json control it; all are enabled by default.
| Flag | Description |
|---|---|
--full | Clear sync state and re-fetch everything |
-d, --days | Max days of history to fetch |
--prs-only | Index only pull requests |
--issues-only | Index only issues |
--no-push | Extract to the Ledger without pushing |
ox index status
Show index status. This is an alias for ox code status; add --json for JSON output.
Where the index lives
CodeDB stores its index locally, and your AI coworker queries it locally during sessions. ox index github also extracts PRs and issues to the project Ledger and pushes them; pass --no-push to extract without pushing.
CodeDB is local-only by design. Your code and git history stay on your machine. SageOx servers never see your source code.
Incremental vs full re-index
By default, ox index runs incrementally:
- Code: Indexes only commits since the last run
- GitHub: Fetches only PRs and issues updated since the last run
Use --full when:
- The index seems stale or incomplete
- You've changed indexing configuration
- You want to rebuild from scratch after a major refactor
Full re-indexing takes longer but ensures the index matches your current repository state.
Searching the index
Once indexed, use ox code search to query CodeDB.
| Flag | Description |
|---|---|
--limit | Maximum number of results |
--full-json | Full uncompacted JSON output (~4x more context tokens) |
Example searches
Related ox code commands
The ox code command group provides shortcuts for common indexing operations.
| Command | Equivalent | Description |
|---|---|---|
ox code index [url] | ox index code [url] | Alias for indexing code |
ox code search <query> | -- | Search the CodeDB index |
ox code status | ox index status | Show index status and stats |
How AI coworkers use CodeDB
During a coding session, your AI coworker queries CodeDB with ox code. This enables:
- Structured search -- a query DSL over symbols, code, diffs, commits, and comments, with filters that grep cannot match
- History queries -- "when did this behavior change?" answered from git history
- Cross-reference navigation -- resolved callers and callees show how modules connect across the codebase
- PR/issue context -- reference decisions from code review threads
Without CodeDB, AI coworkers rely on grep and file reads. With it, they navigate your codebase with precision.
Troubleshooting
"Repository not initialized" -- Run ox init first to connect your repository to SageOx.
"No commits to index" -- The repository needs at least one commit. If you're starting fresh, make an initial commit first.
"GitHub rate limited" -- GitHub API has rate limits. Wait and retry, or use --prs-only, --issues-only, or --days to reduce API calls.
Stale search results -- Run ox index code to pick up recent commits. Use --full if incremental indexing isn't catching changes.
What's next
- ox agent prime -- Activate context injection for AI coworkers
- ox code -- Search the index: symbols, callers, callees, history, and PRs
- Claude Code integration -- How CodeDB enhances AI coding sessions