nanocodex

Install · Agent API · Thesis · Components · VM-backed tools · Evaluation · Documentation

Install

Install the Nanocodex CLI on macOS or Linux:

curl -fsSL https://nanocodex.paradigm.xyz | bash

Or add the Rust SDK to an application:

cargo add nanocodex

Switch the installed CLI between builds:

nanocodex update                 # latest stable release
nanocodex update 0.2.0           # exact release, including downgrades
nanocodex update --nightly       # latest nightly
nanocodex update --pr 50         # verified on-demand PR artifact
nanocodex update --path ./nanocodex  # trusted local binary

Downloaded builds are retained under ~/.nanocodex/versions. Running nanocodex update 0.2.0 again switches to the cached binary without another download. A stable launcher keeps nanocodex update available even while an older binary is active, and ~/.nanocodex/current points to the selected version.

PR artifacts require an authenticated gh CLI and an already completed on-demand artifact workflow for that PR.

Interactive cleanup workflow

The TUI includes a behavior-preserving cleanup pass for recently changed code:

/simplify
/simplify focus on memory efficiency

The command selects the current Git diff, runs independent reuse, simplification, efficiency, and abstraction-depth reviewers concurrently, then deduplicates and applies valid findings. The workflow reuses the CLI's owned subagent runtime in ordinary TUI sessions. General-purpose subagent tools are enabled by default and can be disabled with --subagents false; the dedicated cleanup workflow remains available when they are disabled.

Minimal API Example

use nanocodex::{Nanocodex, OpenAi};

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, mut events) = Nanocodex::builder(openai)
    .instructions(
        "You are a Rust coding agent. Make focused changes, preserve unrelated work, \
         and run relevant tests before finishing.",
    )
    .workspace(std::env::current_dir()?)
    .build()?;

let event_task = tokio::spawn(async move {
    while let Some(event) = events.recv().await {
        eprintln!("event {}: {:?}", event.seq, event.kind);
        if event.kind.is_terminal() {
            break;
        }
    }
});

// Alternative: stream this turn's response as it arrives:
// use futures_util::StreamExt;
// use nanocodex::agent::events::{AgentEventData, AssistantEvent};
// let mut turn = agent.prompt("Find and fix the failing parser test.").await?;
// while let Some(event) = turn.next().await {
//     if let AgentEventData::Assistant(AssistantEvent::Delta(delta)) = event.data()? {
//         print!("{}", delta.text);
//     }
// }
let result = agent
    .prompt("Find and fix the failing parser test.")
    .await?
    .await?;

event_task.await?;
println!("{}", result.final_message());

The first await accepts and orders the prompt. The second waits for its typed TurnResult. Follow-on prompts automatically reuse the agent's retained history, WebSocket, tools, shell sessions, and prompt-cache identity. agent.clone() is a cheap handle to that same session; the independently returned AgentEvents stream is the session-wide event firehose.

Nanocodex supports gpt-5.6-sol (the default), gpt-5.6-terra, and gpt-5.6-luna. Select a model with .model(Model::Terra) or .model(Model::Luna) when creating an agent. The model is fixed for that thread: switching later would invalidate the provider checkpoint and require an inefficient replay of the complete retained context.

API-key HTTPS OpenAI routing gateways that namespace model identifiers can set NANOCODEX_MODEL_ID_PREFIX. For example, a prefix of openai sends openai/gpt-5.6-sol on the wire while preserving Sol's typed behavior, pricing, compaction, and snapshot identity inside Nanocodex. This does not add an alternate provider or arbitrary-model surface.

Voice: devices or Unix pipes

The non-TUI desktop example owns the default microphone and speaker directly in Rust, using the same VoiceSessionBuilder as the production TUI:

nanocodex auth login # once; shares ~/.codex/auth.json with Codex
cargo run -p nanocodex-examples --bin voice

