# nanocode

The Rust SDK facade: one crate that builds a runtime, spawns agents, and runs turns on the Codex and Claude harnesses.

The `nanocode` crate re-exports the runtime, the agent handle, the tool builders, both provider clients, the durability stores, and the remote hand. Native targets also get runner, computer-use, and JSONL store exports. A `wasm32` build of the same crate leaves those out.

## Install

The crate is a git dependency from the nanocode repository. Agents run on Tokio, and `build_async` fails without an active Tokio runtime.

```toml title="Cargo.toml"
[dependencies]
# The SDK facade, from the nanocode repository
nanocode = { git = "https://github.com/gakonst/nanocode" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

## Example

```rust title="main.rs"
use nanocode::{
    Claude, ClaudeClient, ClaudeModel, Nanocode, OpenAi, Thinking,
    Tools,
};

type Result<T> =
    std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Build a runtime with both harnesses and no default tools
    let runtime = Nanocode::builder()
        .openai(OpenAi::default())
        .claude(ClaudeClient::default())
        .tools(Tools::builder().without_defaults().build()?)
        .without_cua()
        .runner_management(false)
        .thinking(Thinking::Low)
        .build_async()
        .await?;

    // 2. Spawn an agent on a Claude model
    let (agent, _events) = runtime
        .spawn()
        .backend::<Claude>()
        .model(ClaudeModel::Haiku55)
        .build()
        .await?;

    // 3. Run one turn and print its final message
    let turn = agent
        .prompt("Explain durable agents in two sentences.")
        .await?;
    println!("{}", turn.await?.final_message());

    // 4. Wait for durable writes, then stop the runtime
    agent.flush().await?;
    runtime.shutdown().await?;
    Ok(())
}
```

## Runtime

- [Nanocode](/docs/api/rust/Nanocode): The runtime type and its builder.

- [SpawnBuilder](/docs/api/rust/SpawnBuilder): Select the harness, model, and settings of a new agent.

- [Agent](/docs/api/rust/Agent): The handle that prompts, checkpoints, forks, and stops one session.

- [Turn](/docs/api/rust/Turn): One running turn, its control handle, and its result.

## Tools

- [Tools](/docs/api/rust/Tools): The tool catalog builder and tool exposure.

- [#[tool]](/docs/api/rust/tool-macro): Turn an async function into a typed tool.

- [FunctionTool](/docs/api/rust/FunctionTool): A tool with a JSON Schema and a dynamic handler.

## Providers

- [OpenAi](/docs/api/rust/OpenAi): The OpenAI client for the Codex harness.

- [ClaudeClient](/docs/api/rust/ClaudeClient): The Anthropic Messages client and the Claude harness.

- [ResponsesGateway](/docs/api/rust/ResponsesGateway): Route the Codex harness through a Responses API gateway.

## Durability

- [session_store](/docs/api/rust/session_store): Session stores for journaled, resumable sessions.

## Hands

- [hand](/docs/api/rust/hand): Run Code Mode cells and tools on another machine.

## Reference

- [Models and Types](/docs/api/rust/types): Models, thinking levels, service tiers, errors, and usage.

## Other Exports

| Export                            | Contents                                                                                                                                     |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent`                           | Agent-level types such as `SpawnOptions`, `AgentHandle`, `CodexBuilder`, and the `events`, `input`, `session`, and `usage` modules.          |
| `backend`                         | The backend contract for third-party harnesses: `BackendRegistration`, `AgentToolsFactory`, `CheckpointFormat`, and the tool contract types. |
| `claude`                          | The Claude backend crate, including `ClaudeBuilder` and its lifecycle and tool hooks.                                                        |
| `claude_tools`                    | Claude's built-in tools.                                                                                                                     |
| `codex`, `oai`                    | The OpenAI client crate, including `auth::OpenAiAuth` and `transport::ResponsesGateway`.                                                     |
| `codex_tools`                     | Codex's built-in tools.                                                                                                                      |
| `code_mode`, `tools`, `oai_tools` | The tool host: `Tools`, `ToolExposure`, `WorkspaceTools`, Code Mode runtimes, and, on native targets, `mcp`, `remote`, and `shell`.          |
| `cua`                             | Computer-use tools, with `ComputerConfig` and `ComputerTools` at the root. Native only.                                                      |
| `durability`                      | The durable state machine and stores: `SessionStore`, `MemoryStore`, `KeyValueStore`, `SqlStore`, and `StateStore`.                          |
| `http`                            | The HTTP layer trait for the OpenAI transport.                                                                                               |
| `platform`                        | Platform helpers such as UUID generation.                                                                                                    |
| `prelude`                         | The common imports: `Nanocode`, `Agent`, `Tools`, `tool`, both clients, the model types, and the stores.                                     |
| `runners`                         | Runner pools, servers, and attachment. Native only.                                                                                          |
| `session_host`                    | The session log and turn inbox for hosts that queue turns: `SessionLog`, `TurnInbox`, `InboxHost`, and `TurnRecord`.                         |
| `subagents`                       | Subagent orchestration: `SubagentControl`, `AgentUpdate`, and `AgentStatus`.                                                                 |
| `tool_contract`                   | The tool contract: `Tool`, `ToolContext`, `ToolInput`, and `ToolCollection`.                                                                 |
| `AgentEvents`                     | The event stream of an agent or a turn.                                                                                                      |
| `Backend`                         | `BackendRegistration`, the trait a third-party harness implements for `builder.backend`.                                                     |
| `Claude`, `Codex`                 | The backend kinds for `SpawnBuilder.backend` and `builder.for_backend`.                                                                      |
| `ClaudeHarness`, `CodexHarness`   | The harnesses that `builder.claude` and `builder.openai` install.                                                                            |
| `ForkRequest`                     | Where `Agent.fork` branches: `latest`, `at_turn`, or `at` a checkpoint.                                                                      |
| `JsonlStore`                      | The append-only JSONL session store. Native only.                                                                                            |
| `PromptMessage`                   | One message of a transcript.                                                                                                                 |
| `Runner`, `RunnerServerConfig`    | A hand that the runtime dials, or an address where it accepts hands. Native only.                                                            |
| `SubagentUpdates`                 | The receiver that `take_subagent_updates` returns.                                                                                           |