# Nanocodex

> A headless, library-first Rust SDK for building products around an OpenAI coding-agent stack with retained sessions, typed history, tools, Code Mode, branches, and events.

Nanocodex is an open-source, headless SDK authored by gakonst that embeds a complete OpenAI Responses agent loop directly into Rust, JavaScript, and Python applications. Released under MIT OR Apache-2.0, version 0.5.0 shipped on August 12, 2026, and the repository has accumulated 430 stars and 50 forks since its creation in July 2026. It is not a provider abstraction or an app server — the public product is an embeddable agent with an owned lifecycle that callers drive through a cheap, cloneable command handle.

## What It Is

Nanocodex is a multi-language agent SDK that wraps the OpenAI Responses WebSocket API into a fully managed, owned lifecycle. The core is written in Rust and exposed to JavaScript (Node, browser, WASM) and Python via native bindings. The key design premise is that callers should not have to rebuild prompt ordering, response-ID threading, tool-result routing, compaction, reconnect replay, or subprocess cleanup — Nanocodex owns all of that. The caller keeps the interface, data, memory, infrastructure, and policy. Supported models are the `gpt-5.6-sol` family (`sol` default, `terra`, and `luna` selections).

## Architecture and Module Boundaries

The crate is structured as an Alloy-style facade (`nanocodex`) over focused lower-level crates:

- **`nanocodex-agent`** — owned driver, turns, results, events, history policy, snapshots, compaction, branches, and cancellation
- **`nanocodex-oai-api`** — OpenAI auth, typed Responses and Realtime boundaries, persistent transports, managed context, retry, pricing, and Tower client
- **`nanocodex-tools`** — tool contract, standard workspace tools, shell/process lifecycle, Code Mode, deferred BM25 tool search, MCP (stdio and Streamable HTTP), and remote dispatch
- **`nanocodex-observability`** — optional full-fidelity tracing and application-owned OpenTelemetry/OTLP initialization
- **`nanocodex-durability`** — optional append-only execution journal with memory, SQLite, and Postgres stores

Applications that only need a managed OpenAI conversation can use the lower-level `OpenAi → Session → ResponseTurn → Response` API without adopting agent policy.

## Multi-Language Deployment Model

Each language path runs the same Rust-owned agent lifecycle:

- **Rust**: `cargo add nanocodex`; the primary surface with the full API
- **Node.js 22.13+**: `npm install nanocodex`; viem-style `Agent`, `Actions`, and `Transport` namespaces
- **Browser/WASM**: runs the Rust agent in a Worker with OPFS filesystem persistence, Pyodide, wasm-clang, browser Git, and optional subagent trees
- **Python 3.11+**: native PyO3 binding built with Maturin; blocking result waits release the GIL
- **Native CLI/TUI**: installable on Apple Silicon macOS and x86-64 glibc Linux via a curl installer; built on Ratatui

The JavaScript and Python bindings expose the same turn results, typed events, history, snapshots, branches, and shutdown semantics as the Rust API.

## Tools, Code Mode, and MCP

Tools are caller-owned capabilities registered via the typed `Tool` trait or the `#[tool]` attribute macro on async Rust functions. The default native workspace runtime supplies bounded `exec_command`, retained `write_stdin` sessions, Rust-verified `apply_patch`, `view_image`, planning, web search, and image generation. Code Mode presents one compositional JavaScript execution tool to the model; inside a cell, code can loop, branch, fan out with `Promise.all`, and call typed tools through `await tools.<name>(...)`. MCP is part of the native tools crate — stdio and Streamable HTTP servers are discovered in the background, deferred tools are found with BM25 `tool_search`, and OAuth persistence, allow/deny lists, bounded concurrent startup, and hot reload are managed at that boundary.

## Update: v0.5.0

Version 0.5.0 was published to crates.io on August 12, 2026, and is 100% documented on docs.rs. The release stabilizes the four published crates (`nanocodex`, `nanocodex-agent`, `nanocodex-oai-api`, `nanocodex-tools`) and the optional `nanocodex-observability`. Experimental crates — browser, VM, voice, egress, and eval — remain workspace members passing all CI gates but are not yet published to crates.io. The repository's retained benchmark evidence includes a PR #50 release gate where the project reports 39/39 latency gates passed and a 97.879% model-time ratio across a paired 10-turn plus three-fork workload.

## Features
- Owned agent lifecycle with cheap cloneable command handle
- Retained OpenAI Responses WebSocket sessions with typed history
- Ordered turn submission with FIFO prompt queue
- Typed event stream independent from turn result awaiting
- Code Mode: compositional JavaScript execution tool for the model
- MCP support (stdio and Streamable HTTP) with BM25 deferred tool search
- #[tool] attribute macro for defining typed JSON function tools
- Branching: spawn, fork, fork_from, and SessionSnapshot for resumption
- Optional nanocodex-durability: append-only journal with SQLite/Postgres stores
- Automatic USD cost estimation per turn from provider token usage
- Native CLI/TUI consumer built on Ratatui
- JavaScript bindings for Node.js, browser, and WASM
- Python bindings via PyO3/Maturin
- Optional nanocodex-observability with OpenTelemetry/OTLP tracing
- Experimental browser automation (nanocodex-browser) with Chromium control
- Experimental VM workspaces via libkrun (nanocodex-vm)
- Experimental voice input via GPT Realtime (nanocodex-voice)
- Experimental evaluation harness with VM-isolated attempts (nanocodex-eval)
- Subagent task-tree with seven canonical child-agent tools (nanocodex-subagents)
- Cancellation targeting one active or queued turn with subprocess group cleanup

## Integrations
OpenAI Responses API, OpenAI Realtime API, MCP (Model Context Protocol) servers, Tokio async runtime, Tower HTTP middleware, OpenTelemetry / OTLP, SQLite, PostgreSQL, Cloudflare Durable Objects, Cloudflare Workers, Rivet Actors, Vercel Workflows, Pyodide (Python in browser), Ratatui (terminal UI), React, Vite, wterm / xterm.js, libkrun (VM), Chromium / CDP (browser automation)

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
0.5.0

## Links
- Website: https://github.com/gakonst/nanocodex
- Documentation: https://docs.rs/nanocodex/latest/nanocodex/
- Repository: https://github.com/gakonst/nanocodex
- EveryDev.ai: https://www.everydev.ai/tools/nanocodex