Nano Claude Code: A Minimal Python Reimplementation

The newest source of Claude Code · Issue

🔥🔥🔥 News (Pacific Time)

• 10:00 AM, Apr 03, 2026: v3.01 — MCP (Model Context Protocol) support: mcp/ package, stdio + SSE + HTTP transports, auto tool discovery, /mcp command, 34 new tests (~7000 lines of Python).
• 12:20 PM, Apr 02, 2026: v3.0 — Multi-agent packages (multi_agent/), memory package (memory/), skill package (skill/) with built-in skills, argument substitution, fork/inline execution, AI memory search, git worktree isolation, agent type definitions (~5000 lines of Python), see update.
• 10:00 AM, Apr 02, 2026: v2.0 — Context compression, memory, sub-agents, skills, diff view, tool plugin system (~3400 lines of Python Code).
• 01:47 PM, Apr 01, 2026: Support VLLM inference (~2000 lines of Python Code).
• 11:30 AM, Apr 01, 2026: Support more closed-source models and open-source models: Claude, GPT, Gemini, Kimi, Qwen, Zhipu, DeepSeek, and local open-source models via Ollama or any OpenAI-compatible endpoint. (~1700 lines of Python Code).
• 09:50 AM, Apr 01, 2026: Support more closed-source models: Claude, GPT, Gemini. (~1300 lines of Python Code).
• 08:23 AM, Apr 01, 2026: Release the initial version of Nano Claude Code (~900 lines of Python Code).

Nano Claude Code

A minimal Python implementation of Claude Code in ~900 lines (Initial version), supporting Claude, GPT, Gemini, Kimi, Qwen, Zhipu, DeepSeek, and local open-source models via Ollama or any OpenAI-compatible endpoint.

Content

• Features
• Supported Models
• Installation
• Usage: Closed-Source API Models
• Usage: Open-Source Models (Local)
• Model Name Format
• CLI Reference
• Slash Commands (REPL)
• Configuring API Keys
• Permission System
• Built-in Tools
• Memory
• Skills
• Sub-Agents
• MCP (Model Context Protocol)
• Context Compression
• Diff View
• CLAUDE.md Support
• Session Management
• Project Structure
• FAQ

Features

Supported Models

Closed-Source (API)

Open-Source (Local via Ollama)

Note: Tool calling requires a model that supports function calling. Recommended local models: qwen2.5-coder, llama3.3, mistral, phi4.

Installation

git clone <repo-url>
cd nano_claude_code

pip install -r requirements.txt
# or manually:
pip install anthropic openai httpx rich

Usage: Closed-Source API Models

Anthropic Claude

Get your API key at console.anthropic.com.

export ANTHROPIC_API_KEY=sk-ant-api03-...

# Default model (claude-opus-4-6)
python nano_claude.py

# Choose a specific model
python nano_claude.py --model claude-sonnet-4-6
python nano_claude.py --model claude-haiku-4-5-20251001

# Enable Extended Thinking
python nano_claude.py --model claude-opus-4-6 --thinking --verbose

OpenAI GPT

Get your API key at platform.openai.com.

export OPENAI_API_KEY=sk-...

python nano_claude.py --model gpt-4o
python nano_claude.py --model gpt-4o-mini
python nano_claude.py --model gpt-4.1-mini
python nano_claude.py --model o3-mini

Google Gemini

Get your API key at aistudio.google.com.

export GEMINI_API_KEY=AIza...

python nano_claude.py --model gemini/gemini-2.0-flash
python nano_claude.py --model gemini/gemini-1.5-pro
python nano_claude.py --model gemini/gemini-2.5-pro-preview-03-25

Kimi (Moonshot AI)

Get your API key at platform.moonshot.cn.

export MOONSHOT_API_KEY=sk-...

python nano_claude.py --model kimi/moonshot-v1-32k
python nano_claude.py --model kimi/moonshot-v1-128k

Qwen (Alibaba DashScope)

Get your API key at dashscope.aliyun.com.

export DASHSCOPE_API_KEY=sk-...

python nano_claude.py --model qwen/Qwen3.5-Plus
python nano_claude.py --model qwen/Qwen3-MAX
python nano_claude.py --model qwen/Qwen3.5-Flash

