OXIDE
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
Repositoryserializes 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
- Public API, platforms and the security model
- Specification and architecture decisions
- Contributor workflow and the documentation index
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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 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.