Skip to main content

OXIDE

A structural context engine for coding agents.

OXIDE captures a repository, derives a typed graph of its files, modules, symbols, and relations, persists that graph in LadybugDB, and answers "what code matters for this task?" with a bounded, source-backed context bundle. Retrieval is vectorless: BM25 over code-aware terms plus structural seeds from typed hints, then TreeRouter and deterministic selection and packing. No embeddings, model runners, or network access on the query path.

Status: pre-release, on main. Python, TypeScript/TSX, JavaScript/JSX, Go, Rust, Java, C and C++ have parser slices (TypeScript, JavaScript, Go, Rust, Java, C, C++); other files are kept as unsupported file evidence. The public Python API is the product boundary (docs/public-api.md). The legacy v1 implementation and its README are pinned at commit ac985b28; the original documentation remains available in the pinned v1 README.

Install

OXIDE needs CPython 3.12-3.14. Development uses mise and uv:

git clone https://github.com/Kiy-K/oxide && cd oxide
mise run bootstrap        # uv sync --locked + `oxide prepare`

Without mise, run uv sync --locked, then uv run oxide prepare. oxide prepare is the only network access OXIDE makes. It downloads the pinned LadybugDB FTS extension for your platform (Linux x86_64, macOS 15+ x86_64/arm64, Windows x86_64; docs/platforms.md) and checks its SHA-256. Without that extension, the lexical channel reports unavailable and structural seeds and routing still work.

Outside the checkout, install the oxide-agent distribution (pip install oxide-agent once it is published, or build it with uv build and pip install dist/oxide_agent-*.whl), then run oxide prepare. That needs only Python and the native wheels. It does not need Rust, Node.js, or a compiler. On Windows, LadybugDB also needs the OpenSSL 3 x64 DLLs in the system directory. It opens only ASCII paths there, so with a non-ASCII user name, set OXIDE_DATA_DIR and OXIDE_FTS_EXTENSION (docs/platforms.md).

Use

uv run oxide index  path/to/repo                      # built | unchanged
uv run oxide search path/to/repo "where are failed requests retried" --limit 20
uv run oxide context path/to/repo "where are failed requests retried" --budget 1024 \
    --symbol RetryPolicy --file src/http/client.py

Every command takes --json (the typed result) and --data-dir. context prints the payload on stdout and used/budget units on stderr. Errors print error[<code>]: <message> and exit 2.

import oxide

with oxide.open_repository("path/to/repo") as repo:   # owns the store until closed
    repo.index()
    hits = repo.search("where are failed requests retried")
    bundle = repo.build_context("where are failed requests retried", budget=1024)
    print(bundle.payload)                             # used <= budget

MCP

oxide mcp serves one read-only tool, oxide_search, over stdio (FastMCP). Its mode is search (ranked locations, the default) or context (a budgeted source bundle); oxide_context was folded into it on 2026-10-18. It never indexes: run oxide index first, and again whenever you want fresher results, even while the server runs.

uv run oxide mcp --repo path/to/repo                      # stdio, for a local agent
uv run oxide mcp --repo path/to/repo --http --port 8765   # stateless HTTP, loopback only

For example, in Claude Code: claude mcp add oxide -- uv run --directory /path/to/oxide oxide mcp --repo /path/to/repo. With --repo (repeatable) calls may only name those repositories, and with exactly one they may omit repository.

The store lives under --data-dir, else $OXIDE_DATA_DIR, else $XDG_DATA_HOME/oxide/py (~/.local/share/oxide/py). It is never captured, even when it sits inside the repository.

Limits

  • One owner per store, across processes. A Repository is not thread-safe.
  • Indexing is a full rebuild per change, and capture holds the captured bytes in memory (at most 1 GiB in scope, 1 MiB per file).
  • Verified on Linux x86_64, macOS 15+ (x86_64, arm64) and Windows x86_64 by the Platforms workflow. Windows needs the OpenSSL 3 DLLs and ASCII store paths; see docs/platforms.md.

docs/public-api.md has the full list, with errors, bounds and recovery behavior.

Develop

mise run verify           # ruff, mypy --strict, pytest (CI runs exactly this)
uv run python scripts/bench.py path/to/corpus   # latency and peak RSS, JSON report

Architecture: docs/spec/SPEC.md, docs/decisions.md and the decisions in docs/adr/, in particular ADR-0011 (Python engine, vectorless retrieval). Contributor workflow: docs/agents/workflow.md. Documentation and historical evidence: docs index.

License

MIT

Metadata

Release files for oxide-agent 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oxide-agent 0.1.1
File Size Uploaded Provenance Actions
oxide_agent-0.1.1.tar.gz 139.1 kB With provenance Details for oxide_agent-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oxide-agent 0.1.1
File Interpreter ABI Platform Actions
oxide_agent-0.1.1-py3-none-any.whl Python 3 none any Details for oxide_agent-0.1.1-py3-none-any.whl

Total release size: 308.0 kB

Release files / oxide_agent-0.1.1.tar.gz

Download URL oxide_agent-0.1.1.tar.gz
Size 139.1 kB
Tags Source
SHA-256 checksum
How to use checksums
77a787bb612de4a7cf438bb6d3a1eca0cf7b817314b063d6d6d5e07e1a98818c
BLAKE2b-256 checksum
How to use checksums
27d5248096394c7f06fe2dc09c68bb187277095a5456ec86105d1b06b7b7cdb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / oxide_agent-0.1.1-py3-none-any.whl

Download URL oxide_agent-0.1.1-py3-none-any.whl
Size 168.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5fdc41ed720a9a06432ba9d75948a905ab9fea01b01c87c6e5cecf691369789b
BLAKE2b-256 checksum
How to use checksums
5015b4341e6c993c8cb6fba6a166f635b07b40ecabc59048e98925227e395dfb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for oxide-agent 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for oxide_agent-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page