nanocodex-tools 0.2.0

Nanocodex is a Code Mode-first Rust agents SDK. It provides typed turns, tools, events, steering, cancellation, queueing, durable session snapshots, and fast historical forks over the OpenAI Responses API. It supports persistent WebSocket and HTTPS/SSE transports while keeping the complete coding-agent conversation inside your process, without requiring an app server or durable control plane.

Installation

Install the daily-driver CLI on macOS or Linux:

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

The installer tracks stable releases. Switch an installed CLI to the rolling nightly channel with:

nanocodex update --nightly

Multi-architecture Linux images are published to GHCR as ghcr.io/gakonst/nanocodex:latest and ghcr.io/gakonst/nanocodex:nightly. Immutable version, commit, and nightly-<commit> tags are also available.

Add the library to a Rust project:

cargo add nanocodex

Or add it directly to Cargo.toml:

[dependencies]
nanocodex = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Node.js 12.22 or newer must be available on PATH for Code Mode.

Model and harness co-design

Nanocodex starts from a simple thesis: the model and its harness are one system. A coding model is not an interchangeable completion engine floating above an arbitrary tool loop. Its effective capabilities depend on the exact instructions, tool contracts, response shapes, history ordering, continuation semantics, cache identity, streaming behavior, and failure recovery that surround it. Change the harness and you change the agent.

That is why Nanocodex begins with how Codex actually works. We inspect the concrete Codex implementation, identify the model-facing invariants and operational behavior it relies on, and adapt them rather than designing a provider-neutral agent abstraction from first principles. Typed Responses items, stable prompt prefixes, incremental conversation continuation, complete history replay, tool-call ordering, WebSocket lifecycle, cancellation, and subprocess cleanup are parts of the behavioral contract, not incidental plumbing.

The adaptation is as important as the fidelity. Nanocodex keeps the pieces that shape model behavior, then recasts them for a headless, library-first product: one owned driver instead of an app server, typed results and optional events instead of a durable rollout control plane, caller-defined tools instead of a product-wide integration catalog, and generated Code Mode orchestration instead of a generic workflow or multi-agent scheduler. Codex is the evidence and the behavioral reference; Nanocodex chooses the smaller API boundary.

This also means agent quality and performance belong to the model–harness pair. We evaluate the complete path—prompt, tools, transport, caching, execution, and recovery—because a model-only comparison would miss the system we are actually building.

Why Code Mode?

Most tool-calling agents expose a flat catalog and return to the model between operations. Nanocodex instead presents caller-defined Rust tools and MCP tools as typed JavaScript functions behind one Code Mode entrypoint. The model can write a small program that uses loops, conditions, data transformations, and Promise.all, so related tool work can be composed inside one cell without a model round trip between every operation.

This keeps the model-facing surface small while the application keeps normal Rust ownership. Tool implementations, credentials, retry policy, and mutable state stay outside the generated program. Code Mode runs cells on a prewarmed, session-persistent Node host and gives the model explicit controls for yielding, resuming long work, and bounding returned output.

Subagents make that composition especially useful. An application can expose AgentHandle::spawn() as a clean-room worker, AgentHandle::fork() as a worker with the latest safe conversation context, and another tool for follow-up turns on a retained child. Code Mode can then generate the orchestration topology for the task instead of selecting a hard-coded workflow DAG:

const [independent, contextual] = await Promise.all([
  tools.spawn_agent({
    role: "reviewer",
    task: "Find assumptions the parent may have missed."
  }),
  tools.fork_agent({
    role: "investigator",
    task: "Trace the suspected regression using our existing context."
  })
]);

const followUp = await tools.prompt_agent({
  agent_id: independent.agent_id,
  task: `Challenge this conclusion:\n\n${contextual.report}`
});

text({ independent, contextual, followUp });

That allows dynamic fan-out, fan-in, independent checks, contextual branches, and targeted follow-ups while Nanocodex core remains one owned agent lifecycle rather than a generic multi-agent scheduler. The bundled CLI exposes this example surface with nanocodex --subagents true; library consumers define the tools and policy themselves. See subagents.rs for the complete implementation.

API

let (agent, _events) = Nanocodex::new(api_key)?;