Zhipu GLM

Get your API key at open.bigmodel.cn.

export ZHIPU_API_KEY=...

python nano_claude.py --model zhipu/glm-4-plus
python nano_claude.py --model zhipu/glm-4-flash   # free tier

DeepSeek

Get your API key at platform.deepseek.com.

export DEEPSEEK_API_KEY=sk-...

python nano_claude.py --model deepseek/deepseek-chat
python nano_claude.py --model deepseek/deepseek-reasoner

Usage: Open-Source Models (Local)

Option A — Ollama (Recommended)

Ollama runs models locally with zero configuration. No API key required.

Step 1: Install Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Or download from https://ollama.com/download

Step 2: Pull a model

# Best for coding (recommended)
ollama pull qwen2.5-coder          # 4.7 GB (7B)
ollama pull qwen2.5-coder:32b      # 19 GB (32B)

# General purpose
ollama pull llama3.3               # 42 GB (70B)
ollama pull llama3.2               # 2.0 GB (3B)

# Reasoning
ollama pull deepseek-r1            # 4.7 GB (7B)
ollama pull deepseek-r1:32b        # 19 GB (32B)

# Other
ollama pull phi4                   # 9.1 GB (14B)
ollama pull mistral                # 4.1 GB (7B)

Step 3: Start Ollama server (runs automatically on macOS; on Linux run manually)

ollama serve     # starts on http://localhost:11434

Step 4: Run nano claude

python nano_claude.py --model ollama/qwen2.5-coder
python nano_claude.py --model ollama/llama3.3
python nano_claude.py --model ollama/deepseek-r1

List your locally available models:

ollama list

Then use any model from the list:

python nano_claude.py --model ollama/<model-name>

Option B — LM Studio

LM Studio provides a GUI to download and run models, with a built-in OpenAI-compatible server.

Step 1: Download LM Studio and install it.

Step 2: Search and download a model inside LM Studio (GGUF format).

Step 3: Go to Local Server tab → click Start Server (default port: 1234).

Step 4:

python nano_claude.py --model lmstudio/<model-name>
# e.g.:
python nano_claude.py --model lmstudio/phi-4-GGUF
python nano_claude.py --model lmstudio/qwen2.5-coder-7b

The model name should match what LM Studio shows in the server status bar.

Option C — vLLM / Self-Hosted OpenAI-Compatible Server

For self-hosted inference servers (vLLM, TGI, llama.cpp server, etc.) that expose an OpenAI-compatible API:

Quick Start for option C:
Step 1: Start vllm:

CUDA_VISIBLE_DEVICES=7 python -m vllm.entrypoints.openai.api_server \
     --model Qwen/Qwen2.5-Coder-7B-Instruct \
     --host 0.0.0.0 \
     --port 8000 \
     --enable-auto-tool-choice \
     --tool-call-parser hermes

Step 2: Start nano claude：

  export CUSTOM_BASE_URL=http://localhost:8000/v1
  export CUSTOM_API_KEY=none
  python nano_claude.py --model custom/Qwen/Qwen2.5-Coder-7B-Instruct

# Example: vLLM serving Qwen2.5-Coder-32B
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-Coder-32B-Instruct \
    --port 8000

# Then run nano claude pointing to your server:
python nano_claude.py

Inside the REPL:

/config custom_base_url=http://localhost:8000/v1
/config custom_api_key=token-abc123    # skip if no auth
/model custom/Qwen2.5-Coder-32B-Instruct

Or set via environment:

export CUSTOM_BASE_URL=http://localhost:8000/v1
export CUSTOM_API_KEY=token-abc123

python nano_claude.py --model custom/Qwen2.5-Coder-32B-Instruct

For a remote GPU server:

/config custom_base_url=http://192.168.1.100:8000/v1
/model custom/your-model-name

Model Name Format

Three equivalent formats are supported:

# 1. Auto-detect by prefix (works for well-known models)
python nano_claude.py --model gpt-4o
python nano_claude.py --model gemini-2.0-flash
python nano_claude.py --model deepseek-chat

