nanocodex
Blazing-fast, minimal, library-first reimplementation of Codex
What is it?
What it is
Nanocodex is a blazing‑fast, minimal, library‑first Rust SDK that re‑implements the Codex agent experience. It provides typed turns, tools, events, steering, cancellation, queueing, and fast historical forks over the OpenAI Responses WebSocket API, keeping the entire coding‑agent conversation inside your process without an external server or durable control plane.
Why it exists
It exists to give Rust applications a lightweight, headless agent that behaves like Codex but with a smaller, tighter boundary. By co‑designing the model and its harness, Nanocodex preserves Codex’s operational invariants while exposing a Rust‑centric API, typed tools, Code Mode orchestration, and efficient forkable checkpoints, enabling developers to embed agent logic directly into their code.
Who should use it
Rust developers and AI engineers who want to embed a fast, library‑first coding agent directly into their Rust applications, control the tool‑calling workflow, and leverage Code Mode for efficient, typed interactions.
Who should avoid it
Teams that require a full‑featured, durable agent runtime with built‑in UI, persistent rollouts, multi‑model support, or non‑Rust ecosystems; or users who prefer a turnkey product over a library integration.
How it works
A quick walkthrough in plain English
How nanocodex works
Step 1 of 3
You interact with it
Open nanocodex, send a request, or connect it to your stack.
Features
Advantages
- Significant performance improvements over Codex (1.69x faster for 10 turns)
- Fine-grained control over agent lifecycle and conversation history
- Efficient resource usage via checkpointing and delta requests
- Library-first design enables customization and integration with Rust apps
- Supports complex orchestration without a separate scheduler
- Reduced payload sizes for historical forks (97.4% reduction)
- Transparent handling of cancellations and queued work
- Typed responses and events for safer and more predictable interactions
- Supports both OpenAI API keys and ChatGPT subscriptions
- Minimal overhead with library-first approach
Disadvantages
- Requires Node.js 12.22+ for Code Mode functionality
- Limited to gpt-5.6-sol model family
- Caller must manage sandboxing, permissions, and durability
- No built-in tool catalog or integration catalog
- Less mature TUI/IDE ecosystem compared to Codex
- Historical fork efficiency depends on provider checkpoint retention
- May require more manual configuration for complex workflows
- No durable thread persistence outside the process
- Limited to one WebSocket transport (Responses API)
- Subagent orchestration requires explicit tool definitions
Installation
docker
docker pull ghcr.io/gakonst/nanocodex:latest
native
cargo add nanocodex
FAQ
How do I install and run the Nanocodex CLI on macOS or Linux?
Run the installer script: `curl -fsSL https://nanocodex.paradigm.xyz | bash`. The CLI will use your `OPENAI_API_KEY` from the nearest `.env` or fall back to a stored ChatGPT session. Once installed, simply type `nanocodex` in a project directory to start the agent.
How do I add Nanocodex as a dependency in my Rust project?
Add it via Cargo: `cargo add nanocodex`. If you need Tokio, include it as shown in the README: `tokio = { version = "1", features = ["macros", "rt-multi-thread"] }`. Then create an agent with `Nanocodex::new(api_key)?`.
What is the difference between a normal prompt and a forked prompt, and how do I create one?
A normal `prompt()` queues a new turn that continues the current conversation. A fork creates a new agent starting from a checkpoint: `agent.fork().await?` gives the latest safe state, while `agent.fork_from(&checkpoint).await?` starts from an older turn. Forks share the same WebSocket and history but run independently.
How do I expose Rust functions as tools for the model to call?
Mark async Rust functions with `#[tool]` to generate a typed tool. Build a `Tools` collection with `Tools::builder()` or use `Mcp::builder()` for HTTP/stdio providers. Pass the tools to the agent via `Nanocodex::builder(...).tools(tools).build()?`.
How does authentication work for OpenAI API keys and ChatGPT subscriptions?
For an API key, call `Nanocodex::new(api_key)?`. For a ChatGPT subscription, the CLI performs OAuth and stores credentials in `$CODEX_HOME/auth.json`. You can load this with `load_chatgpt_auth("/path/to/auth.json")` and pass the resulting auth to `Nanocodex::new(auth)?`. The agent will automatically refresh tokens and retry rejected requests.
Featured in Videos
YouTube tutorials and walkthroughs for nanocodex
Alternatives
Similar projects ranked by category, topics, and text overlap.