// Accepted now.
let turn = agent.prompt("Inspect this repository.").await?;
// Optional cloneable control.
let _control = turn.control();
// Steer the same active turn.
turn.steer("Focus on the failing tests.").await?;
// Completed result and checkpoint.
let checkpoint = turn.result().await?;

let _follow_on = agent.prompt("Now propose a fix.").await?.result().await?;

let turn = agent.prompt("Run a long investigation.").await?;
// Cancel queued or active work.
turn.cancel().await?;
// Returns Err(TurnCancelled).
let _cancelled = turn.result().await;

// Fork from the latest safe model/tool boundary.
let (latest, _events) = agent.fork().await?;
// Fork from the exact older state.
let (historical, _events) = agent.fork_from(&checkpoint).await?;

// The application owns snapshot storage and retention.
let stored = serde_json::to_vec(&checkpoint.snapshot())?;
drop(agent);
let snapshot = serde_json::from_slice(&stored)?;
let (resumed, _events) = Nanocodex::builder(api_key)
    .resume(snapshot)
    .build()?;

prompt().await means accepted, not completed. The agent retains conversation history, tools, cache identity, response chain, and its WebSocket automatically. Snapshots contain the complete unredacted conversation and must be protected like the prompts and tool data they preserve. Resuming creates fresh runtime resources while retaining authoritative typed history and cache lineage. They do not persist provider response IDs, so the first resumed request replays that history before subsequent turns follow the configured incremental or full-replay policy. Use RolloutConfig for the existing Codex-compatible on-disk recording and codex resume handoff; snapshots are the library-level checkpoint for application-owned restoration. Both project the same immutable committed session boundary: snapshots encode the complete native restore state, while rollouts append the Codex-specific turn envelope and only the newly committed history.

Creating and retaining that committed boundary is constant-time: forks, TurnResult, and rollout projection share the immutable typed-history prefix. Calling TurnResult::snapshot() is deliberately different. It copies the complete history into an independently serializable value, so its work and memory scale with total retained history; JSON encoding adds another content-sized pass. Treat it as a durability boundary rather than something to call after every turn unless every boundary must be retained. Rollout recording remains incremental during ordinary turns, and the first request after restoring a serialized snapshot performs the required full-history replay.

GPT-5.6 Pro is selected independently from reasoning effort; it does not use a different model slug. All six effort levels are available in either mode:

let (agent, _events) = Nanocodex::builder(api_key)
    .reasoning_mode(ReasoningMode::Pro)
    .thinking(Thinking::Xhigh) // None, Low, Medium, High, Xhigh, or Max
    .fast_mode(true) // Requests priority service.
    .build()?;

// Later turns can switch priority service without replacing the session.
agent.set_fast_mode(false).await?;

The CLI equivalents are --reasoning-mode pro --thinking xhigh, with matching OPENAI_REASONING_MODE and OPENAI_REASONING_EFFORT environment variables.

Independent agents that use the same immutable instructions and tool definitions may deliberately share only their provider-side prompt cache while retaining separate conversations, response chains, tools, and workspaces:

let (agent, _events) = Nanocodex::builder(api_key)
    .session_id(attempt_id)
    .prompt_cache_key(agent_recipe_id)
    .shared_prompt_cache()
    .build()?;

Builders cloned after shared_prompt_cache() singleflight the first warmup for each exact prefix. Later agents skip that redundant request and send their first complete generation with the shared provider cache key. The cache key is inherited by forks and clean spawned agents. Without an explicit key, every clean root or spawned agent retains its own cache identity.

Lifecycle and dataflow

NanocodexBuilder
       │
       ▼
 private agent driver ───────────────► AgentEvents
       ▲                                  side channel
       │
 Nanocodex
 cloneable conversation handle
       │
       ├── prompt(...) ──► Turn
       │                    ├── steer(...)
       │                    ├── cancel(...)
       │                    ├── control() ──► cloneable TurnControl
       │                    └── result() ──► TurnResult
       │                                         │
       ├── fork()                                │ checkpoint
       └── fork_from(&TurnResult) ◄──────────────┘

AgentHandle, supplied to tools_factory(...)
       ├── spawn()  clean child
       └── fork()   child from latest safe model/tool boundary

That is the complete ownership model. See the runnable lifecycle.rs for all of it in one file.

Authentication

Native applications can use either an OpenAI API key or a ChatGPT subscription. Existing API-key construction remains unchanged:

