gakonst/nanocodex

Nanocodex – a library‑first SDK for an OpenAI‑powered coding agent

What it is – Nanocodex is a head‑less Rust library (with bindings for JavaScript/Node, the browser, and Python) that implements the full OpenAI Responses interaction loop for the gpt‑5.6‑sol family. It ships an embeddable coding agent whose lifecycle (prompt ordering, tool calls, code execution, subprocess cleanup, snapshots, branching, etc.) is owned by the library, so applications don’t have to re‑implement any of that plumbing.

Why it matters – Building a reliable “coding‑assistant” around a large language model usually requires stitching together:

• a prompt‑ordering queue,
• a persistent WebSocket to the model,
• retry/compaction logic,
• tool‑execution sandboxing,
• session history, snapshots, and clean shutdown of subprocesses.

Nanocodex does all of that once and exposes a tiny, typed API. Consumers can focus on their product UI, persistence, or custom tools instead of the orchestration runtime.

---

Core capabilities

Feature	What you get
Typed turn handling	prompt() returns a Turn future; the turn also yields an optional event stream of typed events (e.g., tool calls, usage stats).
Retained session history	The agent keeps an authoritative FIFO history of completed responses; new prompts are delta‑only.
Built‑in tool ecosystem	Workspace tools (file ops, shell exec, patch apply, image view), web‑search, image generation, and a Code Mode JavaScript sandbox that lets the model run arbitrary JS and call tools via await tools.<name>(…).
Branching & snapshots	spawn(), fork(), fork_from() let you create fresh agents or resume from a checkpoint without copying the whole process state.
Durability layer (optional)	Append‑only journal with SQLite/Postgres back‑ends; provides replay, deduplication, and crash‑safe recovery.
Sub‑agents	A lightweight task‑tree registry that adds orchestration primitives (spawn, wait, interrupt) usable from Code Mode.
Multi‑host support	Same Rust core runs natively, in a WASM worker (browser), or via PyO3 (Python). JavaScript bindings expose Agent, Transport, and Subagents for Node or the browser.
OpenAI‑specific	Direct support for the gpt‑5.6‑sol family (default sol, also terra and luna). No generic‑provider abstraction – the library owns the Responses WebSocket behavior.

---

Languages & entry points

Language	Package / crate	Typical entry point
Rust	nanocodex (crate)	Nanocodex::builder(OpenAi::new(...)).build()?
JavaScript / Node	nanocodex npm package	import { Agent, Transport } from "nanocodex/node"
Browser / WASM	Same npm package (nanocodex/browser)	Agent.create({ transport: Transport.hostManaged(...), ... })
Python	PyO3 wheel (nanocodex on PyPI)	Nanocodex(api_key, instructions=...)

---

Typical usage pattern (Rust example)

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, _events) = Nanocodex::builder(openai)
    .instructions("You are a Rust coding agent.")
    .workspace(std::env::current_dir()?)
    .build()?;

let turn = agent.prompt("Fix the failing parser test.").await?;
let result = turn.await?;               // typed TurnResult
println!("{}", result.final_message());
agent.shutdown().await?;

The same flow exists in JavaScript (turn.result()) and Python (agent.prompt(...).result()).

---

When would you use Nanocodex?

• Product teams building IDE extensions, CI bots, or low‑code platforms that need a reliable “code‑fix” or “code‑generation” assistant without re‑implementing the OpenAI conversation loop.
• Research prototypes that want to experiment with custom tools, branching, or durable checkpoints while keeping the core agent stable.
• Full‑stack applications where the same agent runs on the server (Rust/Node) and in the browser (WASM) to give users an in‑page coding workspace.
• Voice‑enabled assistants – the library already ships a voice client; you can attach your own audio pipeline and still benefit from the same session management.

---

Installation quick‑start

# Rust
cargo add nanocodex

# Node (>=22.13)
npm install nanocodex

# Python (from source checkout)
uv venv --python 3.11 py/bindings/.venv
uv pip install -r py/bindings/requirements.txt maturin
py/bindings/.venv/bin/maturin develop --manifest-path py/bindings/Cargo.toml

Or grab the pre‑built CLI/TUI binary for macOS or Linux via the one‑liner shown in the README.

---

Maturity & status

• Crates.io version is published and CI‑tested on Linux/macOS.
• The core agent, durability layer, and tool crates are stable; the browser‑only and experimental VM crates are marked unpublished/experimental.
• Documentation is available on docs.rs and in‑repo READMEs for each crate.
• The project provides a suite of examples (minimal, lifecycle, fork, sub‑agents, browser, React, Vercel workflow) that serve as reference implementations.

---

TL;DR

Nanocodex gives you a single, typed, Rust‑owned SDK that handles the entire OpenAI coding‑assistant lifecycle—prompt ordering, tool execution, branching, snapshots, and cleanup—while exposing thin bindings for JavaScript/Node, the browser, and Python. It lets developers embed a fully‑featured coding agent into any product without writing the orchestration glue themselves.