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
Repositoryis 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.