let (agent, events) = Nanocodex::new(api_key)?;

For a ChatGPT subscription, the bundled CLI performs an authorization-code OAuth login with PKCE and reuses Codex's credential file at $CODEX_HOME/auth.json, or ~/.codex/auth.json by default. If Codex is already logged in, no separate Nanocodex login is required:

nanocodex auth login
nanocodex auth status
nanocodex

Plain nanocodex and nanocodex run prefer an existing Codex subscription session in $CODEX_HOME/auth.json (normally ~/.codex/auth.json). If that file is absent, the CLI falls back to OPENAI_API_KEY; direct binary runs load the key from the nearest .env automatically. An explicit --api-key overrides both automatic sources, while NANOCODEX_AUTH_FILE or --auth-file selects a specific subscription file. A present but invalid auth file fails visibly instead of silently incurring API-key charges. nanocodex auth logout removes the shared file and therefore logs both Codex and Nanocodex out.

The default Responses policy depends on the selected authorization:

Authorization	Default transport	Default `store`	Default history
ChatGPT subscription	WebSocket	`false`	connection-local incremental
API key	WebSocket	`true`	stored incremental

Selecting HTTPS keeps API-key sessions stored and incremental. ChatGPT HTTPS remains store: false and automatically switches to complete client-history replay because it has no connection-local checkpoint. Explicit --store-responses and --responses-history values override these defaults when the combination is supported.

These defaults optimize the normal long-lived interactive session, where the retained WebSocket delivered warm first events in 80-151 ms versus 277-369 ms over HTTPS. HTTPS is the better explicit choice for cold or fork-heavy one-shot work: cold first events were 374-405 ms versus 587-679 ms for WebSocket, and fresh HTTPS forks reached their first event in 373-436 ms versus about 1.0-1.1 seconds for a new WebSocket. With API-key authentication, store: true also reduced three historical-fork requests by roughly 97%. Completion latency was backend-noisy, and every policy had identical token, cache, and estimated-cost behavior in this workload. See the full transport benchmark.

Library consumers own their login UX and can reuse the same managed session:

use nanocodex::{Nanocodex, load_chatgpt_auth};

let auth = load_chatgpt_auth("/path/to/.codex/auth.json")?;
let (agent, events) = Nanocodex::new(auth)?;

The shared authorization handle selects the matching Responses endpoints, attaches the account and FedRAMP routing headers, refreshes shortly before JWT expiry, reloads credentials rotated by another process, and retries one rejected request after a serialized refresh. Forks and built-in HTTP tools share that same rotating session. Browser/WASM embeddings continue to receive an already-authorized WebSocket from the host and never own refresh tokens.

Lifecycle details

Nanocodex::new installs the standard instructions, medium thinking, built-in tools, persistent WebSocket, and retry/reconnect policy. The builder can instead fix HTTPS/SSE, response storage, and full-replay policy for the agent and all of its forks. Dropping the event receiver is supported; events then become a no-op.

Callers never pass transcripts, response IDs, tool outputs, or turn IDs back to the agent. An incremental transport sends only the new delta with previous_response_id; full-replay policy transparently sends the authoritative typed history. A replacement ephemeral socket and HTTPS with store: false also replay that history.

The Responses path encodes each wire request once and rejects common non-metadata frames before attempting metadata decoding. Every streamed attempt records request and response bytes, encode/send and socket-wait time, parsing, public-event emission, typed decoding, and time to first event/output as structural tracing fields.

Queue, steer, cancel

Every prompt is an ordinary queued turn. Steering is explicit because it has different semantics: it joins one already-active turn and is sampled only between complete model responses and tool outputs. It does not create a second turn or terminal event.

Cancellation targets the same opaque unfinished turn. Cancelling queued work removes it before it reaches the model. Cancelling active work waits for model work, Code Mode cells, and shell process groups to stop, then resolves the turn as NanocodexError::TurnCancelled. Partial model or tool work is never committed; surviving queued prompts resume from the last completed checkpoint.

Call methods directly when one task owns the turn:

let turn = agent.prompt("Investigate the failing tests.").await?;
turn.steer("Prioritize deterministic failures.").await?;
let result = turn.result().await?;

Use TurnControl only when result and control ownership need to split:

use nanocodex::NanocodexError;

