# saferl-lab/nano-claude-code architecture

> Architecture diagram of the GitHub repository saferl-lab/nano-claude-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saferl-lab/nano-claude-code
- Repository: https://github.com/saferl-lab/nano-claude-code

## Overview

1. **Overall shape**
   - This repo is a Python reimplementation of Claude Code-style agentic coding workflow.
   - The core runtime is a REPL CLI (`nano_claude.py`) that drives one conversational loop, while most features are split into self-contained packages that register tools into a shared tool registry.

2. **Top-level runtime loop**
   - `nano_claude.py` is the user-facing entry point for interactive chat, slash commands, and non-interactive `--print` mode.
   - `agent.py` contains the main agent loop: it streams model output, detects tool calls, executes tools, and continues until the turn completes.
   - The loop is designed around typed events, so rendering, logging, and tool execution are cleanly separated from orchestration.

3. **Model/provider boundary**
   - `providers.py` is the abstraction layer for model backends.
   - It supports multiple external model families and OpenAI-compatible endpoints, including local servers such as Ollama, LM Studio, and vLLM.
   - The architecture treats provider choice as a runtime concern: the same agent loop can switch models without changing the rest of the system.

4. **Tool system as the main extension seam**
   - `tool_registry.py` is the central dispatch point for tools.
   - `tools.py` defines the core coding tools such as file read/write/edit, shell execution, search, web fetch/search, notebook editing, and diagnostics.
   - Each tool package registers its tools into the same registry, so built-ins, plugins, MCP servers, skills, and sub-agents all appear as callable tools from the model’s perspective.

5. **Context construction and compression**
   - `context.py` builds the system prompt and injected context from repo-local and user-local sources.
   - It pulls in `CLAUDE.md`, git status, working directory information, and persistent memory.
   - `compaction.py` handles long conversations with a two-stage strategy: cheap truncation/snipping of old tool outputs, then model-based summarization when context grows too large.

6. **Persistent state and configuration**
   - `config.py` manages saved settings such as default model, permission mode, API keys, and other runtime preferences.
   - Session history is saved and restored through the CLI, with autosave/resume behavior described in the README.
   - The architecture keeps durable user/project state separate from ephemeral turn state, which is important for understanding reload/resume flows.

7. **Memory subsystem**
   - The `memory/` package implements persistent, dual-scope memory: user scope under `~/.nano_claude/memory/` and project scope under `.nano_claude/memory/`.
   - `memory/store.py` handles save/delete/search and rebuilds the `MEMORY.md` index used for prompt injection.
   - `memory/context.py` prepares memory snippets for the model, while `memory/tools.py` exposes MemorySave/Delete/Search/List as tools.

8. **Task tracking subsystem**
   - The `task/` package adds a structured task graph separate from conversation state.
   - `task/store.py` persists tasks to `.nano_claude/tasks.json`, and `task/tools.py` exposes create/update/get/list actions.
   - Tasks support dependency edges (`blocks` / `blocked_by`), which means the architecture can represent multi-step plans explicitly rather than only through chat history.

9. **Multi-agent execution**
   - `multi_agent/` provides sub-agent orchestration for parallel or isolated work.
   - `multi_agent/subagent.py` defines agent types and worktree/isolation behavior.
   - `multi_agent/tools.py` exposes tools like Agent, SendMessage, CheckAgentResult, and listing utilities, making sub-agents first-class participants in the same tool-driven workflow.

10. **Skills as reusable prompt behaviors**
   - The `skill/` package loads markdown-based skill definitions and built-in skills such as `/commit` and `/review`.
   - `skill/executor.py` can run skills inline in the current conversation or fork them into isolated sub-agents.
   - This acts as a higher-level behavior layer on top of the same tool registry and model loop.

11. **MCP integration**
   - The `mcp/` package connects external Model Context Protocol servers over stdio, SSE, or HTTP.
   - `mcp/config.py` reads project and user MCP config, `mcp/client.py` manages connections, and `mcp/tools.py` auto-registers discovered remote tools into the registry.
   - Architecturally, MCP is an adapter layer: external services become ordinary callable tools once connected.

