# ox index (/docs/cli/commands/index-cmd)



ox index [#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 [#usage]

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

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

What gets indexed [#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 [#subcommands]

ox index code [#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](mailto: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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#whats-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