How saferl-lab/nano-claude-code works
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 Tool registry · nano_claude.py REPL CLI · agent.py Agent loop · plugin Plugins
Components 18
Runtime
Interactive entrypoint, orchestration, and model/provider boundary
- REPL CLI · Interactive chat, slash commands, and print mode
nano_claude.py - Agent loop · Streams model output, executes tools, and continues turns
agent.py - Providers · Abstraction over external and OpenAI-compatible model providers
providers.py - Context · Builds system prompt and injected repo/user context
context.py - Compaction · Truncates and summarizes long conversations
compaction.py
State
Persistent configuration, memory, and task storage
- Config · Saved runtime preferences and API configuration
config.py - Memory · User and project memory store plus prompt snippets
memory - Tasks · Persistent structured tasks with dependencies
task - Memory shim · Back-compat re-export for the memory package
memory.py
Extensions
Pluggable tool, skill, agent, and MCP surfaces
- Tool registry · Central registration and lookup for callable tools
tool_registry.py - Core tools · File, shell, search, web, notebook, and diagnostics tools
tools.py - Sub-agents · Isolated and parallel agent execution
multi_agent - Skills · Markdown skills and built-in behaviors like commit and review
skill - MCP bridge · Connects external MCP servers and exposes remote tools
mcp - Plugins · Installs bundles that contribute tools, skills, and MCP config
plugin - Subagent shim · Back-compat re-export for sub-agent APIs
subagent.py - Skills shim · Back-compat re-export for skill APIs
skills.py
Input
Optional pre-processing before prompts reach the agent
- Voice input · Recording and transcription before prompts enter the REPL
voice
Connections 22
- 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