shareAI-lab/learn-claude-code

Learn Claude Code – A nano Claude Code-like agent, built from 0 to 1

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


                    THE AGENT PATTERN
                    =================

    User --> messages[] --> LLM --> response
                                      |
                            stop_reason == "tool_use"?
                           /                          \
                         yes                           no
                          |                             |
                    execute tools                    return text
                    append results
                    loop back -----------------> messages[]


    That's the minimal loop. Every AI coding agent needs this loop.
    Production agents add policy, permissions, and lifecycle layers.

12 progressive sessions, from a simple loop to isolated autonomous execution. Each session adds one mechanism. Each mechanism has one motto.

s01 “One loop & Bash is all you need” — one tool + one loop = an agent

s02 “Adding a tool means adding one handler” — the loop stays the same; new tools register into the dispatch map

s03 “An agent without a plan drifts” — list the steps first, then execute; completion doubles

s04 “Break big tasks down; each subtask gets a clean context” — subagents use independent messages[], keeping the main conversation clean

s05 “Load knowledge when you need it, not upfront” — inject via tool_result, not the system prompt

s06 “Context will fill up; you need a way to make room” — three-layer compression strategy for infinite sessions

s07 “Break big goals into small tasks, order them, persist to disk” — a file-based task graph with dependencies, laying the foundation for multi-agent collaboration

s08 “Run slow operations in the background; the agent keeps thinking” — daemon threads run commands, inject notifications on completion

s09 “When the task is too big for one, delegate to teammates” — persistent teammates + async mailboxes

s10 “Teammates need shared communication rules” — one request-response pattern drives all negotiation

s11 “Teammates scan the board and claim tasks themselves” — no need for the lead to assign each one

s12 “Each works in its own directory, no interference” — tasks manage goals, worktrees manage directories, bound by ID

The Core Pattern

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        messages.append({"role": "assistant",
                         "content": response.content})

        if response.stop_reason != "tool_use":
            return

        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

Every session layers one mechanism on top of this loop – without changing the loop itself.

Scope (Important)

This repository is a 0->1 learning project for building a nano Claude Code-like agent. It intentionally simplifies or omits several production mechanisms:

Full event/hook buses (for example PreToolUse, SessionStart/End, ConfigChange).
s12 includes only a minimal append-only lifecycle event stream for teaching.
Rule-based permission governance and trust workflows
Session lifecycle controls (resume/fork) and advanced worktree lifecycle controls
Full MCP runtime details (transport/OAuth/resource subscribe/polling)

Treat the team JSONL mailbox protocol in this repo as a teaching implementation, not a claim about any specific production internals.

Quick Start

1
2
3
4
5
6
7
8


git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env   # Edit .env with your ANTHROPIC_API_KEY

python agents/s01_agent_loop.py       # Start here
python agents/s12_worktree_task_isolation.py  # Full progression endpoint
python agents/s_full.py               # Capstone: all mechanisms combined

Web Platform

Interactive visualizations, step-through diagrams, source viewer, and documentation.

1

cd web && npm install && npm run dev   # http://localhost:3000

Learning Path

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


Phase 1: THE LOOP                    Phase 2: PLANNING & KNOWLEDGE
==================                   ==============================
s01  The Agent Loop          [1]     s03  TodoWrite               [5]
     while + stop_reason                  TodoManager + nag reminder
     |                                    |
     +-> s02  Tool Use            [4]     s04  Subagents            [5]
              dispatch map: name->handler     fresh messages[] per child
                                              |
                                         s05  Skills               [5]
                                              SKILL.md via tool_result
                                              |
                                         s06  Context Compact      [5]
                                              3-layer compression

Phase 3: PERSISTENCE                 Phase 4: TEAMS
==================                   =====================
s07  Tasks                   [8]     s09  Agent Teams             [9]
     file-based CRUD + deps graph         teammates + JSONL mailboxes
     |                                    |
s08  Background Tasks        [6]     s10  Team Protocols          [12]
     daemon threads + notify queue        shutdown + plan approval FSM
                                          |
                                     s11  Autonomous Agents       [14]
                                          idle cycle + auto-claim
                                     |
                                     s12  Worktree Isolation      [16]
                                          task coordination + optional isolated execution lanes

                                     [N] = number of tools

Architecture

1
2
3
4
5
6
7


learn-claude-code/
|
|-- agents/                        # Python reference implementations (s01-s12 + s_full capstone)
|-- docs/{en,zh,ja}/               # Mental-model-first documentation (3 languages)
|-- web/                           # Interactive learning platform (Next.js)
|-- skills/                        # Skill files for s05
+-- .github/workflows/ci.yml      # CI: typecheck + build

Documentation

Mental-model-first: problem, solution, ASCII diagram, minimal code. Available in English | 中文 | 日本語.

Session	Topic	Motto
s01	The Agent Loop	One loop & Bash is all you need
s02	Tool Use	Adding a tool means adding one handler
s03	TodoWrite	An agent without a plan drifts
s04	Subagents	Break big tasks down; each subtask gets a clean context
s05	Skills	Load knowledge when you need it, not upfront
s06	Context Compact	Context will fill up; you need a way to make room
s07	Tasks	Break big goals into small tasks, order them, persist to disk
s08	Background Tasks	Run slow operations in the background; the agent keeps thinking
s09	Agent Teams	When the task is too big for one, delegate to teammates
s10	Team Protocols	Teammates need shared communication rules
s11	Autonomous Agents	Teammates scan the board and claim tasks themselves
s12	Worktree + Task Isolation	Each works in its own directory, no interference

What’s Next – from understanding to shipping

After the 12 sessions you understand how an agent works inside out. Two ways to put that knowledge to work:

Kode Agent CLI – Open-Source Coding Agent CLI

npm i -g @shareai-lab/kode

Skill & LSP support, Windows-ready, pluggable with GLM / MiniMax / DeepSeek and other open models. Install and go.

GitHub: shareAI-lab/Kode-cli

Kode Agent SDK – Embed Agent Capabilities in Your App

The official Claude Code Agent SDK communicates with a full CLI process under the hood – each concurrent user means a separate terminal process. Kode SDK is a standalone library with no per-user process overhead, embeddable in backends, browser extensions, embedded devices, or any runtime.

GitHub: shareAI-lab/Kode-agent-sdk

Sister Repo: from on-demand sessions to always-on assistant

The agent this repo teaches is use-and-discard – open a terminal, give it a task, close when done, next session starts blank. That is the Claude Code model.

OpenClaw proved another possibility: on top of the same agent core, two mechanisms turn the agent from “poke it to make it move” into “it wakes up every 30 seconds to look for work”:

Heartbeat – every 30s the system sends the agent a message to check if there is anything to do. Nothing? Go back to sleep. Something? Act immediately.
Cron – the agent can schedule its own future tasks, executed automatically when the time comes.

Add multi-channel IM routing (WhatsApp / Telegram / Slack / Discord, 13+ platforms), persistent context memory, and a Soul personality system, and the agent goes from a disposable tool to an always-on personal AI assistant.

claw0 is our companion teaching repo that deconstructs these mechanisms from scratch:

1

claw agent = agent core + heartbeat + cron + IM chat + memory + soul

1
2
3
4


learn-claude-code                   claw0
(agent runtime core:                (proactive always-on assistant:
 loop, tools, planning,              heartbeat, cron, IM channels,
 teams, worktree isolation)          memory, soul personality)

About

Scan with Wechat to fellow us,
or fellow on X: shareAI-Lab

License

MIT

The model is the agent. Our job is to give it tools and stay out of the way.