nano-claude-code

Claude Code leaked today: 1,903 files, 513,083 lines. I compressed the whole thing down to 13 files and about 4.2k lines, and it actually works. Lightweight, hackable, and built to be fully understood.

That makes nano-claude-code roughly 146x smaller by file count and 119x smaller by line count than the leaked codebase snapshot.

nano-claude-code keeps the useful parts of a Claude Code style harness:

a real model + tool loop
core coding tools
web search and fetch
MCP integration
local skills
a simple terminal UI
project instructions via NANO.md
path-scoped rules via .nano/rules/*.md

It leaves out most of the surrounding product surface that makes larger agent repos hard to reason about.

Why I Built nano-claude-code

Claude Code style agents feel good because of the harness, not because they are giant.

The repo snapshot I started from was powerful, but far too large to comfortably reason about end to end: 1,903 files and 513,083 lines. For a solo fork that I want to modify aggressively, that is too much surface area.

nano-claude-code keeps the same core shape in a codebase small enough to inspect directly:

one process
a handful of source files
explicit built-in tools
local transcripts
local skills
MCP support without a plugin empire

The point is not to recreate every feature. The point is to keep the part that actually matters: a tight coding-agent loop you can trust yourself to edit.

Quick Start

Requirements:

Node 22+
an ANTHROPIC_API_KEY
rg if you want fast grep_files

Create a .env file:

hljs language-bash

cd /Users/composio/Downloads/src/nano-claude-code
printf 'ANTHROPIC_API_KEY=your_key_here\n' > .env

Install the command globally on your machine:

hljs language-bash

cd /Users/composio/Downloads/src/nano-claude-code
npm link

Start interactive mode:

hljs language-bash

nano-claude-code

Or run it locally from the repo without installing:

hljs language-bash

npm run chat --

Initialize NANO.md and the rules directory:

hljs language-bash

nano-claude-code /init

Run a one-shot prompt:

hljs language-bash

nano-claude-code "summarize this repo"

Run against another workspace:

hljs language-bash

nano-claude-code --workspace /path/to/project "fix the failing tests"

Philosophy

Small enough to understand.

One process, a few source files, no build graph, no framework maze. If you want to understand the whole repo, you actually can.

Built for direct customization.

This repo is meant to be changed in code, not stretched through config sprawl. If you want different behavior, edit the harness.

Core loop first.

The important part is:

build the system prompt
send messages and tools to the model
execute tool calls
append tool results
continue until the model stops

Everything else is secondary.

AI-native interface.

No dashboard. No wizard. No orchestration theater. Open the CLI, tell the agent what to do, and change the code when you want different behavior.

Skills over feature sprawl.

Instead of stuffing every behavior into core, nano-claude-code can load local SKILL.md files and MCP servers. The base stays small.

Project instructions as files.

Like CLAUDE.md in Claude Code, nano-claude-code can load project instructions from NANO.md.

Rules when you need them.

Put path-scoped instructions in .nano/rules/*.md instead of cramming everything into one file.

What It Supports

coding tools: bash, list_files, grep_files, read_file, write_file, edit_file, apply_patch
web tools: web_search, web_fetch
project instructions: NANO.md, .nano/NANO.md, .nano/rules/*.md, NANO.local.md
skills: list_skills, load_skill, plus prompt-triggered skill preloading like $code-review
MCP: stdio, streamable http, and legacy sse
subagents: delegate_task
structured diffs for file-changing tools
JSONL session transcripts
approval prompts for risky tools
retry/backoff for transient Anthropic overload and network failures
interactive error recovery so failed turns do not kill the session

Usage

Try this in the interactive shell:

hljs language-text

/status
/skills
Use $code-review to review src/mcp.js

Useful commands:

/help
/init
/status
/skills
/clear
/exit

Ctrl+C exits cleanly.

Customizing

nano-claude-code is intentionally small enough that customization should happen in code.

Examples:

add repo-specific instructions in NANO.md
change the default model in src/config.js
change the UI behavior in src/ui.js
change prompt behavior in src/agent.js
add or remove built-in tools in src/tools.js
add local behavior via skills/*/SKILL.md
add external capabilities through .nano-claude-code/mcp.json

This repo is designed to be forked and changed, not merely configured.

Architecture

Key files:

