Deep Dive: learn-claude-code

The entire agent is 30 lines of Python. A while True loop sends messages + tool definitions to the LLM, checks if stop_reason == "tool_use", executes tools if yes, appends results, and loops back. When the model stops calling tools, the function returns.

Key Takeaways

• The core loop is the same in every session — everything else is layered on top
• One tool (bash) + one loop = a functioning agent
• messages[] is the accumulating state — both user and tool results live here
• The exit condition (stop_reason) is what makes it autonomous rather than one-shot

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 = [execute_tool(block) for block in response.content
                   if block.type == "tool_use"]
        messages.append({"role": "user", "content": results})

Introduces the dispatch map pattern: a simple dict mapping tool names to handler functions. Adding a new tool = adding one entry to the dict + one schema entry. The loop itself never changes.

Key Takeaways

• TOOL_HANDLERS = {"bash": run_bash, "read_file": run_read, ...}
• Path sandboxing via safe_path() — prevents workspace escape
• Dedicated tools (read/write/edit) are safer and more predictable than shelling out for everything
• The dispatch map scales linearly — no if/elif chains

Adds a TodoManager — a structured task list where only one item can be in_progress at a time. Plus a nag reminder: if the model goes 3+ rounds without updating its todos, a <reminder> gets injected into the next tool result.

Key Takeaways

• "One in_progress at a time" forces sequential focus — prevents the agent from wandering
• The nag reminder is a simple but effective pattern: inject text into tool_result to redirect attention
• System prompts fade as context fills up — in-context reminders fight this signal decay
• This is Claude Code's actual TodoWrite mechanism

The parent agent gets a task tool that spawns a subagent with fresh messages=[]. The child does all its work (potentially 30+ tool calls), then only the final text summary returns to the parent as a tool_result. The child's entire message history is discarded.

Key Takeaways

• Context isolation: child's work (file reads, bash outputs) never pollutes parent context
• No recursive spawning: children get all tools except task
• This is the pattern behind Claude Code's /task command and OpenClaw's sessions_spawn
• 30-iteration safety limit prevents infinite loops

Two-layer skill injection: Layer 1 puts skill names/descriptions in the system prompt (~100 tokens each). Layer 2 loads the full skill body via tool_result when the model calls load_skill("name") (~2000 tokens each).

Key Takeaways

• 10 skills × 2000 tokens = 20,000 tokens wasted if all loaded upfront
• The two-layer pattern (cheap metadata + expensive on-demand body) is elegant and token-efficient
• Skills are SKILL.md files with YAML frontmatter in directories
• This is exactly how OpenClaw's available_skills system works

Three-layer compression strategy:

• Layer 1 — micro_compact (every turn): Replace old tool results (3+ turns back) with "[Previous: used {tool_name}]"
• Layer 2 — auto_compact (at token threshold): Save full transcript to .transcripts/, LLM summarizes, replace all messages with summary
• Layer 3 — manual compact: Model explicitly calls compact tool

Key Takeaways

• Micro-compact is the killer feature: silently cleaning old tool results every turn is low-cost, high-impact
• Transcripts on disk = nothing truly lost, just moved out of active context
• The token estimate is rough (len(json.dumps(messages)) // 4) — good enough for a threshold trigger
• This is how OpenClaw handles compaction internally

Promotes s03's flat checklist into a file-based task graph. Each task is a JSON file with status, blockedBy, and blocks fields. Completing a task automatically clears its ID from all dependents' blockedBy lists.

Key Takeaways

• Task graph answers 3 questions: What's ready? What's blocked? What's done?
• Survives compression and restarts — state lives on disk, not in context
• DAG (Directed Acyclic Graph) pattern enables parallel execution in later sessions
• 4 tools: task_create, task_update, task_list, task_get

Uses daemon threads for long-running shell commands. Results go into a notification queue that gets drained before each LLM call — injected as <background-results> blocks.

Key Takeaways

• The agent loop stays single-threaded — only subprocess I/O is parallelized
• Notification queue pattern: producer (bg thread) → queue → consumer (agent loop)
• Enables "install deps AND write config simultaneously"
• 300s timeout per background task as safety valve

Introduces persistent teammates with lifecycle management (spawn → working → idle → shutdown) and JSONL mailboxes for inter-agent communication. Each teammate runs its own agent loop in a daemon thread.

Key Takeaways

• JSONL mailboxes: append-only files per agent, drain-on-read — simple, crash-safe IPC
• Teammates check inbox before each LLM call — messages are context, not interrupts
• Team roster in config.json tracks who exists and their status
• Unlike subagents (s04), teammates persist and have identity

Adds two structured protocols on top of the mailbox system:

• Shutdown protocol: request_id handshake — lead requests shutdown, teammate approves/rejects
• Plan approval: teammate submits plan with request_id, lead reviews and approves/rejects

Key Takeaways

• Both protocols share the same FSM: pending → approved | rejected
• Correlation via request_id — same pattern as HTTP request/response correlation
• One pattern (request→response with ID) handles any structured negotiation
• Without shutdown protocol, killing a thread leaves files half-written

Teammates become self-organizing: instead of being assigned tasks, they scan the task board and auto-claim unclaimed work. Work phase → idle phase (poll every 5s for messages/tasks) → timeout → shutdown.

Key Takeaways

• Idle cycle: poll inbox + scan task board → 60s timeout → auto-shutdown
• Identity re-injection: after context compression, the agent might forget who it is — inject identity block when len(messages) <= 3
• Self-organization scales better than lead-assigned work
• Task claiming: find pending + unowned + unblocked tasks

Each task gets its own git worktree directory. Task board tracks what to do, worktrees track where to do it. Bound by task ID. Lifecycle events emitted to events.jsonl.

Key Takeaways

• Control plane (.tasks/) + execution plane (.worktrees/) = clean separation
• Two agents can work on different modules simultaneously without file conflicts
• Worktree lifecycle: absent → active → removed | kept
• Event stream (events.jsonl) enables audit, recovery, and monitoring
• State on disk survives crashes — conversation memory is volatile, file state is durable