# 2. Explicit provider prefix with slash
python nano_claude.py --model ollama/qwen2.5-coder
python nano_claude.py --model kimi/moonshot-v1-128k

# 3. Explicit provider prefix with colon (also works)
python nano_claude.py --model kimi:moonshot-v1-32k
python nano_claude.py --model qwen:qwen-max

Auto-detection rules:

CLI Reference

python nano_claude.py [OPTIONS] [PROMPT]

Options:
  -p, --print          Non-interactive: run prompt and exit
  -m, --model MODEL    Override model (e.g. gpt-4o, ollama/llama3.3)
  --accept-all         Auto-approve all operations (no permission prompts)
  --verbose            Show thinking blocks and per-turn token counts
  --thinking           Enable Extended Thinking (Claude only)
  --version            Print version and exit
  -h, --help           Show help

Examples:

# Interactive REPL with default model
python nano_claude.py

# Switch model at startup
python nano_claude.py --model gpt-4o
python nano_claude.py -m ollama/deepseek-r1:32b

# Non-interactive / scripting
python nano_claude.py --print "Write a Python fibonacci function"
python nano_claude.py -p "Explain the Rust borrow checker in 3 sentences" -m gemini/gemini-2.0-flash

# CI / automation (no permission prompts)
python nano_claude.py --accept-all --print "Initialize a Python project with pyproject.toml"

# Debug mode (see tokens + thinking)
python nano_claude.py --thinking --verbose

Slash Commands (REPL)

Type / and press Tab to autocomplete.

Switching models inside a session:

[myproject] ❯ /model
  Current model: claude-opus-4-6  (provider: anthropic)

  Available models by provider:
    anthropic     claude-opus-4-6, claude-sonnet-4-6, ...
    openai        gpt-4o, gpt-4o-mini, o3-mini, ...
    ollama        llama3.3, llama3.2, phi4, mistral, ...
    ...

[myproject] ❯ /model gpt-4o
  Model set to gpt-4o  (provider: openai)

[myproject] ❯ /model ollama/qwen2.5-coder
  Model set to ollama/qwen2.5-coder  (provider: ollama)

Configuring API Keys

Method 1: Environment Variables (recommended)

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=AIza...
export MOONSHOT_API_KEY=sk-...       # Kimi
export DASHSCOPE_API_KEY=sk-...      # Qwen
export ZHIPU_API_KEY=...             # Zhipu GLM
export DEEPSEEK_API_KEY=sk-...       # DeepSeek

Method 2: Set Inside the REPL (persisted)

/config anthropic_api_key=sk-ant-...
/config openai_api_key=sk-...
/config gemini_api_key=AIza...
/config kimi_api_key=sk-...
/config qwen_api_key=sk-...
/config zhipu_api_key=...
/config deepseek_api_key=sk-...

Keys are saved to ~/.nano_claude/config.json and loaded automatically on next launch.

Method 3: Edit the Config File Directly

// ~/.nano_claude/config.json
{
  "model": "qwen/qwen-max",
  "max_tokens": 8192,
  "permission_mode": "auto",
  "verbose": false,
  "thinking": false,
  "qwen_api_key": "sk-...",
  "kimi_api_key": "sk-...",
  "deepseek_api_key": "sk-..."
}

Permission System

When prompted:

  Allow: Run: git commit -am "fix bug"  [y/N/a(ccept-all)]

• y — approve this one action
• n or Enter — deny
• a — approve and switch to accept-all for the rest of the session

Commands always auto-approved in auto mode:
ls, cat, head, tail, wc, pwd, echo, git status, git log, git diff, git show, find, grep, rg, python, node, pip show, npm list, and other read-only shell commands.

Built-in Tools

Core Tools

Memory Tools

Sub-Agent Tools

Skill Tools

MCP Tools

MCP tools are discovered automatically from configured servers and registered under the name mcp__<server>__<tool>. Claude can use them exactly like built-in tools.

Adding custom tools: See Architecture Guide for how to register your own tools.

Memory

The model can remember things across conversations using the built-in memory system.

How it works: Memories are stored as markdown files. There are two scopes:

• User scope (~/.nano_claude/memory/) — follows you across all projects
• Project scope (.nano_claude/memory/ in cwd) — specific to the current repo

