# openlair/nano-claude-code architecture

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

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

## Overview

Nano-Claude-Code is a lightweight Python coding agent. A user submits a coding task through the CLI; the agent builds context and prompts, calls a configured model, dispatches tool requests under permission rules, and returns results through the interactive or stream-json interface. The graph also preserves the documented sub-agent, skill, memory, session, and multi-provider capabilities. Some internal links rely on README descriptions or SOURCE INDEX references; unsampled behavior is not inferred beyond those links.

Main entry points: [`nano_claude_code/agent.py`](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/agent.py) (Agent loop), [`nano_claude_code/tools_impl.py`](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/tools_impl.py) (Coding tools), [`nano_claude_code/cli.py`](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/cli.py) (CLI and REPL), [`nano_claude_code/prompts.py`](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/prompts.py) (Prompt builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and runtime"]
  node_cli["CLI and REPL<br/>[cli.py]"]
  node_stream["Stream events<br/>[stream_json.py]"]
end

subgraph group_agent["Agent orchestration"]
  node_agentloop["Agent loop<br/>[agent.py]"]
  node_subagents["Sub-agents<br/>[agents.py]"]
end

subgraph group_context["Context and extensions"]
  node_prompts["Prompt builder<br/>[prompts.py]"]
  node_memory["Memory hierarchy<br/>[memory.py]"]
  node_skills["Skills<br/>[skills.py]"]
  node_frontmatter["Frontmatter parser<br/>[frontmatter.py]"]
end

subgraph group_tools["Tools and safety"]
  node_tools["Coding tools<br/>[tools_impl.py]"]
  node_permissions["Permission rules<br/>[permissions.py]"]
end

subgraph group_providers["Providers and state"]
  node_config["Configuration<br/>[config.py]"]
  node_openai["OpenAI-compatible backend<br/>[openai_compat.py]"]
  node_sessions[("Session persistence<br/>[session.py]")]
end

node_user(("User"))
node_workspace["Project workspace"]
node_anthropic["Anthropic API"]
node_compatapi["Compatible API endpoint"]

node_user -->|"submits task"| node_cli
node_cli -->|"starts agent"| node_agentloop
node_cli -->|"loads settings"| node_config
node_cli -->|"saves and resumes"| node_sessions
node_cli -->|"handles skill commands"| node_skills
node_agentloop -->|"builds prompt"| node_prompts
node_prompts -->|"loads context"| node_memory
node_prompts -->|"lists agents"| node_subagents
node_prompts -->|"lists skills"| node_skills
node_skills -->|"parses metadata"| node_frontmatter
node_subagents -->|"parses agent files"| node_frontmatter
node_agentloop -->|"dispatches tool calls"| node_tools
node_agentloop -->|"checks permissions"| node_permissions
node_agentloop -->|"resolves provider"| node_config
node_agentloop -->|"persists conversation"| node_sessions
node_agentloop -->|"emits harness output"| node_stream
node_agentloop -->|"selects compatible backend"| node_openai
node_agentloop -->|"sends model requests"| node_anthropic
node_openai -->|"sends chat requests"| node_compatapi
node_tools -->|"reads and edits files"| node_workspace
node_tools -->|"runs shell commands"| node_workspace
node_tools -->|"spawns agents"| node_subagents
node_tools -->|"loads skills"| node_skills
node_tools -.->|"fetches and searches web"| node_compatapi
node_stream -->|"returns events"| node_user

click node_cli "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/cli.py"
click node_stream "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/stream_json.py"
click node_agentloop "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/agent.py"
click node_subagents "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/agents.py"
click node_prompts "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/prompts.py"
click node_memory "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/memory.py"
click node_skills "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/skills.py"
click node_frontmatter "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/frontmatter.py"
click node_tools "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/tools_impl.py"
click node_permissions "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/permissions.py"
click node_config "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/config.py"
click node_openai "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/openai_compat.py"
click node_sessions "https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/session.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_cli,node_stream,node_user toneBlue
class node_agentloop,node_subagents toneAmber
class node_prompts,node_memory,node_skills,node_frontmatter,node_anthropic,node_compatapi toneMint
class node_tools,node_permissions toneRose
class node_config,node_openai,node_sessions,node_workspace toneIndigo
```

## Components

### CLI and runtime

- [CLI and REPL](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/cli.py): `nano_claude_code/cli.py`
- [Stream events](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/stream_json.py): `nano_claude_code/stream_json.py`

### Agent orchestration

- [Agent loop](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/agent.py): `nano_claude_code/agent.py`
- [Sub-agents](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/agents.py): `nano_claude_code/agents.py`

### Context and extensions

- [Prompt builder](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/prompts.py): `nano_claude_code/prompts.py`
- [Memory hierarchy](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/memory.py): `nano_claude_code/memory.py`
- [Skills](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/skills.py): `nano_claude_code/skills.py`
- [Frontmatter parser](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/frontmatter.py): `nano_claude_code/frontmatter.py`

### Tools and safety

- [Coding tools](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/tools_impl.py): `nano_claude_code/tools_impl.py`
- [Permission rules](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/permissions.py): `nano_claude_code/permissions.py`

### Providers and state

- [Configuration](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/config.py): `nano_claude_code/config.py`
- [OpenAI-compatible backend](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/openai_compat.py): `nano_claude_code/openai_compat.py`
- [Session persistence](https://github.com/openlair/nano-claude-code/blob/main/nano_claude_code/session.py): `nano_claude_code/session.py`

### Other components

- **User**
- **Project workspace**
- **Anthropic API**
- **Compatible API endpoint**

## Connections

- User → CLI and REPL: submits task (evidence: `README.md`)
- CLI and REPL → Agent loop: starts agent (evidence: `nano_claude_code/cli.py`)
- CLI and REPL → Configuration: loads settings (evidence: `nano_claude_code/cli.py`)
- CLI and REPL → Session persistence: saves and resumes (evidence: `nano_claude_code/cli.py`)
- CLI and REPL → Skills: handles skill commands (evidence: `nano_claude_code/cli.py`)
- Agent loop → Prompt builder: builds prompt (evidence: `nano_claude_code/agent.py`)
- Prompt builder → Memory hierarchy: loads context (evidence: `nano_claude_code/prompts.py`)
- Prompt builder → Sub-agents: lists agents (evidence: `nano_claude_code/prompts.py`)
- Prompt builder → Skills: lists skills (evidence: `nano_claude_code/prompts.py`)
- Skills → Frontmatter parser: parses metadata (evidence: `nano_claude_code/skills.py`)
- Sub-agents → Frontmatter parser: parses agent files (evidence: `nano_claude_code/agents.py`)
- Agent loop → Coding tools: dispatches tool calls (evidence: `nano_claude_code/agent.py`)
- Agent loop → Permission rules: checks permissions (evidence: `nano_claude_code/agent.py`)
- Agent loop → Configuration: resolves provider (evidence: `nano_claude_code/agent.py`)
- Agent loop → Session persistence: persists conversation (evidence: `nano_claude_code/agent.py`)
- Agent loop → Stream events: emits harness output (evidence: `nano_claude_code/agent.py`)
- Agent loop → OpenAI-compatible backend: selects compatible backend (evidence: `nano_claude_code/agent.py`)
- Agent loop → Anthropic API: sends model requests (evidence: `README.md`)
- OpenAI-compatible backend → Compatible API endpoint: sends chat requests (evidence: `nano_claude_code/openai_compat.py`)
- Coding tools → Project workspace: reads and edits files (evidence: `nano_claude_code/tools_impl.py`)
- Coding tools → Project workspace: runs shell commands (evidence: `nano_claude_code/tools_impl.py`)
- Coding tools → Sub-agents: spawns agents (evidence: `README.md`)
- Coding tools → Skills: loads skills (evidence: `README.md`)
- Coding tools → Compatible API endpoint: fetches and searches web
- Stream events → User: returns events (evidence: `nano_claude_code/stream_json.py`)
