# nanocodexyz/nanocode architecture

> Architecture diagram of the GitHub repository nanocodexyz/nanocode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nanocodexyz/nanocode
- Repository: https://github.com/nanocodexyz/nanocode

## Overview

Nanocode is a Rust SDK and CLI for embedded frontier-model agents. The main user flow is to submit a prompt through a host or CLI, run it through a Codex or Claude harness, invoke tools (including remote “hands” when needed), and return results while journaling calls for durability. The README also highlights Code Mode, subagents, and multiple payer options. Edges use README-documented capabilities or SOURCE INDEX references; unsampled subsystem internals and wiring are not inferred.

Main entry points: [`crates/runtime/agent/src/runtime.rs`](https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/agent/src/runtime.rs) (Agent runtime), [`bin/nanocode-sim/src/host.rs`](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/host.rs) (Simulated host), [`bin/nanocode/src/app.rs`](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode/src/app.rs) (Interactive app), [`bin/nanocode/src/main.rs`](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode/src/main.rs) (Nanocode CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entrypoints"]
  node_cli["Nanocode CLI<br/>[main.rs]"]
  node_lite["Lite CLI<br/>[main.rs]"]
  node_front["Front host<br/>[main.rs]"]
  node_app["Interactive app<br/>[app.rs]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent runtime<br/>[runtime.rs]"]
  node_router["Agent router<br/>[router.rs]"]
  node_durability[("Durable sessions<br/>[session.rs]")]
  node_events["Agent events<br/>[events.rs]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tools["Tool execution<br/>[standard.rs]"]
  node_code_mode["Code Mode<br/>[client.rs]"]
  node_remote_hand["Remote hands<br/>[hand.rs]"]
  node_subagents["Subagents<br/>[routing.rs]"]
  node_computer["Computer integration<br/>[engine.rs]"]
end

subgraph group_providers["Models and payers"]
  node_codex["Codex harness<br/>[mod.rs]"]
  node_claude["Claude harness<br/>[driver.rs]"]
  node_model_services["Model services"]
  node_payer["Payer options<br/>[chatgpt.rs]"]
end

subgraph group_simulation["Simulation runtime"]
  node_sim_host["Simulated host<br/>[host.rs]"]
  node_sim_executor["Sim executor<br/>[executor.rs]"]
  node_sim_egress["Sim egress<br/>[egress.rs]"]
  node_sim_rng["Sim random<br/>[rng.rs]"]
  node_sim_streams["Sim streams<br/>[streams.rs]"]
  node_sim_turns["Sim turns<br/>[turns.rs]"]
end

node_user(("User"))

node_user -->|"submits prompt"| node_cli
node_user -->|"submits prompt"| node_lite
node_cli -->|"runs agent"| node_agent
node_lite -->|"runs agent"| node_agent
node_front -.->|"hosts runtime"| node_agent
node_agent -->|"selects harness"| node_codex
node_agent -->|"selects harness"| node_claude
node_codex -.->|"calls model"| node_model_services
node_claude -.->|"calls model"| node_model_services
node_agent -->|"invokes tools"| node_tools
node_agent -->|"journals calls"| node_durability
node_agent -->|"runs program"| node_code_mode
node_code_mode -->|"calls tools"| node_tools
node_agent -->|"dispatches calls"| node_remote_hand
node_agent -->|"spawns sessions"| node_subagents
node_agent -->|"uses payer"| node_payer
node_payer -.->|"funds requests"| node_model_services
node_app -.->|"submits turns"| node_agent
node_app -->|"handles events"| node_events
node_agent -.->|"emits events"| node_events
node_remote_hand -.->|"uses computer"| node_computer
node_sim_host -->|"derives randomness"| node_sim_rng
node_sim_host -->|"queues futures"| node_sim_executor
node_sim_egress -->|"uses host"| node_sim_host

click node_cli "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode/src/main.rs"
click node_lite "https://github.com/nanocodexyz/nanocode/blob/master/bin/nc-lite/src/main.rs"
click node_front "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-front/src/main.rs"
click node_app "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode/src/app.rs"
click node_agent "https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/agent/src/runtime.rs"
click node_router "https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/agent/src/router.rs"
click node_durability "https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/durability/src/session.rs"
click node_codex "https://github.com/nanocodexyz/nanocode/blob/master/crates/backends/codex/src/agent/driver/mod.rs"
click node_claude "https://github.com/nanocodexyz/nanocode/blob/master/crates/backends/claude/src/agent/driver.rs"
click node_payer "https://github.com/nanocodexyz/nanocode/blob/master/crates/backends/codex/client/src/auth/chatgpt.rs"
click node_tools "https://github.com/nanocodexyz/nanocode/blob/master/crates/backends/codex/src/builtin_tools/standard.rs"
click node_code_mode "https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/code-mode/src/remote/client.rs"
click node_remote_hand "https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/code-mode/src/remote/hand.rs"
click node_subagents "https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/subagents/src/routing.rs"
click node_computer "https://github.com/nanocodexyz/nanocode/blob/master/crates/integrations/computer/src/engine.rs"
click node_events "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode/src/events.rs"
click node_sim_host "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/host.rs"
click node_sim_executor "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/executor.rs"
click node_sim_egress "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/egress.rs"
click node_sim_rng "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/rng.rs"
click node_sim_streams "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/streams.rs"
click node_sim_turns "https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/turns.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_lite,node_front,node_app,node_user toneBlue
class node_agent,node_router,node_durability,node_events toneAmber
class node_tools,node_code_mode,node_remote_hand,node_subagents,node_computer toneMint
class node_codex,node_claude,node_model_services,node_payer toneRose
class node_sim_host,node_sim_executor,node_sim_egress,node_sim_rng,node_sim_streams,node_sim_turns toneIndigo
```

## Components

### User entrypoints

- [Nanocode CLI](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode/src/main.rs): `bin/nanocode/src/main.rs`
- [Lite CLI](https://github.com/nanocodexyz/nanocode/blob/master/bin/nc-lite/src/main.rs): `bin/nc-lite/src/main.rs`
- [Front host](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-front/src/main.rs): `bin/nanocode-front/src/main.rs`
- [Interactive app](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode/src/app.rs): `bin/nanocode/src/app.rs`

### Agent runtime

- [Agent runtime](https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/agent/src/runtime.rs): `crates/runtime/agent/src/runtime.rs`
- [Agent router](https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/agent/src/router.rs): `crates/runtime/agent/src/router.rs`
- [Durable sessions](https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/durability/src/session.rs): `crates/runtime/durability/src/session.rs`
- [Agent events](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode/src/events.rs): `bin/nanocode/src/events.rs`

### Agent capabilities

- [Tool execution](https://github.com/nanocodexyz/nanocode/blob/master/crates/backends/codex/src/builtin_tools/standard.rs): `crates/backends/codex/src/builtin_tools/standard.rs`
- [Code Mode](https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/code-mode/src/remote/client.rs): `crates/runtime/code-mode/src/remote/client.rs`
- [Remote hands](https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/code-mode/src/remote/hand.rs): `crates/runtime/code-mode/src/remote/hand.rs`
- [Subagents](https://github.com/nanocodexyz/nanocode/blob/master/crates/runtime/subagents/src/routing.rs): `crates/runtime/subagents/src/routing.rs`
- [Computer integration](https://github.com/nanocodexyz/nanocode/blob/master/crates/integrations/computer/src/engine.rs): `crates/integrations/computer/src/engine.rs`

### Models and payers

- [Codex harness](https://github.com/nanocodexyz/nanocode/blob/master/crates/backends/codex/src/agent/driver/mod.rs): `crates/backends/codex/src/agent/driver/mod.rs`
- [Claude harness](https://github.com/nanocodexyz/nanocode/blob/master/crates/backends/claude/src/agent/driver.rs): `crates/backends/claude/src/agent/driver.rs`
- **Model services**
- [Payer options](https://github.com/nanocodexyz/nanocode/blob/master/crates/backends/codex/client/src/auth/chatgpt.rs): `crates/backends/codex/client/src/auth/chatgpt.rs`

### Simulation runtime

- [Simulated host](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/host.rs): `bin/nanocode-sim/src/host.rs`
- [Sim executor](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/executor.rs): `bin/nanocode-sim/src/executor.rs`
- [Sim egress](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/egress.rs): `bin/nanocode-sim/src/egress.rs`
- [Sim random](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/rng.rs): `bin/nanocode-sim/src/rng.rs`
- [Sim streams](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/streams.rs): `bin/nanocode-sim/src/streams.rs`
- [Sim turns](https://github.com/nanocodexyz/nanocode/blob/master/bin/nanocode-sim/src/turns.rs): `bin/nanocode-sim/src/turns.rs`

### Other components

- **User**

## Connections

- User → Nanocode CLI: submits prompt
- User → Lite CLI: submits prompt
- Nanocode CLI → Agent runtime: runs agent
- Lite CLI → Agent runtime: runs agent
- Front host → Agent runtime: hosts runtime
- Agent runtime → Codex harness: selects harness
- Agent runtime → Claude harness: selects harness
- Codex harness → Model services: calls model
- Claude harness → Model services: calls model
- Agent runtime → Tool execution: invokes tools
- Agent runtime → Durable sessions: journals calls
- Agent runtime → Code Mode: runs program
- Code Mode → Tool execution: calls tools
- Agent runtime → Remote hands: dispatches calls
- Agent runtime → Subagents: spawns sessions
- Agent runtime → Payer options: uses payer
- Payer options → Model services: funds requests
- Interactive app → Agent runtime: submits turns
- Interactive app → Agent events: handles events (evidence: `bin/nanocode/src/app.rs`)
- Agent runtime → Agent events: emits events
- Remote hands → Computer integration: uses computer
- Simulated host → Sim random: derives randomness (evidence: `bin/nanocode-sim/src/host.rs`)
- Simulated host → Sim executor: queues futures (evidence: `bin/nanocode-sim/src/host.rs`)
- Sim egress → Simulated host: uses host (evidence: `bin/nanocode-sim/src/egress.rs`)