let turn = agent.prompt("Run a long investigation.").await?;
let control = turn.control();
let result_task = tokio::spawn(async move { turn.result().await });

control.steer("Check the integration tests first.").await?;
control.cancel().await?;
assert!(matches!(result_task.await?, Err(NanocodexError::TurnCancelled)));

Continue and fork conversations

Follow-on prompts reuse retained context automatically:

let first = agent
    .prompt("Choose one word for this project.")
    .await?
    .result()
    .await?;

let second = agent
    .prompt("Return the word you chose in uppercase.")
    .await?
    .result()
    .await?;

Each completed result is also an opaque historical checkpoint. The mainline can keep advancing while multiple branches start from different points:

let turn_2 = agent
    .prompt("Record design decision A.")
    .await?
    .result()
    .await?;

agent
    .prompt("Record later decision B.")
    .await?
    .result()
    .await?;

// The mainline may continue while both new agents are being constructed.
let mainline = agent.prompt("Continue the primary analysis.").await?;
let ((historical, _), (latest, _)) = tokio::try_join!(
    agent.fork_from(&turn_2),
    agent.fork(),
)?;

let historical_turn = historical.prompt("Explore an alternative to A.").await?;
let latest_turn = latest.prompt("Challenge our newest assumptions.").await?;
let (mainline, historical, latest) = tokio::try_join!(
    mainline.result(),
    historical_turn.result(),
    latest_turn.result(),
)?;

Why checkpoint forks are efficient

With the stored incremental policy, used by default with API-key authentication, each Nanocodex response.create request sets store: true. Once a response completes, the API can retain it as a checkpoint; Nanocodex keeps its response ID private inside the completed TurnResult. The next healthy model call sends that ID as previous_response_id plus only the new delta—the user message, steer, or tool output added since the stored response—not the transcript again.

The same mechanism makes a historical fork cheap:

prewarm       input: stable instructions/tools, store: true   → prefix response
root turn A   previous_response_id: prefix, input: A delta    → response A
root turn B   previous_response_id: A, input: B delta         → response B
fork from A   previous_response_id: A, input: branch delta    → branch response

The root remains attached to response B and continues independently. The fork gets its own driver, WebSocket, response chain, service stack, and tool runtime, but its first request references response A and uploads only the branch delta. Locally, immutable typed-history segments and stable cache lineage are shared, so constructing the branch does not copy the retained conversation either. The API still evaluates the complete logical context—and token usage reflects that context—even though the request payload carries only the delta.

The local fork remains constant-time under every transport and storage policy. What changes is its first wire request: a fresh store: false fork cannot use a durable provider checkpoint and replays its shared committed history. HTTPS with store: false also replays on every turn; a persistent WebSocket may use connection-local incremental continuation until it is replaced. Stable cache lineage is preserved in all cases.

Stored responses are an optimization, not the source of truth. Nanocodex keeps complete client-owned typed history for every checkpoint. If the provider no longer has a response ID, the retry drops previous_response_id, replays that committed history once, and then resumes delta-only requests from the new stored response. Partial or failed responses are never committed or used as fork points.

In the retained checkpoint benchmark, three concurrent branch requests sent 2,175 bytes instead of an equivalent 84,612-byte full replay—a 97.4% payload reduction. See benchmarks/fork_results.md for the live methodology, cache observations, and raw trials.

See fork_conversations.rs for a complete ten-checkpoint example with parallel historical forks and a caller-defined Tower stack.

Configure only what your application owns

The common paths remain short; factories appear only when lifecycle isolation requires them.

use std::time::Duration;

use nanocodex::{Nanocodex, Responses, Thinking};
use tower::timeout::TimeoutLayer;

let responses = Responses::builder()
    .layer(TimeoutLayer::new(Duration::from_secs(120)))
    .build();

let (agent, events) = Nanocodex::builder(api_key)
    .codex_home("/home/me/.codex")
    .instructions("You are a concise repository maintenance agent.")
    .thinking(Thinking::High)
    .workspace("/work/project")
    .tools(tools)
    .responses(responses)
    .build()?;

Configuring a Codex home loads its AGENTS.override.md or AGENTS.md before workspace-scoped project instructions. Native applications can also opt into a Codex-compatible committed-history rollout; rollout configuration implies the same Codex home. The agent session ID is also the UUID accepted by codex resume:

