$ show shareAI-lab/learn-claude-code
This repository is a comprehensive tutorial on building AI agent harnesses, structured as 17 progressive lessons. Each lesson introduces a single mechanism (tool use, permissions, hooks, planning, subagents, skill loading, context compaction, memory, task system, background tasks, cron scheduler, agent teams, MCP integration, workflow runtime, and goal loop) that extends a core agent loop without modifying it. The harness enables a language model (Claude) to perceive, reason, and act through tool interactions while managing context, permissions, and collaboration. The repository includes runnable Python implementations for each lesson and an interactive Next.js web application with visualizations for learning and experimentation.
The LLM identified 3 files worth highlighting for reuse:
Implements a lightweight hook system with register_hook() and trigger_hooks() for UserPromptSubmit, PreToolUse, PostToolUse, and Stop events. Demonstrates the observer pattern for adding cross-cutting concerns (permissions, logging) without modifying the core agent loop. Self-contained, framework-agnostic, and reusable in any Python application requiring event-driven extensibility.
Defines a TOOL_HANDLERS dictionary mapping tool names to functions, with tool schemas for input validation. Shows how to safely extract tool_use blocks from LLM responses, execute corresponding handlers, and format tool_result outputs. Isolated pattern that can be extracted with minimal modification; only requires defining handler functions and schemas. Demonstrates secure tool dispatch for LLM-mediated API interactions.
Provides a MessageBus class with file-backed JSONL mailboxes for persistent agent communication. Implements request/response correlation using message IDs, condition variables for efficient signaling, and file locking for cross-process safety. Self-contained component usable in any Python application needing reliable, durable messaging between processes or threads. Demonstrates robust inter-agent communication patterns.