oxcode

oxcode indexes source code into a graph and serves it to coding agents. It is built on oxgraph — a storage-agnostic, zero-copy-friendly graph/hypergraph topology substrate for Rust — and stores the index in a native oxgraph database under .oxcode/index.oxgdb/.

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.

Get Started

1. Install

Prebuilt binary (recommended — no Rust toolchain, grammars are statically linked so it runs offline):

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://github.com/oxgraph/oxcode/releases/latest/download/oxcode-cli-installer.ps1 | iex"

Or download an archive from the Releases page. With Cargo instead:

cargo binstall oxcode-cli   # prebuilt, no compile
cargo install --force oxcode-cli   # build from source

This installs one oxcode binary — the CLI plus the MCP server (oxcode mcp). (The crate is oxcode-cli because the bare oxcode name is taken on crates.io; the command is still oxcode.) Re-run the installer (or cargo install --force oxcode-cli) to replace an existing install; oxcode mcp also self-updates on startup once you are on v0.1.2+.

2. Index a project

cd your-project
oxcode index
oxcode context "How does authentication work?"

3. Wire up an agent (MCP)

Add the server to your agent. For Claude Code (~/.claude.json):

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

Once wired, have the agent call oxcode_watch once: it builds the index and keeps it current as files change. When path is omitted, the project root comes from OXCODE_ROOT, CLAUDE_PROJECT_DIR, or WORKSPACE_FOLDER_PATHS — not from the MCP process cwd (hosts often start servers in $HOME). Across multiple agents on one repo a file lock elects a single writer (the one watcher/re-indexer) while the rest serve reads, so you can run as many as you like. Then ask questions with oxcode_explore.

Optionally auto-allow the tools in ~/.claude/settings.json (the query tools are read-only; oxcode_watch only builds/maintains the local index): mcp__oxcode__oxcode_watch, _explore, _search, _callers, _callees, _symbol, _files, _status.

Claude Code plugin (one-command install)

Instead of hand-editing the config above, install the bundled plugin from the oxgraph marketplace — it wires up the MCP server for you:

/plugin marketplace add oxgraph/oxgraph
/plugin install oxcode@oxgraph

The plugin still needs the oxcode binary on your PATH and an indexed project (steps 1–2). See claude-plugin/README.md.

Other MCP clients (registry / npm)

oxcode is listed in the official MCP Registry as io.github.snowmead/oxcode, so registry-aware clients can discover it. For clients that prefer an npx launch command there's also an npm package:

{
  "mcpServers": {
    "oxcode": { "command": "npx", "args": ["-y", "@snowmead/oxcode-mcp"] }
  }
}

@snowmead/oxcode-mcp is a thin wrapper that runs oxcode mcp, so it still needs the oxcode binary on your PATH (step 1) — if you have it, command: "oxcode" above is the simpler config.

How Indexing Works

1. Extraction — tree-sitter parses each source file into a syntax tree. A per-language extractor walks it (hand-written) or runs a tree-sitter query (generic), emitting symbol nodes (file, module, class, struct, trait, interface, function, method, field, …) and edges (contains, calls, imports, references, implements). Qualified names are normalized to a ::-joined internal form regardless of the language's own separator, so the resolver and graph are language-neutral.
2. Resolution — references resolve to definitions across files through tiers: exact qualified name → enclosing module scope → in-scope imports → receiver type → bare name. Ambiguous matches are kept and marked, not dropped.
3. Storage — the resolved graph is reconciled into the oxgraph database with stable symbol identities, so re-indexing is O(change), not O(repo). Personalized PageRank over the graph powers the context command's bounded, relevance-ranked output.

Languages

Run oxcode languages to list the registered extractors. Coverage is tiered:

• High-fidelity — hand-written extractors that resolve receiver-typed method calls (self/this/Go receivers), precise qualified names, and imports (including TypeScript path-based ESM imports).
• Generic — one query-driven extractor shared by all of these languages. Each is a tree-sitter query plus a profile entry (crates/oxcode-core/src/extract/profiles.rs); containment comes from byte-span nesting. It yields symbols and approximate call edges that resolve at the scoped/simple tiers (no receiver typing), so some edges are marked ambiguous.
• Embedded script — Svelte/Vue <script> blocks are extracted as TypeScript at offsets accurate to the original component file.
• Recognized — the file type is known but not indexed yet; such files are reported as skipped, not silently dropped.

Adding a language is a tree-sitter query + a profile entry; promoting one to high fidelity is a hand-written extractor that reuses the shared extract/walker.rs scaffolding.

Quick Start

oxcode index --path path/to/rust/project
oxcode status --path path/to/rust/project
oxcode context "How does entry reach helper?" --path path/to/rust/project --limit 8 --json
oxcode symbols "entry helper" --path path/to/rust/project --limit 20 --json
oxcode symbols "entry helper" --path path/to/rust/project --kind function --kind method
oxcode files "runtime scheduler" --path path/to/rust/project --limit 20 --json
oxcode symbol crate::entry --path path/to/rust/project --json
oxcode calls crate::entry --depth 2 --path path/to/rust/project
oxcode callers crate::helper --depth 2 --path path/to/rust/project
oxcode query "MATCH ELEMENTS WHERE qualified_name = 'crate::entry'" --path path/to/rust/project
oxcode query "MATCH RELATIONS TYPE calls" --format expand --path path/to/rust/project
oxcode query "GRAPH calls WALK FROM 12 DEPTH 2 DIRECTION both LIMIT 100" --path path/to/rust/project

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

Useful selectors for navigation commands:

• element:<id> for a concrete OxGraph element ID
• an exact crate-qualified name such as my_crate::auth::tenant_middleware (qualified names are anchored at the crate, so the first segment is the package name with - normalized to _)
• name:<name> for a simple function name
• file:<path>:<line> for the innermost symbol covering a source line

symbols accepts repeatable --kind <kind> filters. Valid kinds are:

• file, module, namespace, package, class, struct, enum, trait, interface, impl_block, function, method, field, variable, constant, type_alias, macro

context is deterministic and graph-derived. It ranks entry-point symbols for the task text, then expands nearby calls, contains, references, and implements relationships.

query and explain execute raw OxQL/Cypher. For keyword discovery, use symbols; do not pass plain English phrases to query.

Accepted OxQL profile:

• CATALOG
• MATCH ELEMENTS
• MATCH ELEMENTS HAS LABEL <label>
• MATCH ELEMENTS WHERE <property> = '<value>'
• MATCH RELATIONS TYPE <type>
• GRAPH calls WALK FROM <element-id> DEPTH <n> [DIRECTION outgoing|incoming|both] [LIMIT n]

Benchmarks

Agent-task benchmark on the Tokio codebase: an agent answers "How does tokio schedule and run async tasks?" with and without each tool, measuring efficiency and blind-judged answer quality. oxcode and codegraph were measured on different agent harnesses, so the comparable unit is each tool's improvement vs its own no-tool baseline, not absolute numbers.