src/cli.js - CLI entrypoint and interactive loop
src/agent.js - model/tool execution loop
src/anthropic.js - Anthropic client with retry and backoff
src/tools.js - built-in tools, tool execution, and tool-result compaction
src/mcp.js - MCP transport handling and dynamic tool wiring
src/skills.js - local skill discovery and loading
src/ui.js - terminal UI, loading indicator, prompts, and error rendering
src/transcript.js - session persistence
src/config.js - CLI flags, defaults, and .env loading
src/nano.js - NANO.md / .nano/rules instruction loading
skills/code-review/SKILL.md - sample built-in skill

System shape:

hljs language-text

CLI -> Agent Loop -> Anthropic Messages API
                -> Built-in Tools
                -> MCP Tools
                -> Local Skills
                -> JSONL Transcript

Skills

Skills are plain local instruction files loaded from:

<workspace>/skills/*/SKILL.md
<workspace>/.nano-claude-code/skills/*/SKILL.md
any extra --skills-dir

If a prompt explicitly mentions a skill like $code-review, nano-claude-code preloads that skill into the turn prompt.

NANO.md

nano-claude-code supports workspace instruction files that behave like a lightweight CLAUDE.md equivalent.

Load order:

NANO.md
nano.md
.nano/NANO.md
.nano/nano.md
.nano/rules/**/*.md
NANO.local.md
nano.local.md

Later files have higher priority.

Rules under .nano/rules/*.md can also use simple frontmatter:

hljs language-md

---
paths:
  - "src/**/*.js"
  - "tests/**"
---

Run vitest for this part of the repo.

Path-scoped rules are included when the prompt mentions files or directories that match those globs.

Simple @include lines are also supported:

hljs language-text

@./docs/coding-style.md
@~/.nano/private-notes.md

Included files are loaded before the file that references them.

MCP

nano-claude-code can load MCP servers from .nano-claude-code/mcp.json or --mcp-config.

Example:

hljs language-json

{
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    },
    "remote-http-server": {
      "transport": "http",
      "url": "https://example.com/mcp"
    },
    "legacy-sse-server": {
      "transport": "sse",
      "url": "https://example.com/sse"
    }
  }
}

Connected MCP servers contribute dynamic tool definitions directly to the model.

Local session logs and generated runtime state live under .nano-claude-code/.

Safety Model

This is a small local harness, not a hardened sandbox product.

file tools are locked to the workspace root
bash runs in the workspace root
risky tools go through approval prompts when --approval-mode ask is active
MCP helper tools also require approval

The safety model is intentionally simple and visible in code.

Reliability

transient 429, 529, and other 5xx Anthropic failures retry with backoff
common network failures retry automatically
large tool results are compacted before they are sent back to the model
interactive mode stays alive after failed turns
one-shot mode still exits nonzero on failure, which is useful for scripting

End-To-End Tests

Minimal skill test:

hljs language-bash

cd /Users/composio/Downloads/src/nano-claude-code
nano-claude-code --approval-mode auto "First call list_skills, then call load_skill for code-review, then answer with the skill name and one sentence on what it does."

MCP plus skills:

hljs language-bash

cd /Users/composio/Downloads/src/nano-claude-code
nano-claude-code --approval-mode ask "Use $code-review, inspect the repo, and tell me what MCP tools and resources are available before making any edits."

Flags

--workspace <path>: target repo to operate in
--model <id>: Anthropic model ID
--max-turns <n>: max tool/action rounds per user turn
--max-subagent-depth <n>: maximum nested delegation depth
--approval-mode ask|auto: interactive confirmation for risky tools, or auto-approve them
--mcp-config <path>: explicit MCP config file; defaults to .nano-claude-code/mcp.json
--skills-dir <path>: additional skill directory; repeatable
--session <uuid>: explicit session ID
--resume <uuid>: load messages from an existing session log

Development

Syntax check the repo:

hljs language-bash

npm run check

There is no build step. That is intentional.

If you want to remove the global command later:

hljs language-bash

cd /Users/composio/Downloads/src/nano-claude-code
npm unlink -g

nano-claude-code

nano-claude-code

Why I Built nano-claude-code

Quick Start

Philosophy

What It Supports

Usage

Customizing

Architecture

Skills

NANO.md

MCP

Safety Model

Reliability

End-To-End Tests

Flags

Development

Similar Packages

Repository

Tags

Original Author

Publisher