Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

OXIDE

PyPI CI License: MIT

OXIDE indexes a repository into a graph of files, modules, symbols and relations, stores it in LadybugDB, and answers "what code matters for this task?" with a bounded context bundle of real source. It is made for coding agents and the people who work with them.

Retrieval needs no embeddings, no model calls and no network. It combines BM25 over code-aware terms with structural seeds from typed hints, then applies TreeRouter and deterministic selection and packing.

Status

0.2.0rc1 is a release candidate. 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.

Upgrading from 0.1.1? Read the changelog first. It lists the breaking changes and what to do about each.

Install

OXIDE needs CPython 3.12 to 3.14 on Linux x86_64, macOS 15 or later (arm64) or Windows x86_64 (platform details). It needs no Rust, Node.js or compiler.

The PyPI project is oxide-agent; the import package and the command are oxide. This is a pre-release, so the commands pin the exact version.

With uv:

uv tool install oxide-agent==0.2.0rc1

With pipx or pip:

pipx install oxide-agent==0.2.0rc1
pip install oxide-agent==0.2.0rc1

To try it once without installing, name the command separately because it differs from the distribution:

uvx --from oxide-agent==0.2.0rc1 oxide --help

Explicit structural search (Repository.structural_search) needs the optional structural extra, which adds ast-grep (about 46 MB):

uv tool install 'oxide-agent[structural]==0.2.0rc1'

Check the install with oxide --version, then fetch the lexical-search extension once:

oxide setup

oxide setup is the only network access OXIDE makes. It downloads the pinned LadybugDB FTS extension for your platform and checks its SHA-256. Without it the lexical channel reports unavailable, and structural seeds and routing still work.

On Windows, LadybugDB also needs the OpenSSL 3 x64 DLLs in the system directory, and it opens only ASCII paths. With a non-ASCII user name, set OXIDE_DATA_DIR and OXIDE_FTS_EXTENSION (details).

Quick start

oxide index  path/to/repo                      # built | unchanged
oxide search path/to/repo "where are failed requests retried" --limit 20
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. oxide index with no path indexes the current directory. context prints the payload on stdout and used/budget units on stderr. Errors print error[<code>]: <message> and exit 2. oxide alone prints the command list with examples.

The same operations are available from Python:

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

oxide status shows the last published snapshot without touching the worktree. oxide impact lists what depends on an entity, and search and context results carry a short blast summary per entry point. oxide outline, oxide inspect and oxide refs read indexed facts, and they can read the snapshot of a process that is already running. While a handle is open, filesystem events keep its index fresh, so you rarely need to index again by hand.

MCP server

oxide mcp serves one read-only tool, oxide_search, over stdio (FastMCP). Its mode is search for ranked locations (the default) or context for a budgeted source bundle. It never indexes, so run oxide index first.

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

Register it once with your MCP clients:

oxide install                    # every MCP client it detects: Claude Code, Codex, Cursor
oxide install --client codex     # or name one: claude, codex, cursor

oxide install writes one user-wide oxide entry per client. The entry runs the Python that installed OXIDE, so the server works from any directory, and each tool call names its repository. It writes only the entry named oxide. For Claude Code it also reports a local entry in the current directory that would override it. Restart the client afterwards.

Run by hand, --repo (repeatable) limits calls to those repositories, and with exactly one they may omit repository.

The server keeps one handle per repository until it shuts down, and it keeps the index fresh itself. That handle owns the store, so while the server runs, oxide index, search, context, impact and judge on the same store fail with ownership_conflict. oxide status, outline, inspect and refs still work, and the last three read the server's latest snapshot. To run the other commands, stop the server first. Ctrl-C and SIGTERM stop it: it prints oxide: stopping, releases the store and exits.

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 serializes concurrent calls on the same handle.
  • Capture holds the captured bytes in memory, at most 1 GiB in scope and 1 MiB per file.
  • Each publication covers the whole snapshot. Unchanged files reuse their captured bytes and parse facts.
  • The Platforms workflow verifies Linux x86_64, macOS 15 or later (arm64) and Windows x86_64.

The public API reference has the full list, with errors, bounds and recovery behavior.

Documentation and development

To work on OXIDE itself, use mise and uv:

git clone https://github.com/Kiy-K/oxide && cd oxide
mise run bootstrap        # uv sync --locked + `oxide setup`
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

Without mise, run uv sync --locked and then uv run oxide setup. The v1 implementation is pinned at commit ac985b28, with its README.

License

MIT

Metadata

Release files for oxide-agent 0.2.0rc1

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.2.0rc1
File Size Uploaded Provenance Actions
oxide_agent-0.2.0rc1.tar.gz 166.6 kB With provenance Details for oxide_agent-0.2.0rc1.tar.gz

Built distribution (wheel)

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

Total release size: 369.4 kB

Release files / oxide_agent-0.2.0rc1.tar.gz

Download URL oxide_agent-0.2.0rc1.tar.gz
Size 166.6 kB
Tags Source
SHA-256 checksum
How to use checksums
c119decd0d01e615ddd1e3fec64d75fb5fb077d1972526cf25d667ee201d01b1
BLAKE2b-256 checksum
How to use checksums
8d1a42112da1b8b85b1e0f0246e3983a1572e4848a4a75f039fa96940c78cd48
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 14, 2026.

Transparency log

Release files / oxide_agent-0.2.0rc1-py3-none-any.whl

Download URL oxide_agent-0.2.0rc1-py3-none-any.whl
Size 202.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9037abb2b5d0c10893fed4c2df24e08eeb12680d0439c24767de6049f9e7959a
BLAKE2b-256 checksum
How to use checksums
75cec4c3d7e900aaa0d939f4fa6382e40637a03bd8e30d6b17884d8fce180f6f
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 14, 2026.

Transparency log

Security for oxide-agent 0.2.0rc1

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.2.0rc1.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 14, 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