For non-interactive Business or Enterprise hosts, set CODEX_ACCESS_TOKEN=at-...; it takes precedence over the default stored credential and does not require browser login or OAuth refresh.

The lower adapter leaves device and media ownership outside Nanocodex. It reads 24 kHz mono PCM16 little-endian audio from stdin, writes the same format to stdout, and keeps transcripts and agent events on stderr:

cargo run -p nanocodex-examples --bin realtime-pipe < microphone.pcm > speaker.pcm

# Equivalently, compose any live capture/decoder and playback/encoder:
capture-s16le | cargo run --quiet -p nanocodex-examples --bin realtime-pipe | play-s16le

Both retain one coding-agent session. A spoken request starts work while idle; a follow-up received during that work atomically steers the active turn at its next safe model boundary. Both use shared Codex/ChatGPT subscription auth, not an API key. Set NANOCODEX_AUTH_FILE to override the normal Codex credential path.

Thesis

Small, excellent building blocks

Agent infrastructure is easier to understand and reuse when each piece has a sharp owner and a useful API of its own. An OpenAI client should work without an agent loop. Tools should work without a CLI. The high-level agent should compose those pieces rather than hide another implementation of them.

Nanocodex makes a small number of deliberate choices—Rust, Tower, typed protocols, owned lifecycle state, and builder APIs—then keeps the boundaries boring.

The model and harness are co-designed

We do not try to outsmart behavior that frontier models and Codex already make explicit. Context management, AGENTS.md, compaction, cache identity, tool shapes, continuation, reconnect replay, cancellation, and process cleanup are parts of the model-facing contract.

Nanocodex carries those invariants into a smaller, library-first API while leaving application policy with the caller.

Evidence over intuition

Representative cargo bench workloads, OpenTelemetry traces, differential tests, and end-to-end evals keep the harness honest. The goal is simple: normal agent turns should be model- and network-latency bound, with token usage and estimated USD cost visible at the same typed boundary as the result.

Components

nanocodex                         Alloy-style facade and prelude
├── agent                         nanocodex-agent
│   ├── oai                       nanocodex-oai-api
│   └── tools                     nanocodex-tools
│       └── macros                nanocodex-tools-macros
├── oai                           nanocodex-oai-api
├── tools                         nanocodex-tools
└── observability                 nanocodex-observability (optional)

The facade provides the canonical common imports. Each lower crate is also designed to be useful directly, without importing the higher orchestration layer.

nanocodex

The thin facade reexports the golden agent path at the crate root and keeps detailed APIs under nanocodex::agent, nanocodex::oai, and nanocodex::tools. Its prelude contains only the common types needed to build an agent.

Facade guide · API documentation

nanocodex-agent

The batteries-included lifecycle: an owned private driver, a cheap cloneable Nanocodex handle, typed Turn and TurnResult values, and an optional event stream. It owns prompt ordering, the tool loop, AGENTS.md discovery, compaction timing, cancellation, snapshots, and branching through spawn, fork, and fork_from.

Callers never pass previous messages, response IDs, or tool results back into the agent.

Agent guide · API documentation

nanocodex-oai-api

The complete OpenAI boundary: API-key and ChatGPT authentication, typed Responses protocol values, a persistent WebSocket transport, client-owned context, continuation and replay, automatic pricing, and a generic Tower client.

Its standalone OpenAi -> Session -> ResponseTurn -> Response path provides a managed conversation without taking on agent policy. Custom Tower layers and services remain concrete and nameable—no boxing or global client is required.

OpenAI API guide · API documentation

nanocodex-tools

The model-facing tool runtime: the Tool contract, heterogeneous Tools registry, standard workspace tools, shell and process lifecycle, Code Mode, deferred tool_search, remote dispatch, and MCP. MCP is always available on native targets.

Applications can implement Tool directly or use the reexported #[tool] macro. The separate nanocodex-tools-macros package exists only for Rust's procedural-macro boundary.

Tools guide · API documentation

nanocodex-observability