learn-claude-code

Implements a minimal but complete agent loop pattern where an LLM (Claude) perceives environment state, reasons about next actions, and executes tool calls in a synchronous request-response cycle. The harness captures tool outputs as observations, feeds them back into the next loop iteration, and maintains conversation history across cycles. This is the foundational pattern taught in s01 and reused throughout all 12 sessions.

Routes LLM-generated tool calls to concrete implementations (bash, read_file, write_file, edit_file, load_skill, task_* operations) via a schema registry that defines input/output contracts. The harness validates tool schemas against LLM requests, executes the tool in an isolated context, captures output, and returns it to the agent. This is taught in s02 and extended throughout the curriculum.

Implements a task claiming mechanism (s11) where agents autonomously claim tasks from a shared task board based on their capabilities and current workload. Agents can evaluate task requirements, decide whether to claim a task, and update task status. This enables self-organizing agent teams without a central scheduler.

Implements WorktreeManager (s12) that creates isolated filesystem subtrees for each agent or task, preventing cross-contamination and enabling parallel execution. Each worktree is a separate directory with its own file state, and agents can only access files within their worktree. This is the final session and combines all previous concepts into a complete isolated execution environment.

Structures the entire framework as a 12-session curriculum (s01–s12) where each session introduces exactly one harness mechanism without modifying the core agent loop. Sessions build incrementally: s01 teaches the loop, s02 adds tools, s03 adds planning, s04 adds subagents, s05 adds skills, s06 adds compression, s07 adds tasks, s08 adds background execution, s09 adds teams, s10 adds protocols, s11 adds autonomous claiming, s12 adds worktree isolation. This design makes the framework explicitly educational and modular.

Implements a permission layer that validates file paths against a safe_path whitelist before executing read/write/edit operations, and blocks dangerous bash commands (rm -rf, sudo, etc.) via a blocklist. The harness intercepts tool calls at dispatch time, checks paths and commands against rules, and rejects unsafe operations before they reach the OS. This is a core security mechanism taught in the overview and applied throughout.

Provides a persistent task board (TodoManager) where agents can write, read, and update tasks in a structured format. Tasks are stored as markdown with metadata (status, assignee, priority), and the agent can decompose complex goals into subtasks, track progress, and coordinate with other agents. This is introduced in s03 and extended in s07 (TaskManager) and s09 (multi-agent teams).

Allows a parent agent to spawn child agents (subagents) with isolated context, separate tool access, and independent task boards. Each subagent runs its own agent loop with a subset of the parent's tools and knowledge, and communicates back via message passing. This is taught in s04 and forms the foundation for multi-agent teams in s09.

Implements a SkillLoader that reads markdown files from a skills/ directory and injects them into the agent's context as knowledge. Skills are markdown documents describing tools, APIs, or domain knowledge that the agent can reference during reasoning. The two-layer injection strategy (s05) allows skills to be loaded at runtime without modifying the agent loop or tool registry.

Implements a context compression pipeline (s06) that summarizes or prunes conversation history, task boards, and skill content to reduce token usage while preserving semantic meaning. The harness can compress context before sending to the LLM, trading off detail for cost and latency. Compression strategies include summarization, chunking, and selective retention of recent/important messages.

Provides a BackgroundManager (s08) that allows agents to spawn long-running tasks that execute asynchronously while the agent loop continues. Background tasks are tracked in a job queue, can be polled for status, and can emit events when complete. This enables agents to parallelize work without blocking the main loop.

Implements a MessageBus (s10) that allows multiple agents to communicate asynchronously via message passing. Agents can publish messages to topics, subscribe to topics, and react to messages from teammates. This enables team protocols (FSMs, workflows) where agents coordinate work without shared mutable state. Teams are taught in s09, with protocols in s10.

Allows teams of agents to follow structured protocols defined as finite state machines (FSMs) or workflow specifications. Protocols define valid state transitions, which agents can trigger via messages, and enforce rules about who can do what in each state. This is taught in s10 and enables complex multi-agent behaviors like approval workflows, handoffs, and consensus patterns.