A MEMORY.md index (≤ 200 lines / 25 KB) is auto-rebuilt on every save or delete and injected into the system prompt so Claude always has an overview.

Memory types:

Memory file format (~/.nano_claude/memory/coding_style.md):

---
name: coding style
description: Python formatting preferences
type: feedback
created: 2026-04-02
---
Prefer 4-space indentation and full type hints in all Python code.
**Why:** user explicitly stated this preference.
**How to apply:** apply to every Python file written or edited.

Example interaction:

You: Remember that I prefer 4-space indentation and type hints in all Python code.
AI: [calls MemorySave] Memory saved: coding_style [feedback/user]

You: /memory
  [feedback/user] coding_style (today): Python formatting preferences

You: /memory python
  [feedback/user] coding_style: Prefers 4-space indent and type hints in Python

Staleness warnings: Memories older than 1 day get a freshness note in /memory output so you know when to review or update them.

AI-ranked search: MemorySearch(query="...", use_ai=true) uses the model to rank results by relevance rather than simple keyword matching.

Skills

Skills are reusable prompt templates that give the model specialized capabilities. Two built-in skills ship out of the box — no setup required.

Built-in skills:

Quick start — custom skill:

mkdir -p ~/.nano_claude/skills

Create ~/.nano_claude/skills/deploy.md:

---
name: deploy
description: Deploy to an environment
triggers: [/deploy]
allowed-tools: [Bash, Read]
when_to_use: Use when the user wants to deploy a version to an environment.
argument-hint: [env] [version]
arguments: [env, version]
context: inline
---

Deploy $VERSION to the $ENV environment.
Full args: $ARGUMENTS

Now use it:

You: /deploy staging 2.1.0
AI: [deploys version 2.1.0 to staging]

Argument substitution:

• $ARGUMENTS — the full raw argument string
• $ARG_NAME — positional substitution by named argument (first word → first name)
• Missing args become empty strings

Execution modes:

• context: inline (default) — runs inside current conversation history
• context: fork — runs as an isolated sub-agent with fresh history; supports model override

Priority (highest wins): project-level > user-level > built-in

List skills: /skills — shows triggers, argument hint, source, and when_to_use

Skill search paths:

./.nano_claude/skills/     # project-level (overrides user-level)
~/.nano_claude/skills/     # user-level

Sub-Agents

The model can spawn independent sub-agents to handle tasks in parallel.

Specialized agent types — built-in:

Basic usage:

You: Search this codebase for all TODO comments and summarize them.
AI: [calls Agent(prompt="...", subagent_type="researcher")]
    Sub-agent reads files, greps for TODOs...
    Result: Found 12 TODOs across 5 files...

Background mode — spawn without waiting, collect result later:

AI: [calls Agent(prompt="run all tests", name="test-runner", wait=false)]
AI: [continues other work...]
AI: [calls CheckAgentResult / SendMessage to follow up]

Git worktree isolation — agents work on an isolated branch with no conflicts:

Agent(prompt="refactor auth module", isolation="worktree")

The worktree is auto-cleaned up if no changes were made; otherwise the branch name is reported.

Custom agent types — create ~/.nano_claude/agents/myagent.md:

---
name: myagent
description: Specialized for X
model: claude-haiku-4-5-20251001
tools: [Read, Grep, Bash]
---
Extra system prompt for this agent type.

List running agents: /agents

Sub-agents have independent conversation history, share the file system, and are limited to 3 levels of nesting.

MCP (Model Context Protocol)

MCP lets you connect any external tool server — local subprocess or remote HTTP — and Claude can use its tools automatically. This is the same protocol Claude Code uses to extend its capabilities.

Supported transports

Configuration

Place a .mcp.json file in your project directory or edit ~/.nano_claude/mcp.json for user-wide servers.

{
  "mcpServers": {
    "git": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git"]
    },
    "filesystem": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-filesystem", "/tmp"]
    },
    "my-remote": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "headers": {"Authorization": "Bearer my-token"}
    }
  }
}

Config priority: .mcp.json (project) overrides ~/.nano_claude/mcp.json (user) by server name.

Quick start

