[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93600":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":16,"compositeScore":17,"rankGlobal":8,"rankLanguage":8,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":8,"pushedAt":8,"updatedAt":22,"readmeContent":23,"aiSummary":8,"trendingCount":14,"starSnapshotCount":14,"syncStatus":12,"lastSyncTime":24,"discoverSource":25},93600,"nanocodex","gakonst\u002Fnanocodex","gakonst",null,"Rust",137,10,2,1,0,26,78,75.72,"Apache License 2.0",false,"master",[],"2026-07-22 04:02:09","\u003Cdiv align=\"center\">\n\n\u003Ch1>Nanocodex\u003C\u002Fh1>\n\n\u003Cp>\u003Cstrong>Blazing-fast, minimal, library-first reimplementation of Codex.\u003C\u002Fstrong>\u003C\u002Fp>\n\n[![CI](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fgakonst\u002Fnanocodex\u002Fci.yml?branch=master)][ci]\n[![Crates.io](https:\u002F\u002Fimg.shields.io\u002Fcrates\u002Fv\u002Fnanocodex.svg)][crates]\n[![Docs.rs](https:\u002F\u002Fimg.shields.io\u002Fdocsrs\u002Fnanocodex)][docs]\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT%20OR%20Apache--2.0-blue.svg)][license]\n\n**[API](#api)** | **[Install](#installation)** | **[Examples](examples)** | **[Benchmarks](#how-fast)**\n\n[ci]: https:\u002F\u002Fgithub.com\u002Fgakonst\u002Fnanocodex\u002Factions\u002Fworkflows\u002Fci.yml\n[crates]: https:\u002F\u002Fcrates.io\u002Fcrates\u002Fnanocodex\n[docs]: https:\u002F\u002Fdocs.rs\u002Fnanocodex\n[license]: LICENSE-MIT\n\n\u003C\u002Fdiv>\n\n---\n\nNanocodex provides typed turns, tools, events, steering, cancellation, queueing,\nand fast historical forks over the OpenAI Responses WebSocket API. It keeps the\ncomplete coding-agent conversation inside your process without requiring an app\nserver or durable control plane.\n\n## API\n\n```rust\nlet (agent, _events) = Nanocodex::new(api_key)?;\n\n\u002F\u002F Accepted now.\nlet turn = agent.prompt(\"Inspect this repository.\").await?;\n\u002F\u002F Optional cloneable control.\nlet _control = turn.control();\n\u002F\u002F Steer the same active turn.\nturn.steer(\"Focus on the failing tests.\").await?;\n\u002F\u002F Completed result and checkpoint.\nlet checkpoint = turn.result().await?;\n\nlet _follow_on = agent.prompt(\"Now propose a fix.\").await?.result().await?;\n\nlet turn = agent.prompt(\"Run a long investigation.\").await?;\n\u002F\u002F Cancel queued or active work.\nturn.cancel().await?;\n\u002F\u002F Returns Err(TurnCancelled).\nlet _cancelled = turn.result().await;\n\n\u002F\u002F Fork from the latest safe model\u002Ftool boundary.\nlet (latest, _events) = agent.fork().await?;\n\u002F\u002F Fork from the exact older state.\nlet (historical, _events) = agent.fork_from(&checkpoint).await?;\n```\n\n`prompt().await` means accepted, not completed. The agent retains conversation\nhistory, tools, cache identity, response chain, and its WebSocket automatically.\n\n### Lifecycle and dataflow\n\n```text\nNanocodexBuilder\n       │\n       ▼\n private agent driver ───────────────► AgentEvents\n       ▲                                  side channel\n       │\n Nanocodex\n cloneable conversation handle\n       │\n       ├── prompt(...) ──► Turn\n       │                    ├── steer(...)\n       │                    ├── cancel(...)\n       │                    ├── control() ──► cloneable TurnControl\n       │                    └── result() ──► TurnResult\n       │                                         │\n       ├── fork()                                │ checkpoint\n       └── fork_from(&TurnResult) ◄──────────────┘\n\nAgentHandle, supplied to tools_factory(...)\n       ├── spawn()  clean child\n       └── fork()   child from latest safe model\u002Ftool boundary\n```\n\nThat is the complete ownership model. See the runnable\n[`lifecycle.rs`](examples\u002Flifecycle.rs) for all of it in one file.\n\n## Installation\n\nMost applications need only the top-level crate:\n\n```toml\n[dependencies]\nnanocodex = \"0.1\"\ntokio = { version = \"1\", features = [\"macros\", \"rt-multi-thread\"] }\n```\n\nNode.js 12.22 or newer must be available on `PATH` for Code Mode.\n\n### Authentication\n\nNative applications can use either an `OpenAI` API key or a `ChatGPT`\nsubscription. Existing API-key construction remains unchanged:\n\n```rust\nlet (agent, events) = Nanocodex::new(api_key)?;\n```\n\nFor a `ChatGPT` subscription, the bundled CLI performs an authorization-code\nOAuth login with PKCE and reuses Codex's credential file at\n`$CODEX_HOME\u002Fauth.json`, or `~\u002F.codex\u002Fauth.json` by default. If Codex is already\nlogged in, no separate Nanocodex login is required:\n\n```sh\nnanocodex auth login\nnanocodex auth status\nnanocodex --chatgpt\n```\n\n`OPENAI_API_KEY` or `--api-key` takes precedence by default; `--chatgpt` (or\n`NANOCODEX_CHATGPT=true`) explicitly selects the subscription session. Override\nthe credential file with `NANOCODEX_AUTH_FILE` or `--auth-file`. `nanocodex auth\nlogout` removes the shared file and therefore logs both Codex and Nanocodex out.\n\nLibrary consumers own their login UX and can reuse the same managed session:\n\n```rust\nuse nanocodex::{Nanocodex, load_chatgpt_auth};\n\nlet auth = load_chatgpt_auth(\"\u002Fpath\u002Fto\u002F.codex\u002Fauth.json\")?;\nlet (agent, events) = Nanocodex::new(auth)?;\n```\n\nThe shared authorization handle selects the matching Responses endpoints,\nattaches the account and FedRAMP routing headers, refreshes shortly before JWT\nexpiry, reloads credentials rotated by another process, and retries one rejected\nrequest after a serialized refresh. Forks and built-in HTTP tools share that\nsame rotating session. Browser\u002FWASM embeddings continue to receive an\nalready-authorized WebSocket from the host and never own refresh tokens.\n\n## Lifecycle details\n\n`Nanocodex::new` installs the standard instructions, medium thinking, built-in\ntools, persistent WebSocket, and retry\u002Freconnect policy. Dropping the event\nreceiver is supported; events then become a no-op.\n\nCallers never pass transcripts, response IDs, tool outputs, or turn IDs back to\nthe agent. On a healthy socket the driver sends only the new delta with\n`previous_response_id`. After reconnecting it drops that ID and transparently\nreplays its authoritative typed history.\n\n### Queue, steer, cancel\n\nEvery `prompt` is an ordinary queued turn. Steering is explicit because it has\ndifferent semantics: it joins one already-active turn and is sampled only\nbetween complete model responses and tool outputs. It does not create a second\nturn or terminal event.\n\nCancellation targets the same opaque unfinished turn. Cancelling queued work\nremoves it before it reaches the model. Cancelling active work waits for model\nwork, Code Mode cells, and shell process groups to stop, then resolves the turn\nas `NanocodexError::TurnCancelled`. Partial model or tool work is never\ncommitted; surviving queued prompts resume from the last completed checkpoint.\n\nCall methods directly when one task owns the turn:\n\n```rust\nlet turn = agent.prompt(\"Investigate the failing tests.\").await?;\nturn.steer(\"Prioritize deterministic failures.\").await?;\nlet result = turn.result().await?;\n```\n\nUse `TurnControl` only when result and control ownership need to split:\n\n```rust\nuse nanocodex::NanocodexError;\n\nlet turn = agent.prompt(\"Run a long investigation.\").await?;\nlet control = turn.control();\nlet result_task = tokio::spawn(async move { turn.result().await });\n\ncontrol.steer(\"Check the integration tests first.\").await?;\ncontrol.cancel().await?;\nassert!(matches!(result_task.await?, Err(NanocodexError::TurnCancelled)));\n```\n\n### Continue and fork conversations\n\nFollow-on prompts reuse retained context automatically:\n\n```rust\nlet first = agent\n    .prompt(\"Choose one word for this project.\")\n    .await?\n    .result()\n    .await?;\n\nlet second = agent\n    .prompt(\"Return the word you chose in uppercase.\")\n    .await?\n    .result()\n    .await?;\n```\n\nEach completed result is also an opaque historical checkpoint. The mainline can\nkeep advancing while multiple branches start from different points:\n\n```rust\nlet turn_2 = agent\n    .prompt(\"Record design decision A.\")\n    .await?\n    .result()\n    .await?;\n\nagent\n    .prompt(\"Record later decision B.\")\n    .await?\n    .result()\n    .await?;\n\n\u002F\u002F The mainline may continue while both new agents are being constructed.\nlet mainline = agent.prompt(\"Continue the primary analysis.\").await?;\nlet ((historical, _), (latest, _)) = tokio::try_join!(\n    agent.fork_from(&turn_2),\n    agent.fork(),\n)?;\n\nlet historical_turn = historical.prompt(\"Explore an alternative to A.\").await?;\nlet latest_turn = latest.prompt(\"Challenge our newest assumptions.\").await?;\nlet (mainline, historical, latest) = tokio::try_join!(\n    mainline.result(),\n    historical_turn.result(),\n    latest_turn.result(),\n)?;\n```\n\nForks contain only committed work. Each child gets a new driver, WebSocket,\nresponse chain, service stack, and tool runtime. Immutable typed history and\ncache lineage are shared. If a provider checkpoint has expired, Nanocodex\nreplays committed history once and then returns to incremental requests.\n\nSee [`fork_conversations.rs`](examples\u002Ffork_conversations.rs) for a complete\nten-checkpoint example with parallel historical forks and a caller-defined\nTower stack.\n\n### Configure only what your application owns\n\nThe common paths remain short; factories appear only when lifecycle isolation\nrequires them.\n\n```rust\nuse std::time::Duration;\n\nuse nanocodex::{Nanocodex, Responses, Thinking};\nuse tower::timeout::TimeoutLayer;\n\nlet responses = Responses::builder()\n    .layer(TimeoutLayer::new(Duration::from_secs(120)))\n    .build();\n\nlet (agent, events) = Nanocodex::builder(api_key)\n    .instructions(\"You are a concise repository maintenance agent.\")\n    .thinking(Thinking::Medium)\n    .workspace(\"\u002Fwork\u002Fproject\")\n    .tools(tools)\n    .responses(responses)\n    .build()?;\n```\n\nUse `tools_factory` when a tool must spawn or fork the agent that invoked it.\nThe factory receives a weak `AgentHandle`, not credentials:\n\n```rust\nlet (agent, events) = Nanocodex::builder(api_key)\n    .tools_factory(|handle| build_agent_tools(handle))\n    .build()?;\n```\n\n`handle.spawn()` creates a clean child; `handle.fork()` creates a contextual\nchild from the invoking agent. Both privately reuse the builder's credentials\nand policy. The application can expose these as Code Mode tools and let the\nmodel generate loops, fan-out, follow-up prompts, and synthesis without encoding\na DAG in the SDK. See [`subagents.rs`](examples\u002Fsubagents.rs) for that complete\norchestration pattern.\n\nOne Tower call is one complete streamed Responses attempt. Nanocodex owns retry\nand reconnect policy; caller middleware can own deadlines, load shedding,\ntracing, metrics, and circuit breaking without creating a second retry loop.\nSee [`docs\u002FRESPONSES_TOWER.md`](docs\u002FRESPONSES_TOWER.md) for the boundary and\nordering rules.\n\n### Tools, MCP, events, and errors\n\n`#[tool]` turns an async Rust function into a typed tool and derives its input\nschema. `Tools::builder()` accepts generated or manual `Tool` implementations;\n`Mcp::builder()` adds deferred Streamable HTTP or stdio MCP providers. The model\nnormally sees only Code Mode and its wait operation, then composes nested tools\nwith generated JavaScript, including loops, conditionals, and `Promise.all`.\n\n`AgentEvents` is an optional ordered stream independent of `TurnResult`. A TUI,\nserver, notebook, or binding can consume all events, select a subset, or drop\nthe receiver without changing prompt\u002Fresult behavior. Libraries emit diagnostic\n`tracing` spans but never install a global subscriber.\n\nLifecycle failures are direct `NanocodexError` variants. Common control flow can\nmatch `TurnCancelled` or `TurnNotSteerable`; transport and API details remain\navailable through `responses_error()` and the standard `Error::source` chain.\n\nRunnable API tours:\n\n```sh\ncargo run -p nanocodex-examples --bin minimal\ncargo run -p nanocodex-examples --bin lifecycle\ncargo run -p nanocodex-examples --bin follow-on\ncargo run -p nanocodex-examples --bin custom-tool\ncargo run -p nanocodex-examples --bin mcp\ncargo run -p nanocodex-examples --bin fork-conversations\ncargo run -p nanocodex-examples --bin subagents\n```\n\n## CLI and repository\n\nInstall the daily-driver CLI and start it in the workspace the agent should\nedit:\n\n```sh\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fgakonst\u002Fnanocodex\u002Fmaster\u002Finstall | bash\nexport OPENAI_API_KEY=...\nnanocodex\n```\n\nThe TUI retains one session across prompts. Enter submits, Tab explicitly queues\na follow-up while work is active, and `\u002Fcancel` stops the focused turn. At any\nsafe model\u002Ftool boundary, `\u002Fbtw \u003Cquestion>` opens a fast fork in a vertical pane\nwhile the mainline continues. The fork inherits the last completed response ID\nplus complete tool results and applied steers after that response; partial model\noutput and unmatched tool calls remain excluded. With local telemetry running,\n`\u002Ftrace` opens Jaeger filtered to every turn in the focused main or `\u002Fbtw`\nsession. The complete keybinding reference, retained Amp and Codex research, and\nprioritized Ratatui backlog live in\n[`docs\u002FTUI_NOTES.md`](docs\u002FTUI_NOTES.md). The headless `nanocodex run` adapter\nemits flushed JSONL for scripts and Harbor.\n\nTo measure streaming cadence without recording response text, enable the shared\ntransport\u002FTUI timing target and JSON logs:\n\n```sh\nnanocodex --log-format json \\\n  --log-filter 'warn,nanocodex=info,nanocodex_service=info,nanocodex_stream_timing=trace'\n```\n\nThe TUI log at `.nanocodex\u002Flogs\u002Ftui.log` then correlates each event's request ID\nand sequence across `api_delta_emitted`, `tui_event_received`,\n`tui_event_applied`, and `frame_presented`. Frame records include coalesced delta\ncount, payload byte count, render time, and first\u002Flast-event-to-presentation\nlatency; prompt and response bodies are never logged.\n\nThe workspace also contains thin [Python](bindings\u002Fpython),\n[Node](examples\u002Fnode), and [browser Worker](examples\u002Freact-vite) consumers.\nArchitecture and current work are tracked in [`PLAN.md`](PLAN.md); benchmark\nrunner research lives in [`docs\u002FHARBOR_RS_LOG.md`](docs\u002FHARBOR_RS_LOG.md).\n\n```sh\n# Install pinned host dependencies.\njust bootstrap\n# Run the native smoke test.\njust run\n# Build and cache benchmark inputs.\njust prepare-evals\n# Run the pinned Terminal-Bench suite.\njust eval\n# Inspect retained Harbor jobs.\njust view\n```\n\n## Nanocodex versus Codex\n\nUse Nanocodex when the agent is a component of your Rust application. Use Codex\nwhen you want the complete product: durable threads, approval UX, broad built-in\nintegrations, managed subagents, and a mature TUI and IDE ecosystem.\n\n| | Nanocodex | Codex |\n| --- | --- | --- |\n| Product boundary | Rust library in your process | Application and durable agent runtime |\n| State | One owned in-memory session | Persisted threads and rollouts |\n| Follow-on turns | New input delta on one persistent WebSocket | Full Codex session lifecycle |\n| Historical forks | Exact completed checkpoint; parent keeps running | Durable thread reconstruction |\n| Tools | Code Mode over Rust tools and MCP | Broad built-in tool and integration surface |\n| Middleware | Your concrete Tower stack | Codex-owned runtime policy |\n| Results and events | Typed `TurnResult` plus optional ordered `AgentEvents` | Product-wide rollout\u002Fevent lifecycle |\n| Orchestration | Model composes application-defined agent tools | Managed agents, task identities, mailboxes, and budgets |\n\nThe smaller boundary is the feature. A caller builds an agent, receives\n`(Nanocodex, AgentEvents)`, sends prompts through a cheap cloneable handle, and\nawaits independently owned `TurnResult`s. The CLI, Harbor adapter, Python\nbinding, and Rust\u002FWASM binding all consume that same API.\n\n### How Fast?\n\nOur live checkpoint benchmark uses `gpt-5.6-sol`, a deterministic 600-fact\nprefix, ten sequential turns, and concurrent historical forks. Three runs on\n2026-07-20 compared Nanocodex `210ac85` with stock Codex CLI\n`0.145.0-alpha.18`:\n\n| Measurement | Nanocodex | Stock Codex | Difference |\n| --- | ---: | ---: | ---: |\n| Ten sequential turns, median total | 14.78 s | 24.99 s | **1.69x faster** |\n| Warm turn p50, turns 3–10 | 1.304 s | 1.532 s | **1.18x faster** |\n| Historical fork to first answer, p50 | 1.570 s | 6.530 s | **4.16x faster** |\n| Historical fork model time, p50 | 1.291 s | 5.862 s | **4.54x faster** |\n\n**Takeaway: Nanocodex was 1.69x faster across ten turns and 4.16x faster to\nthe first historical-fork answer in this checkpoint benchmark.**\n\nA Nanocodex fork sent about 725 bytes of new request data from its stored\ncheckpoint. Replaying the same history would send 27–29 KB: a 97.4% reduction.\nOn a separate 41-task coding gate, Nanocodex completed 38 tasks with 92.23% of\ninput tokens cached, zero Responses retries, and zero WebSocket reconnects.\n\nThese are checkpoint-path measurements, not a normalized full-agent quality\ncomparison. The Nanocodex arm used a minimal benchmark developer message and no\nproduction tool definitions; the Codex arm ran the complete stock app-server\nagent. See [`benchmarks\u002Ffork_results.md`](benchmarks\u002Ffork_results.md) for the\nmethodology, cache observations, raw trials, and reproduction commands.\n\n### The tradeoff\n\nNanocodex currently supports one model family (`gpt-5.6-sol`), one Responses\nWebSocket transport, and caller-defined tools. Sessions and branches live only\nas long as your process. Your application owns sandboxing, permissions,\ndurability, and recursive cancellation policy for application-defined child\nagents. Code Mode requires Node.js 12.22 or newer on `PATH`.\n\nThat is substantially less product than Codex. It is also much less machinery\nbetween your code and an agent turn.\n","2026-07-21 02:30:08","CREATED_QUERY"]