use nanocodex::{Nanocodex, RolloutConfig};

let (agent, events) = Nanocodex::builder(api_key)
    .rollout(RolloutConfig::new("/home/me/.codex"))
    .build()?;

println!("codex resume {}", agent.session_id());
println!("rollout: {}", agent.rollout().unwrap().path().display());
agent.flush_rollout().await?;

Recording appends Codex's model-context response items and its legacy turn and message events after each completed or cancelled turn, so both resumed model context and the visible Codex transcript are restored. Compaction uses explicit replacement-history records, and failed partial output is excluded. nanocodex resume <thread-id> discovers the same rollout beneath $CODEX_HOME/sessions (or archived_sessions) that codex resume uses and materializes its latest replacement-history boundary plus subsequent response items. No Nanocodex-specific sidecar is required, so Codex-created threads can be continued directly. Pass --prompt "..." to submit a follow-on prompt as soon as the TUI opens. The rollout writer projects the same committed session boundary exposed by TurnResult::snapshot() rather than maintaining a second conversation state. flush_rollout() retries pending writes and provides a durability barrier. Treat a resume as a single-writer handoff: release the Nanocodex session before continuing the same rollout in Codex.

Use tools_factory when a tool must spawn or fork the agent that invoked it. The factory receives a weak AgentHandle, not credentials:

let (agent, events) = Nanocodex::builder(api_key)
    .tools_factory(|handle| build_agent_tools(handle))
    .build()?;

handle.spawn() creates a clean child; handle.fork() creates a contextual child from the invoking agent. Both privately reuse the builder's credentials and policy. The application can expose these as Code Mode tools and let the model generate loops, fan-out, follow-up prompts, and synthesis without encoding a DAG in the SDK. See subagents.rs for that complete orchestration pattern.

One Tower call is one complete streamed Responses attempt. Nanocodex owns retry and reconnect policy; caller middleware can own deadlines, load shedding, tracing, metrics, and circuit breaking without creating a second retry loop. See docs/RESPONSES_TOWER.md for the boundary and ordering rules.

Tools, MCP, events, and errors

#[tool] turns an async Rust function into a typed tool and derives its input schema. Tools::builder() accepts generated or manual Tool implementations; Mcp::builder() adds deferred Streamable HTTP or stdio MCP providers. The model normally sees only Code Mode and its wait operation, then composes nested tools with generated JavaScript, including loops, conditionals, and Promise.all.

Code Mode prewarms one persistent Node host alongside the first model call and reuses it for the session. Cells receive one shared owned history snapshot; resumed waits do not copy history they cannot read. A nested shell request can extend the default outer-cell yield deadline while an explicit @exec deadline still wins. Live shell session IDs remain visible for later write_stdin calls, and stdout/stderr drains share one bounded completion deadline.

AgentEvents is an optional ordered stream independent of TurnResult. A TUI, server, notebook, or binding can consume all events, select a subset, or drop the receiver without changing prompt/result behavior. Libraries emit diagnostic tracing spans but never install a global subscriber. Nested tools that finish after a yielded cell retain their original Code Mode and model-call lineage, so the public event stream and trace hierarchy agree.

Lifecycle failures are direct NanocodexError variants. Common control flow can match TurnCancelled or TurnNotSteerable; transport and API details remain available through responses_error() and the standard Error::source chain.

Runnable API tours:

cargo run -p nanocodex-examples --bin minimal
cargo run -p nanocodex-examples --bin lifecycle
cargo run -p nanocodex-examples --bin follow-on
cargo run -p nanocodex-examples --bin custom-tool
cargo run -p nanocodex-examples --bin mcp
cargo run -p nanocodex-examples --bin fork-conversations
cargo run -p nanocodex-examples --bin subagents

CLI and repository

Install the daily-driver CLI and start it in the workspace the agent should edit:

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

# Reuse an existing Codex login, or fall back to OPENAI_API_KEY when absent.
nanocodex

# Create or explicitly select the same subscription store Codex uses.
nanocodex auth login
nanocodex --auth-file "${CODEX_HOME:-$HOME/.codex}/auth.json"