# Install a popular MCP server
pip install uv        # uv includes uvx
uvx mcp-server-git --help   # verify it works

# Add to user config via REPL
/mcp add git uvx mcp-server-git

# Or create .mcp.json in your project dir, then:
/mcp reload

REPL commands

/mcp                          # list servers + their tools + connection status
/mcp reload                   # reconnect all servers, refresh tool list
/mcp reload git               # reconnect a single server
/mcp add myserver uvx mcp-server-x   # add stdio server
/mcp remove myserver          # remove from user config

How Claude uses MCP tools

Once connected, Claude can call MCP tools directly:

You: What files changed in the last git commit?
AI: [calls mcp__git__git_diff_staged()]
    → shows diff output from the git MCP server

Tool names follow the pattern mcp__<server_name>__<tool_name>. All characters
that are not alphanumeric or _ are automatically replaced with _.

Popular MCP servers

Browse the full registry at modelcontextprotocol.io/servers

Context Compression

Long conversations are automatically compressed to stay within the model's context window.

Two layers:

1. Snip — Old tool outputs (file reads, bash results) are truncated after a few turns. Fast, no API cost.
2. Auto-compact — When token usage exceeds 70% of the context limit, older messages are summarized by the model into a concise recap.

This happens transparently. You don't need to do anything.

Diff View

When the model edits or overwrites a file, you see a git-style diff:

  Changes applied to config.py:

--- a/config.py
+++ b/config.py
@@ -12,7 +12,7 @@
     "model": "claude-opus-4-6",
-    "max_tokens": 8192,
+    "max_tokens": 16384,
     "permission_mode": "auto",

Green lines = added, red lines = removed. New file creations show a summary instead.

CLAUDE.md Support

Place a CLAUDE.md file in your project to give the model persistent context about your codebase. Nano Claude automatically finds and injects it into the system prompt.

~/.claude/CLAUDE.md          # Global — applies to all projects
/your/project/CLAUDE.md      # Project-level — found by walking up from cwd

Example CLAUDE.md:

# Project: FastAPI Backend

## Stack
- Python 3.12, FastAPI, PostgreSQL, SQLAlchemy 2.0, Alembic
- Tests: pytest, coverage target 90%

## Conventions
- Format with black, lint with ruff
- Full type annotations required
- New endpoints must have corresponding tests

## Important Notes
- Never hard-code credentials — use environment variables
- Do not modify existing Alembic migration files
- The `staging` branch deploys automatically to staging on push

Session Management

# Inside REPL:
/save                          # auto-name: session_20260401_143022.json
/save debug_auth_bug           # named save

/load                          # list all saved sessions
/load debug_auth_bug           # resume a session
/load session_20260401_143022.json

Sessions are stored as JSON in ~/.nano_claude/sessions/.

Project Structure

nano_claude_code/
├── nano_claude.py        # Entry point: REPL + slash commands + diff rendering
├── agent.py              # Agent loop: streaming, tool dispatch, compaction
├── providers.py          # Multi-provider: Anthropic, OpenAI-compat streaming
├── tools.py              # Core tools (Read/Write/Edit/Bash/Glob/Grep/Web) + registry wiring
├── tool_registry.py      # Tool plugin registry: register, lookup, execute
├── compaction.py         # Context compression: snip + auto-summarize
├── context.py            # System prompt builder: CLAUDE.md + git + memory
├── config.py             # Config load/save/defaults
│
├── multi_agent/          # Multi-agent package
│   ├── __init__.py       # Re-exports
│   ├── subagent.py       # AgentDefinition, SubAgentManager, worktree helpers
│   └── tools.py          # Agent, SendMessage, CheckAgentResult, ListAgentTasks, ListAgentTypes
├── subagent.py           # Backward-compat shim → multi_agent/
│
├── memory/               # Memory package
│   ├── __init__.py       # Re-exports
│   ├── types.py          # MEMORY_TYPES and format guidance
│   ├── store.py          # save/load/delete/search, MEMORY.md index rebuilding
│   ├── scan.py           # MemoryHeader, age/freshness helpers
│   ├── context.py        # get_memory_context(), truncation, AI search
│   └── tools.py          # MemorySave, MemoryDelete, MemorySearch, MemoryList
├── memory.py             # Backward-compat shim → memory/
│
├── skill/                # Skill package
│   ├── __init__.py       # Re-exports; imports builtin to register built-ins
│   ├── loader.py         # SkillDef, parse, load_skills, find_skill, substitute_arguments
│   ├── builtin.py        # Built-in skills: /commit, /review
│   ├── executor.py       # execute_skill(): inline or forked sub-agent
│   └── tools.py          # Skill, SkillList
├── skills.py             # Backward-compat shim → skill/
│
├── mcp/                  # MCP (Model Context Protocol) package
│   ├── __init__.py       # Re-exports
│   ├── types.py          # MCPServerConfig, MCPTool, MCPServerState, JSON-RPC helpers
│   ├── client.py         # StdioTransport, HttpTransport, MCPClient, MCPManager
│   ├── config.py         # Load .mcp.json (project) + ~/.nano_claude/mcp.json (user)
│   └── tools.py          # Auto-discover + register MCP tools into tool_registry
│
└── tests/                # 135 unit tests
    ├── test_mcp.py
    ├── test_memory.py
    ├── test_skills.py
    ├── test_subagent.py
    ├── test_tool_registry.py
    ├── test_compaction.py
    └── test_diff_view.py