12. **Plugin system**
   - `plugin/` supports installing feature bundles from git repos or local paths.
   - Plugins can contribute tools, skills, and MCP server definitions, which means they extend the same runtime surface rather than creating a separate plugin execution model.
   - There is also a recommendation layer (`plugin/recommend.py`) that suggests plugins from project context.

13. **Voice input pipeline**
   - `voice/` adds an optional capture-and-transcribe path before a prompt reaches the agent.
   - `voice/recorder.py` handles recording backends, `voice/stt.py` handles transcription backends, and `voice/keyterms.py` boosts coding accuracy using repository-specific vocabulary.
   - The output of this subsystem is just another prompt into the REPL, so it sits outside the core agent loop but feeds it directly.

14. **Compatibility and evolution**
   - Several top-level modules (`memory.py`, `subagent.py`, `skills.py`) are backward-compatibility shims that re-export newer package layouts.
   - That suggests the codebase has evolved from a flatter structure into feature packages without breaking older imports.
   - The `tests/` directory mirrors the major subsystems, which is a good indicator of the architecture’s intended boundaries: agent loop, tools, memory, MCP, plugins, skills, sub-agents, task management, compaction, diff rendering, and voice.

15. **Main data flow to draw**
   - User input enters the REPL.
   - The CLI merges that input with saved config, context, memory, and session state.
   - The agent loop sends the prompt to the selected provider.
   - Model responses may invoke tools, which are executed through the shared registry.
   - Tool results and assistant text are appended to conversation state, optionally compacted, and persisted to session/memory/task stores when relevant.

