# optimalone/build-your-own-coding-agent architecture

> Architecture diagram of the GitHub repository optimalone/build-your-own-coding-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/optimalone/build-your-own-coding-agent
- Repository: https://github.com/optimalone/build-your-own-coding-agent

## Overview

Nanocode is a terminal-based AI coding agent, presented as a sequence of runnable chapter snapshots rather than a single modular application. In the capstone workflow, a user submits a request, the agent consults a model, invokes tools as needed, and returns results while retaining conversation and persistent context. Documented capabilities include file editing, command execution, codebase search, safety modes, multiple model providers, and web search. The sampled code shows provider and agent behavior; several tool details are documented in the README but not present in the excerpts.

Main entry points: [`ch12/nanocode.py`](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py) (Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Agent interaction"]
  node_loop["Terminal loop<br/>[nanocode.py]"]
  node_agent["Agent<br/>[nanocode.py]"]
  node_conversation["Conversation state<br/>[nanocode.py]"]
end

subgraph group_models["Model providers"]
  node_brain["Brain selection<br/>[nanocode.py]"]
  node_claude["Claude API<br/>[nanocode.py]"]
  node_deepseek["DeepSeek API<br/>[nanocode.py]"]
  node_ollama["Ollama API<br/>[nanocode.py]"]
end

subgraph group_capabilities["Coding capabilities"]
  node_file_tools["File tools<br/>[nanocode.py]"]
  node_shell_tool["Shell execution<br/>[nanocode.py]"]
  node_code_search["Codebase search<br/>[nanocode.py]"]
  node_web_search["Web search<br/>[nanocode.py]"]
end

subgraph group_context["Context and memory"]
  node_memory[("Persistent memory<br/>[nanocode.py]")]
  node_safety["Plan and act modes<br/>[nanocode.py]"]
end

node_user(("Terminal user"))
node_model_services(("Model services"))
node_web_service(("DuckDuckGo"))
node_workspace[("Project files")]
node_shell(("Operating system"))

node_user -->|"enters request"| node_loop
node_loop -->|"passes input"| node_agent
node_agent -->|"updates history"| node_conversation
node_agent -->|"requests response"| node_brain
node_brain -->|"selects provider"| node_claude
node_brain -.->|"selects provider"| node_deepseek
node_brain -.->|"selects provider"| node_ollama
node_claude -->|"sends request"| node_model_services
node_deepseek -.->|"sends request"| node_model_services
node_ollama -.->|"sends request"| node_model_services
node_brain -->|"returns thought"| node_agent
node_agent -->|"dispatches tool"| node_file_tools
node_agent -->|"dispatches tool"| node_shell_tool
node_agent -->|"dispatches tool"| node_code_search
node_agent -.->|"dispatches tool"| node_web_search
node_file_tools -->|"reads and writes"| node_workspace
node_code_search -->|"searches files"| node_workspace
node_shell_tool -->|"runs command"| node_shell
node_web_search -.->|"searches web"| node_web_service
node_agent -->|"uses context"| node_memory
node_agent -->|"checks mode"| node_safety

click node_loop "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_agent "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_conversation "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_brain "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_claude "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_deepseek "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_ollama "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_file_tools "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_shell_tool "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_code_search "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_web_search "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_memory "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"
click node_safety "https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py"

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_loop,node_agent,node_conversation,node_user toneBlue
class node_brain,node_claude,node_deepseek,node_ollama,node_workspace toneAmber
class node_file_tools,node_shell_tool,node_code_search,node_web_search toneMint
class node_memory,node_safety toneRose
class node_model_services,node_web_service,node_shell toneIndigo
```

## Components

### Agent interaction

- [Terminal loop](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [Agent](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [Conversation state](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`

### Model providers

- [Brain selection](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [Claude API](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [DeepSeek API](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [Ollama API](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`

### Coding capabilities

- [File tools](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [Shell execution](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [Codebase search](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [Web search](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`

### Context and memory

- [Persistent memory](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`
- [Plan and act modes](https://github.com/optimalone/build-your-own-coding-agent/blob/main/ch12/nanocode.py): `ch12/nanocode.py`

### Other components

- **Terminal user**
- **Model services**
- **DuckDuckGo**
- **Project files**
- **Operating system**

## Connections

- Terminal user → Terminal loop: enters request
- Terminal loop → Agent: passes input
- Agent → Conversation state: updates history
- Agent → Brain selection: requests response
- Brain selection → Claude API: selects provider
- Brain selection → DeepSeek API: selects provider
- Brain selection → Ollama API: selects provider
- Claude API → Model services: sends request
- DeepSeek API → Model services: sends request
- Ollama API → Model services: sends request
- Brain selection → Agent: returns thought
- Agent → File tools: dispatches tool
- Agent → Shell execution: dispatches tool
- Agent → Codebase search: dispatches tool
- Agent → Web search: dispatches tool
- File tools → Project files: reads and writes
- Codebase search → Project files: searches files
- Shell execution → Operating system: runs command
- Web search → DuckDuckGo: searches web
- Agent → Persistent memory: uses context
- Agent → Plan and act modes: checks mode