# ox index (https://sageox.ai/docs/cli/index-cmd)

# ox index

Build searchable indexes from your codebase. `ox index` creates CodeDB -- a local database of commits, symbols, diffs, PRs, and issues that your AI coworker can query during sessions.

## Usage

<Terminal>
  <TerminalCommand>ox index [subcommand] [flags]</TerminalCommand>
</Terminal>

Run from any initialized repository. The index lives locally on your machine.

## 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.

<Terminal>
  <TerminalCommand>ox index code [url] [flags]</TerminalCommand>
</Terminal>

| Flag | Description |
|------|-------------|
| `--full` | Force a complete re-index, ignoring cached state |

Without `--full`, indexing is incremental -- only new commits since the last index are processed.

<Terminal>
  <TerminalComment>Index the current repository</TerminalComment>
  <TerminalCommand>ox index code</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Index a specific repository by URL</TerminalComment>
  <TerminalCommand>ox index code git@github.com:myorg/myrepo.git</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Force a full re-index</TerminalComment>
  <TerminalCommand>ox index code --full</TerminalCommand>
</Terminal>

### ox index github

Index PRs and issues from your GitHub repository.

<Terminal>
  <TerminalCommand>ox index github [flags]</TerminalCommand>
</Terminal>

| Flag | Description |
|------|-------------|
| `--full` | Force a complete re-index |
| `--prs-only` | Index only pull requests |
| `--issues-only` | Index only issues |

<Terminal>
  <TerminalComment>Index all GitHub activity</TerminalComment>
  <TerminalCommand>ox index github</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Index only PRs</TerminalComment>
  <TerminalCommand>ox index github --prs-only</TerminalCommand>
</Terminal>

## Where the index lives

CodeDB stores indexes locally in your repository's `.sageox/codedb/` directory. The index never leaves your machine -- your AI coworker queries it locally during sessions.

```
.sageox/
└── codedb/
    ├── commits.db      # Git history and diffs
    ├── symbols.db      # Code symbols and definitions
    └── github.db       # PRs and issues
```

<Callout type="info">
CodeDB is local-only by design. Your code and git history stay on your machine. SageOx servers never see your source code.
</Callout>

## 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.

<Terminal>
  <TerminalCommand>ox code search "authentication middleware" --limit 10</TerminalCommand>
</Terminal>

| Flag | Description |
|------|-------------|
| `--limit` | Maximum number of results (default: 20) |
| `--full-json` | Output full result details as JSON |

### Example searches

<Terminal>
  <TerminalComment>Find functions related to user auth</TerminalComment>
  <TerminalCommand>ox code search "user authentication"</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Search for recent changes to the API</TerminalComment>
  <TerminalCommand>ox code search "API endpoint changes"</TerminalCommand>
</Terminal>

<Terminal>
  <TerminalComment>Get JSON output for scripting</TerminalComment>
  <TerminalCommand>ox code search "database migration" --full-json</TerminalCommand>
</Terminal>

## 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` | -- | Show index status and stats |

<Terminal>
  <TerminalComment>Check index status</TerminalComment>
  <TerminalCommand>ox code status</TerminalCommand>
</Terminal>

## How AI coworkers use CodeDB

When you start a coding session with `ox prime` or `ox session start`, your AI coworker gains access to CodeDB queries. This enables:

- **Semantic search** -- find code by meaning, not just text matching
- **History queries** -- "when did this behavior change?" answered from git history
- **Cross-reference navigation** -- understand 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` or `--issues-only` 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 prime](/docs/cli/prime) -- Activate context injection for AI coworkers
- [ox distill](/docs/cli/distill) -- Process GitHub activity into Team Context
- [Claude Code integration](/docs/developers/claude-code) -- How CodeDB enhances AI coding sessions