Main entry points: [`tool_registry.py`](https://github.com/saferl-lab/nano-claude-code/blob/main/tool_registry.py) (Tool registry), [`nano_claude.py`](https://github.com/saferl-lab/nano-claude-code/blob/main/nano_claude.py) (REPL CLI), [`agent.py`](https://github.com/saferl-lab/nano-claude-code/blob/main/agent.py) (Agent loop), [`plugin`](https://github.com/saferl-lab/nano-claude-code/tree/main/plugin) (Plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_nano_claude["REPL CLI<br/>entrypoint<br/>[nano_claude.py]"]
  node_agent["Agent loop<br/>orchestrator<br/>[agent.py]"]
  node_providers["Providers<br/>model backend<br/>[providers.py]"]
  node_context["Context<br/>prompt builder<br/>[context.py]"]
  node_compaction["Compaction<br/>conversation management<br/>[compaction.py]"]
end

subgraph group_state["State"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_memory_pkg[("Memory")]
  node_task_pkg[("Tasks<br/>task graph")]
  node_memory_shim["Memory shim<br/>compatibility shim<br/>[memory.py]"]
end

subgraph group_extensions["Extensions"]
  node_tool_registry["Tool registry<br/>dispatch core<br/>[tool_registry.py]"]
  node_tools["Core tools<br/>builtin tools<br/>[tools.py]"]
  node_multi_agent["Sub-agents<br/>multi-agent"]
  node_skill["Skills<br/>prompt behaviors"]
  node_mcp["MCP bridge<br/>protocol adapter"]
  node_plugin["Plugins<br/>extension loader"]
  node_subagent_shim["Subagent shim<br/>compatibility shim<br/>[subagent.py]"]
  node_skills_shim["Skills shim<br/>compatibility shim<br/>[skills.py]"]
end

subgraph group_input["Input"]
  node_voice["Voice input<br/>capture pipeline"]
end

node_nano_claude -->|"loads"| node_config
node_nano_claude -->|"builds"| node_context
node_nano_claude -->|"drives"| node_agent
node_nano_claude -.->|"optionally captures"| node_voice
node_agent -->|"calls"| node_providers
node_agent -->|"executes via"| node_tool_registry
node_agent -->|"compacts"| node_compaction
node_context -->|"injects"| node_memory_pkg
node_context -->|"reads"| node_config
node_memory_pkg -->|"registers tools"| node_tool_registry
node_task_pkg -->|"registers tools"| node_tool_registry
node_tools -->|"registers"| node_tool_registry
node_multi_agent -->|"registers tools"| node_tool_registry
node_skill -->|"uses"| node_tool_registry
node_mcp -->|"registers tools"| node_tool_registry
node_plugin -->|"extends"| node_tool_registry
node_plugin -->|"adds skills"| node_skill
node_plugin -->|"adds servers"| node_mcp
node_voice -->|"feeds input"| node_nano_claude
node_memory_shim -.->|"re-exports"| node_memory_pkg
node_subagent_shim -.->|"re-exports"| node_multi_agent
node_skills_shim -.->|"re-exports"| node_skill

click node_nano_claude "https://github.com/saferl-lab/nano-claude-code/blob/main/nano_claude.py"
click node_agent "https://github.com/saferl-lab/nano-claude-code/blob/main/agent.py"
click node_providers "https://github.com/saferl-lab/nano-claude-code/blob/main/providers.py"
click node_context "https://github.com/saferl-lab/nano-claude-code/blob/main/context.py"
click node_compaction "https://github.com/saferl-lab/nano-claude-code/blob/main/compaction.py"
click node_config "https://github.com/saferl-lab/nano-claude-code/blob/main/config.py"
click node_memory_pkg "https://github.com/saferl-lab/nano-claude-code/tree/main/memory"
click node_task_pkg "https://github.com/saferl-lab/nano-claude-code/tree/main/task"
click node_tool_registry "https://github.com/saferl-lab/nano-claude-code/blob/main/tool_registry.py"
click node_tools "https://github.com/saferl-lab/nano-claude-code/blob/main/tools.py"
click node_multi_agent "https://github.com/saferl-lab/nano-claude-code/tree/main/multi_agent"
click node_skill "https://github.com/saferl-lab/nano-claude-code/tree/main/skill"
click node_mcp "https://github.com/saferl-lab/nano-claude-code/tree/main/mcp"
click node_plugin "https://github.com/saferl-lab/nano-claude-code/tree/main/plugin"
click node_voice "https://github.com/saferl-lab/nano-claude-code/tree/main/voice"
click node_memory_shim "https://github.com/saferl-lab/nano-claude-code/blob/main/memory.py"
click node_subagent_shim "https://github.com/saferl-lab/nano-claude-code/blob/main/subagent.py"
click node_skills_shim "https://github.com/saferl-lab/nano-claude-code/blob/main/skills.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_nano_claude,node_agent,node_providers,node_context,node_compaction toneBlue
class node_config,node_memory_pkg,node_task_pkg,node_memory_shim toneAmber
class node_tool_registry,node_tools,node_multi_agent,node_skill,node_mcp,node_plugin,node_subagent_shim,node_skills_shim toneMint
class node_voice toneRose
```

## Components

### Runtime

Interactive entrypoint, orchestration, and model/provider boundary

- [REPL CLI](https://github.com/saferl-lab/nano-claude-code/blob/main/nano_claude.py): entrypoint · Interactive chat, slash commands, and print mode · `nano_claude.py`
- [Agent loop](https://github.com/saferl-lab/nano-claude-code/blob/main/agent.py): orchestrator · Streams model output, executes tools, and continues turns · `agent.py`
- [Providers](https://github.com/saferl-lab/nano-claude-code/blob/main/providers.py): model backend · Abstraction over external and OpenAI-compatible model providers · `providers.py`
- [Context](https://github.com/saferl-lab/nano-claude-code/blob/main/context.py): prompt builder · Builds system prompt and injected repo/user context · `context.py`
- [Compaction](https://github.com/saferl-lab/nano-claude-code/blob/main/compaction.py): conversation management · Truncates and summarizes long conversations · `compaction.py`

### State

Persistent configuration, memory, and task storage

- [Config](https://github.com/saferl-lab/nano-claude-code/blob/main/config.py): settings · Saved runtime preferences and API configuration · `config.py`
- [Memory](https://github.com/saferl-lab/nano-claude-code/tree/main/memory): persistent memory · User and project memory store plus prompt snippets · `memory`
- [Tasks](https://github.com/saferl-lab/nano-claude-code/tree/main/task): task graph · Persistent structured tasks with dependencies · `task`
- [Memory shim](https://github.com/saferl-lab/nano-claude-code/blob/main/memory.py): compatibility shim · Back-compat re-export for the memory package · `memory.py`

### Extensions

Pluggable tool, skill, agent, and MCP surfaces

- [Tool registry](https://github.com/saferl-lab/nano-claude-code/blob/main/tool_registry.py): dispatch core · Central registration and lookup for callable tools · `tool_registry.py`
- [Core tools](https://github.com/saferl-lab/nano-claude-code/blob/main/tools.py): builtin tools · File, shell, search, web, notebook, and diagnostics tools · `tools.py`
- [Sub-agents](https://github.com/saferl-lab/nano-claude-code/tree/main/multi_agent): multi-agent · Isolated and parallel agent execution · `multi_agent`
- [Skills](https://github.com/saferl-lab/nano-claude-code/tree/main/skill): prompt behaviors · Markdown skills and built-in behaviors like commit and review · `skill`
- [MCP bridge](https://github.com/saferl-lab/nano-claude-code/tree/main/mcp): protocol adapter · Connects external MCP servers and exposes remote tools · `mcp`
- [Plugins](https://github.com/saferl-lab/nano-claude-code/tree/main/plugin): extension loader · Installs bundles that contribute tools, skills, and MCP config · `plugin`
- [Subagent shim](https://github.com/saferl-lab/nano-claude-code/blob/main/subagent.py): compatibility shim · Back-compat re-export for sub-agent APIs · `subagent.py`
- [Skills shim](https://github.com/saferl-lab/nano-claude-code/blob/main/skills.py): compatibility shim · Back-compat re-export for skill APIs · `skills.py`

### Input

Optional pre-processing before prompts reach the agent

- [Voice input](https://github.com/saferl-lab/nano-claude-code/tree/main/voice): capture pipeline · Recording and transcription before prompts enter the REPL · `voice`

## Connections

- REPL CLI → Config: loads · Reads saved runtime preferences and defaults
- REPL CLI → Context: builds · Assembles prompt material for each turn
- REPL CLI → Agent loop: drives · Hands user input and session state to the loop
- REPL CLI → Voice input: optionally captures · Voice input can be transcribed before dispatch
- Agent loop → Providers: calls · Sends prompts to the selected model backend
- Agent loop → Tool registry: executes via · Routes tool calls through the shared registry
- Agent loop → Compaction: compacts · Shrinks or summarizes long conversations
- Context → Memory: injects · Pulls persistent memory into prompts
- Context → Config: reads · Uses saved settings to shape context
- Memory → Tool registry: registers tools · Exposes memory actions as callable tools
- Tasks → Tool registry: registers tools · Exposes task actions as callable tools
- Core tools → Tool registry: registers · Adds core coding tools to the shared registry
- Sub-agents → Tool registry: registers tools · Exposes agent-spawn and coordination tools
- Skills → Tool registry: uses · Skills can invoke the same tool surface
- MCP bridge → Tool registry: registers tools · Imports remote MCP tools into the registry
- Plugins → Tool registry: extends · Plugin-contributed tools join the same runtime surface
- Plugins → Skills: adds skills · Plugins may contribute reusable behaviors
- Plugins → MCP bridge: adds servers · Plugins may define MCP server configurations
- Voice input → REPL CLI: feeds input · Transcribed text enters the REPL as user prompt
- Memory shim → Memory: re-exports · Maintains compatibility with older imports
- Subagent shim → Sub-agents: re-exports · Maintains compatibility with older imports
- Skills shim → Skills: re-exports · Maintains compatibility with older imports
