Skip to main content

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.0 is the current stable release. Python, TypeScript/TSX, JavaScript/JSX, Go, Rust, Java, C#, C and C++ have parser slices (TypeScript, JavaScript, Go, Rust, Java, C#, 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. The stable release needs no exact-version pin.

With uv:

uv tool install oxide-agent

With pipx or pip:

pipx install oxide-agent
pip install oxide-agent

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

uvx --from oxide-agent 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]'

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 inspect and oxide refs also exit 1 when the name is ambiguous or unresolved. oxide alone prints the command list with examples.

Human-facing status, warnings, errors and hints use color on supported terminals. Set NO_COLOR=1 to disable it; redirected output, JSON and source payloads remain plain text.

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 checking worktree freshness. Use oxide status --verbose for file diagnostics, skips and collision details (case collisions: none when the snapshot is clean). 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 re-index.

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. Handles open lazily, at the first tool call for a repository: an idle server blocks nothing. Once a handle is open, that handle owns the store, so oxide index, search, context, impact and judge on the same store fail with ownership_conflict while the server is serving that repository. 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.0

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

Built distribution (wheel)

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

Total release size: 454.5 kB

Release files / oxide_agent-0.2.0.tar.gz

Download URL oxide_agent-0.2.0.tar.gz
Size 204.4 kB
Tags Source
SHA-256 checksum
How to use checksums
e5cbfcae8bbe8f18ccbaa9ba59f1ad2c0343ff29d25278b7399d83ca8f468ee2
BLAKE2b-256 checksum
How to use checksums
085075293b2cff6129cbba3715c2a310c2934aefc18bb1aef32b94eab98aaecd
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 20, 2026.

Transparency log

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

Download URL oxide_agent-0.2.0-py3-none-any.whl
Size 250.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d7f9df45b7c8b504ebdde7e9ac55596c69b86768a17b43538370919235c556df
BLAKE2b-256 checksum
How to use checksums
d94b4dbe2440e2ac4f014fc94fb2db753fcd45c2ce531b6a3737bf94503b11aa
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 20, 2026.

Transparency log

Security for oxide-agent 0.2.0

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.0.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 20, 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