Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Getting started

oxcode indexes source code into a native OxGraph database. It uses tree-sitter for extraction, resolves code references into graph relations, and stores the result under .oxcode/index.oxgdb/. It is the first downstream consumer of the oxgraph engine, and it indexes 20 languages.

The CLI keeps raw OxQL available, but agent navigation should usually start with context, symbols, files, and the call-graph commands, because they expand graph IDs back into function names, definition ranges, signatures, docstrings, source previews, and call-site source context.

Install

From crates.io (needs a Rust toolchain):

cargo install oxcode-cli

Or download a prebuilt binary for macOS, Linux, or Windows, no toolchain needed:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/oxgraph/oxcode/releases/latest/download/oxcode-cli-installer.sh | sh

Either way the installed binary is oxcode (the crate is oxcode-cli because the bare oxcode name is taken on crates.io). Grammars are statically linked, so indexing is offline and deterministic with no runtime grammar download.

Quick start

oxcode index --path path/to/project
oxcode status --path path/to/project
oxcode context "How does entry reach helper?" --path path/to/project --limit 8 --json
oxcode symbols "entry helper" --path path/to/project --limit 20 --json
oxcode symbol crate::entry --path path/to/project --json
oxcode calls crate::entry --depth 2 --path path/to/project
oxcode callers crate::helper --depth 2 --path path/to/project

Index once, then re-run oxcode index after edits: re-indexing is O(change), not O(repo), so it stays fast on large codebases. See How indexing works for the pipeline.

The .oxcode directory

Indexing writes everything under .oxcode/ in the project root:

  • .oxcode/index.oxgdb/ — the native OxGraph database.
  • .oxcode/manifest.json — a content digest and index stats that make re-index O(change): unchanged symbols keep their identities and emit no mutations.

The directory writes its own .gitignore, so the index is never committed by accident.

Use it from a coding agent

The MCP server is the headline interface. Point an MCP-capable agent at oxcode mcp; it calls oxcode_watch once to build and keep the index current as files change (no manual oxcode index needed for the MCP path), then gets the same bounded, PageRank-curated context in one oxcode_explore call instead of composing the CLI itself:

{
  "mcpServers": {
    "oxcode": { "command": "oxcode", "args": ["mcp"] }
  }
}

On Claude Code, the bundled plugin ships this config in one command — /plugin marketplace add oxgraph/oxgraph, then /plugin install oxcode@oxgraph.

Architecture

The workspace publishes three crates and ships one binary:

  • oxcode-model — storage-neutral vocabulary: code-graph kinds, identifier newtypes, the graph schema catalog, the selector grammar, the extraction/resolution IR, and agent-facing report DTOs.
  • oxcode-core — indexing, extraction, reference resolution, OxGraph storage, navigation, formatting, and the public ProjectIndex facade.
  • oxcode-cli — the CLI crate. It builds the single oxcode binary, which includes the MCP server as the oxcode mcp subcommand.

The model crate's typed schema is the single source of truth that the storage layer derives property registration, read-key caching, and indexes from.

Next