For developers: Each feature package (multi_agent/, memory/, skill/, mcp/) is self-contained. Add custom tools by calling register_tool(ToolDef(...)) from any module imported by tools.py.

FAQ

Q: How do I add an MCP server?

Option 1 — via REPL (stdio server):

/mcp add git uvx mcp-server-git

Option 2 — create .mcp.json in your project:

{
  "mcpServers": {
    "git": {"type": "stdio", "command": "uvx", "args": ["mcp-server-git"]}
  }
}

Then run /mcp reload or restart. Use /mcp to check connection status.

Q: An MCP server is showing an error. How do I debug it?

/mcp                    # shows error message per server
/mcp reload git         # try reconnecting

If the server uses stdio, make sure the command is in your $PATH:

which uvx               # should print a path
uvx mcp-server-git      # run manually to see errors

Q: Can I use MCP servers that require authentication?

For HTTP/SSE servers with a Bearer token:

{
  "mcpServers": {
    "my-api": {
      "type": "sse",
      "url": "https://myserver.example.com/sse",
      "headers": {"Authorization": "Bearer sk-my-token"}
    }
  }
}

For stdio servers with env-based auth:

{
  "mcpServers": {
    "brave": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-brave-search"],
      "env": {"BRAVE_API_KEY": "your-key"}
    }
  }
}

Q: Tool calls don't work with my local Ollama model.

Not all models support function calling. Use one of the recommended tool-calling models: qwen2.5-coder, llama3.3, mistral, or phi4.

ollama pull qwen2.5-coder
python nano_claude.py --model ollama/qwen2.5-coder

Q: How do I connect to a remote GPU server running vLLM?

/config custom_base_url=http://your-server-ip:8000/v1
/config custom_api_key=your-token
/model custom/your-model-name

Q: How do I check my API cost?

/cost

  Input tokens:  3,421
  Output tokens:   892
  Est. cost:     $0.0648 USD

Q: Can I use multiple API keys in the same session?

Yes. Set all the keys you need upfront (via env vars or /config). Then switch models freely — each call uses the key for the active provider.

Q: How do I make a model available across all projects?

Add keys to ~/.bashrc or ~/.zshrc. Set the default model in ~/.nano_claude/config.json:

{ "model": "claude-sonnet-4-6" }

Q: Qwen / Zhipu returns garbled text.

Ensure your DASHSCOPE_API_KEY / ZHIPU_API_KEY is correct and the account has sufficient quota. Both providers use UTF-8 and handle Chinese well.

Q: Can I pipe input to nano claude?

echo "Explain this file" | python nano_claude.py --print --accept-all
cat error.log | python nano_claude.py -p "What is causing this error?"

Q: How do I run it as a CLI tool from anywhere?

# Add an alias to ~/.bashrc or ~/.zshrc
alias nc='python /path/to/nano_claude_code/nano_claude.py'

# Or install as a script
pip install -e .   # if setup.py exists