The CLI merges enabled MCP servers from ${CODEX_HOME:-$HOME/.codex}/config.toml with its deferred openaiDeveloperDocs, tempo, and cloudflare defaults. Explicit --mcp and --mcp-stdio entries take precedence over Codex config, and Codex entries take precedence over same-named defaults. Their catalogs stay out of the stable model prompt until Code Mode calls tool_search. Disable the built-in set with --mcp-defaults false and Codex config loading with --mcp-codex-config false; the environment equivalents are NANOCODEX_MCP_DEFAULTS=false and NANOCODEX_MCP_CODEX_CONFIG=false. Streamable HTTP servers also reuse Codex's file-backed MCP OAuth credentials. Expired access tokens refresh through the server's OAuth metadata and rotated credentials are persisted back to .credentials.json under the same cross-process lock as Codex.

Provider prewarming is scheduled before agent construction returns, so the TUI does not wait for HTTP client setup, DNS/TLS, MCP handshakes, tools/list, or BM25 indexing. Discovery and index construction run in parallel in the background while the terminal is idle. Activating a deferred tool changes only the nested Code Mode runtime; the model-visible exec/tool_search prefix stays byte-stable for prompt-cache reuse.

The CLI records Codex-compatible rollouts beneath ${CODEX_HOME:-$HOME/.codex}/sessions by default. The request_id in headless JSONL is the resumable UUID. Restore its workspace, committed typed history, and rollout identity in Nanocodex with:

nanocodex resume <request_id>
nanocodex resume <request_id> --prompt "Continue where we left off"

Or hand the interoperable rollout to Codex:

nanocodex run "Remember this thread"
codex resume <request_id>

Use nanocodex --rollouts false ... (or NANOCODEX_ROLLOUTS=false) when a CLI consumer does not want local session recording.

The TUI retains one session across prompts. Enter submits, Tab explicitly queues a follow-up while work is active, and /cancel stops the focused turn. At any safe model/tool boundary, /btw <question> opens a fast fork in a vertical pane while the mainline continues. The fork inherits the last completed response ID plus complete tool results and applied steers after that response; partial model output and unmatched tool calls remain excluded. With local telemetry running, /trace opens Jaeger filtered to every turn in the focused main or /btw session. /mcp login <server> opens browser OAuth and hot-reloads that server's tools into the running session after the callback; /mcp reload <server> retries discovery without restarting the TUI. The complete keybinding reference, retained Amp and Codex research, and prioritized Ratatui backlog live in docs/TUI_NOTES.md. The headless nanocodex run adapter emits flushed JSONL for scripts and Harbor.

just run-otel exports compact per-turn streaming summaries alongside the full agent trace. When diagnosing a jagged stream, opt into the individual correlated API-delta, TUI-application, and presented-frame records:

just run-otel-detail

The TUI log at .nanocodex/logs/tui.log correlates each request and event across socket receipt, agent emission, TUI receipt, state application, frame coalescing, Ratatui changed cells, terminal output bytes, and final flush. Detailed mode is intentionally opt-in because long responses can create thousands of records. Use just bench-stream for the focused event-delivery, transcript-update, and steady-frame regression gate. See docs/OBSERVABILITY.md for the full trace contract.

The workspace also contains publishable JavaScript and Python libraries plus thin Node, browser Worker, and website consumers. Architecture and current work are tracked in PLAN.md; benchmark runner research lives in docs/HARBOR_RS_LOG.md.

# Install pinned host dependencies.
just bootstrap
# Run the native smoke test.
just run
# Build and cache benchmark inputs.
just prepare-evals
# Run the pinned Terminal-Bench suite.
just eval
# Inspect retained Harbor jobs.
just view

Nanocodex versus Codex

Use Nanocodex when the agent is a component of your Rust application. Use Codex when you want the complete product: durable threads, approval UX, broad built-in integrations, managed subagents, and a mature TUI and IDE ecosystem.

	Nanocodex	Codex
Product boundary	Rust library in your process	Application and durable agent runtime
State	In-memory authority; optional Codex-compatible rollout	Persisted threads and rollouts
Follow-on turns	Fixed WebSocket or HTTPS policy; automatic delta or full replay	Full Codex session lifecycle
Historical forks	Exact completed checkpoint; parent keeps running	Durable thread reconstruction
Tools	Code Mode over Rust tools and MCP	Broad built-in tool and integration surface
Middleware	Your concrete Tower stack	Codex-owned runtime policy
Results and events	Typed `TurnResult` plus optional ordered `AgentEvents`	Product-wide rollout/event lifecycle
Orchestration	Model composes application-defined agent tools	Managed agents, task identities, mailboxes, and budgets

The smaller boundary is the feature. A caller builds an agent, receives (Nanocodex, AgentEvents), sends prompts through a cheap cloneable handle, and awaits independently owned TurnResults. The CLI, Harbor adapter, Python binding, and Rust/WASM binding all consume that same API.

Codex request parity

The deterministic differential drives stock Codex and Nanocodex through basic tools, continued PTY shells, bounded output, failures, images, WebSocket reconnect/replay, automatic compaction, and SIGINT cleanup:

cargo build -p nanocodex-bin
python3 benchmarks/codex_request_parity.py \
  --codex-bin ~/github/openai/codex/codex-rs/target/debug/codex \
  --nanocodex-bin target/debug/nanocodex \
  --output /tmp/nanocodex-request-parity.json

The default command succeeds when both implementations complete every scenario, preserve stable request identity, replay or compact complete history, and clean up cancelled descendants. Add --check when exact normalized request and transport equality is required; it currently reports the documented WebSocket-to-HTTPS fallback. App-owned internal turn metadata is an explicit normalization exclusion. Use repeated --scenario <name> flags to run only selected cases.

Nanocodex deliberately defaults to Thinking::High; stock Codex currently defaults the bundled Sol model to low. The differential passes the same explicit effort to both binaries so it tests harness behavior rather than that product-policy choice.

How Fast?

Focused local profiling also covers the ordinary streaming and tool path. On an M1 Max, prewarming the retained Node host reduced first-cell host latency from 301 ms to 1.7–2.7 ms and complete top-level Code Mode time from 312 ms to 11–13 ms across three trials. On a retained 41-task workload, model generation and caller-requested subprocesses accounted for 99.864% of summed run time; the unattributed local remainder was 0.136%. These are diagnostic measurements, not model-service speed guarantees. See single_prompt_profile_2026-07-20.md and long_prompt_profile_2026-07-20.md for methodology and reproduction commands.

The committed-history benchmark on the current session/rollout implementation kept an active checkpoint plus parent append at 0.369–0.394 µs from 100 through 10,000 retained items. Iterating only the next request suffix stayed near 26 ns. The full-history flattening component required by an explicit durable snapshot scaled from 8.2 µs at 100 items to 92 µs at 1,000 and 992 µs at 10,000. Those synthetic items contain about 512 bytes of text each; the flattening numbers exclude JSON encoding. See the transport benchmark for the table and interpretation.

Our live checkpoint benchmark uses gpt-5.6-sol, a deterministic 600-fact prefix, ten sequential turns, and concurrent historical forks. Three runs on 2026-07-20 compared Nanocodex 210ac85 with stock Codex CLI 0.145.0-alpha.18:

Measurement	Nanocodex	Stock Codex	Difference
Ten sequential turns, median total	14.78 s	24.99 s	1.69x faster
Warm turn p50, turns 3–10	1.304 s	1.532 s	1.18x faster
Historical fork to first answer, p50	1.570 s	6.530 s	4.16x faster
Historical fork model time, p50	1.291 s	5.862 s	4.54x faster

Takeaway: Nanocodex was 1.69x faster across ten turns and 4.16x faster to the first historical-fork answer in this checkpoint benchmark.

A Nanocodex fork sent about 725 bytes of new request data from its stored checkpoint. Replaying the same history would send 27–29 KB: a 97.4% reduction. On a separate 41-task coding gate, Nanocodex completed 38 tasks with 92.23% of input tokens cached, zero Responses retries, and zero WebSocket reconnects.

These are checkpoint-path measurements, not a normalized full-agent quality comparison. The Nanocodex arm used a minimal benchmark developer message and no production tool definitions; the Codex arm ran the complete stock app-server agent. See benchmarks/fork_results.md for the methodology, cache observations, raw trials, and reproduction commands.

The tradeoff

Nanocodex currently supports one model family (gpt-5.6-sol), one Responses WebSocket transport, and caller-defined tools. Sessions and branches live only as long as your process. Your application owns sandboxing, permissions, durability, and recursive cancellation policy for application-defined child agents. Code Mode requires Node.js 12.22 or newer on PATH.

That is substantially less product than Codex. It is also much less machinery between your code and an agent turn.