shareAI-lab/learn-claude-code

This system is an educational curriculum and reference implementation for building autonomous AI agents, structured as a progressive series of Python lesson modules. It demonstrates core orchestration capabilities including tool dispatch, permission gating, hook-based extensibility, context management, and persistent memory. The platform also covers advanced runtime features such as multi-agent teams, background task execution, cron scheduling, and external MCP tool integration. A companion web interface provides interactive visualizations and documentation to guide users through these architectural patterns.

The s03\_permission module introduces a safety layer that intercepts tool execution before it runs. It enforces three gates: a hard deny list (blocking commands like \rm -rf /\ and \sudo\), rule-based matching (flagging workspace escapes for file tools and destructive patterns like \rm\/\del\ for bash), and user approval (pausing for confirmation when rules match). This ensures that potentially dangerous operations require explicit user consent or are blocked outright.

_s03\permission · high confidence

The s11 harness now supports running long-running Bash commands in background daemon threads instead of blocking the main Agent Loop. When a tool call explicitly sets the new \run\_in\_background\ parameter to true, the system returns an immediate placeholder result with a \bg\_id\, allowing the agent to continue with other tasks. Completed results are collected on subsequent turns and injected into the conversation as \\<task\_notification\>\ messages, ensuring slow operations like builds or test suites no longer stall the agent's workflow.

_s11\_background\tasks · high confidence

The web curriculum data now includes six new lesson modules (s12–s17) covering cron scheduling, agent team runtime, MCP tool integration, integrated harness composition, workflow orchestration, and goal-loop evaluation. Each module provides structured decision annotations and interactive scenario steps that demonstrate these capabilities within the agent harness.

web/src/data · high confidence

The s14 lesson adds a new harness layer that connects to external MCP servers, discovers their tools, and dynamically assembles them into the agent's tool pool. It introduces an in-process \MCPClient\ to store tool definitions and handlers, a \connect\_mcp\ function to establish connections, and an \assemble\_tool\pool\ routine that merges base tools with discovered MCP tools. Tools from different servers are prefixed (e.g., \mcp\\docs\\_search\) to prevent name collisions, and a host-side policy (\MCP\_HOST\_POLICY\) manages permissions, requiring confirmation for destructive actions. Input errors are caught at the tool boundary and returned to the model without terminating the loop.

_s14\_mcp\plugin · high confidence

The s05 harness adds a new \todo\_write\ tool that lets the agent maintain an in-memory task list with \pending\, \in\_progress\, and \completed\ statuses, capped at 20 items and allowing only one item in progress at a time. The tool accepts both list and string inputs (parsed via JSON or \ast.literal\_eval\, without \eval\), and the system prompt now encourages planning before execution. Additionally, if the agent goes three consecutive tool-use rounds without calling \todo\_write\, the harness automatically appends a \\<reminder\>Update your todos.\</reminder\>\ to the third round's results and resets the counter. This change is localized to the s05 lesson's \code.py\ (including \TodoManager\, \run\_todo\_write\, and the reminder logic), its READMEs in English, Chinese, and Japanese, and the corresponding architecture diagrams.

_s05\_todo\write · high confidence

The s07\_skill\loading module now implements a \SkillLoader\ that scans \skills/\/SKILL.md\ files at startup to build a catalog of names and descriptions, which is injected into the system prompt. Instead of loading all skill instructions upfront, the agent calls \load\_skill(name)\ at runtime to retrieve the full \SKILL.md\ content, which is then appended to the conversation as a \tool\_result\. This approach prevents unnecessary context window consumption by only loading relevant skill instructions when needed.

_s07\_skill\loading · high confidence

The s09\_memory module adds a new lesson and implementation for persistent memory, allowing the agent to save, recall, and consolidate reusable knowledge across sessions. It stores individual memories as Markdown files with YAML frontmatter in a \.memory/\ directory, indexed by \MEMORY.md\. The system uses a lightweight model call to select the most relevant records (falling back to keyword matching) and limits the total recalled text size. It automatically extracts durable information after each turn, filtering out temporary constraints and duplicates, and consolidates the store when it reaches a threshold, with snapshot-based rollback on failure.

_s09\memory · high confidence

The s01\_agent\_loop module now provides a minimal, runnable agent harness that automates the interaction between a user, an LLM, and a bash tool. The core logic is a \while True\ loop in \code.py\ that sends messages to the model, executes any \tool\_use\ blocks it returns via \run\_bash\, and feeds the results back until the model stops calling tools. The harness includes basic safety guards (blocking dangerous commands like \rm -rf /\), a 120-second timeout, and UTF-8 readline support for macOS. This location contributes the entry-point script, the loop implementation, and the English, Chinese, and Japanese README guides that explain the pattern and provide setup instructions.

_s01\_agent\loop · high confidence

The s08\_context\_compact location now provides a complete lesson (code.py and localized READMEs) that implements a four-step context compaction pipeline to prevent context window overflow. The pipeline first persists oversized tool results to disk (tool\_result\_budget), then archives the middle of the message history while preserving tool-use/result pairs (snip\_compact). If context remains full, it shortens older consumed results with recovery paths (micro\_compact) and, as a final resort, summarizes the entire history into a single compacted message (compact\_history). The code also includes a hardened destructive command filter for bash safety.

_s08\_context\compact · high confidence

Added a suite of new, step-by-step interactive visualizations in the web course curriculum to explain core agent mechanics. These components cover permission routing (allow/ask/deny), hook registration and execution, memory file management, task board dependencies, cron scheduling, team runtime coordination, MCP tool integration, and the integrated harness workflow, providing users with animated, guided explanations of how the agent system operates.

web/src/components/visualizations · high confidence

This update introduces six new Python lesson modules (s10 through s17) that progressively build out an agent runtime. s10 adds a persistent, file-backed task system with dependency tracking and cycle detection. s12 introduces a cron scheduler for time-based task execution. s13 implements multi-agent teams with shared task records and mailboxes. s15 provides an integrated harness that combines built-in tools, persistent teams, and MCP tool support. s16 adds a workflow runtime with parallel execution, journaling, and resume capabilities. s17 implements a goal loop with a session-scoped evaluator to determine when work is complete. These modules collectively expand the platform's capabilities for complex, multi-step agent orchestration.

python · high confidence

The s02 lesson expands the agent's capabilities from a single bash tool to five tools by introducing a dispatch map (\TOOL\_HANDLERS\) that replaces the previous hardcoded \run\_bash()\ call. The new tools are \read\_file\, \write\_file\, \edit\_file\, and \glob\. To ensure safety, file operations are now protected by a \safe\_path\ validation that prevents access outside the workspace directory. The core agent loop remains unchanged, only updating the single line that dispatches tool calls to the appropriate handler.

_s02\_tool\use · high confidence

The s04\_hooks module replaces the hardcoded permission checks from s03 with a flexible hook registry, allowing extension logic to hang outside the main agent loop. It introduces \register\_hook\ and \trigger\_hooks\ functions that support four events: \UserPromptSubmit\ (for input validation and context injection), \PreToolUse\ (for permission checks and logging), \PostToolUse\ (for side effects like auto-git-add and large output warnings), and \Stop\ (for cleanup and loop continuation decisions). The core \agent\_loop\ now calls \trigger\_hooks\ instead of directly invoking check functions, making the loop stable while enabling new behaviors via callbacks.

_s04\hooks · high confidence

The s06\_subagent lesson adds a new \task\ tool that runs a nested agent loop with a fresh \messages\[\]\ list, allowing focused subtasks to execute without polluting the parent conversation's context. The subagent shares the same process and working directory as the parent but is restricted to the five base tools (bash, read, write, edit, glob) and cannot delegate further. Only the subagent's final text is returned to the parent as a tool result, keeping intermediate tool calls and results local to the subagent's isolated message history.

_s06\subagent · high confidence

The learning path in the web library has been consolidated and expanded from 11 to 17 sessions (s01–s17). This update introduces new topics including Permission, Hooks, Cron Scheduler, MCP Tools, Integrated Harness, Workflow Runtime, and Goal Loop, while refining the descriptions and core additions for existing sessions. The course structure now maps these sessions across five layers: Tools & Execution, Planning & Coordination, Memory Management, Concurrency, and Collaboration, providing a more comprehensive progression for building AI agents.

web/src/lib · high confidence

The script used to generate web content now discovers course chapters by scanning repository root directories instead of relying on a fixed agents/docs directory structure. Parsing logic has been updated to correctly identify async functions and extract assignment bodies (lists and dicts) with proper handling of nested structures, quotes, and comments, ensuring more accurate extraction of code content for the curriculum.

web/scripts · high confidence

The architecture diagram now includes descriptions for four new agent concepts: CronJob, ProtocolState, MCPClient, and RecoveryState. The execution flow visualization has been significantly improved with dynamic node sizing, text wrapping, and smarter edge routing (including loop-back rails and step buses) to handle complex flows without overlap. The message flow animation was stabilized by replacing the interval-based timer with a self-scheduling timeout to prevent race conditions, and chips now wrap gracefully instead of overflowing. Additionally, the design decisions and agent loop simulator components now display explicit placeholder messages when content is unavailable for a specific lesson, rather than rendering nothing.

web/src/components/architecture · high confidence

The agent-builder reference code and scripts now explicitly handle text encoding and decoding errors. File read/write operations (read\_file, write\_file, edit\_file) and subprocess execution (run\_bash) explicitly use UTF-8 encoding and set errors='replace' to prevent crashes when encountering non-UTF-8 characters in file content or command output. Additionally, the agent-philosophy reference has been updated to reflect a shift in terminology from 'capabilities' to 'tools' and 'agent' to 'harness', aligning the documentation with the engineering focus on building the environment for the model.

skills · high confidence

Visiting the root URL now automatically redirects to the English locale (/en/). Additionally, the visual presentation of content has been refined: code blocks and tables within the prose layout now handle overflow and width more gracefully to prevent horizontal scrolling issues, and new TypeScript types have been introduced to support chapter images and agent layer classifications.

web/src/app · high confidence

The header's dark mode toggle icon no longer flashes or displays incorrectly during the initial page render. The component now waits for the client-side mount before reading the theme state from the document class, preventing hydration mismatches and ensuring the correct Sun/Moon icon is shown immediately.

web/src/components/layout · high confidence

This update resolves several stability and compatibility issues across the agent lesson files (s01–s12). File read/write operations now explicitly use UTF-8 encoding to prevent corruption of non-ASCII text. Subprocess execution is hardened to handle \OSError\ and \FileNotFoundError\ gracefully, and output decoding uses \errors='replace'\ to avoid crashes on invalid byte sequences. The interactive CLI now uses ANSI escape wrappers (\\\001\/\\\002\) to fix readline backspace issues on macOS. Additionally, the task system simplifies dependency management by removing the \blocks\ field in favor of a single-source \blockedBy\ graph, and the skill loader now uses \yaml.safe\_load\ for more robust frontmatter parsing.

agents · high confidence

Added a suite of new tests in the \tests\ directory to verify the correctness of the agent lesson implementations and runtime behaviors. These tests cover specific lesson modules (s03 through s17, including agent teams, background tasks, cron scheduling, goal loops, and context compaction) by loading their code dynamically with mocked dependencies. The test suite validates functional requirements such as UTF-8 handling for text tools, recursive glob matching, permission command word parsing, background task lifecycle and atomic result delivery, cron job scheduling and persistence, goal evaluation loops, and the integrity of context compaction (preserving tool results and handling oversized outputs). It also includes smoke tests to ensure agent scripts compile and chapter READMEs follow the expected structure and language navigation.

tests · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 55.

• Code Health 69
• Architecture 83
• Maturity 78
• Readiness 44
• Security 81
• Accessibility 54

• 233 commits — 106 feature/other, 127 fixes

• (repo) — 92 commits
• web/src — 19 commits
• (root) — 17 commits
• web/public — 8 commits
• .github/workflows — 7 commits
• agents/s07_task_system.py — 6 commits
• docs/en — 6 commits
• s08_context_compact/README.en.md — 6 commits
• agents/s02_tool_use.py — 5 commits
• agents/s06_context_compact.py — 5 commits
• agents/s11_autonomous_agents.py — 4 commits
• s08_context_compact/images — 4 commits
• agents/s01_agent_loop.py — 3 commits
• agents/s_full.py — 3 commits
• s03_permission/README.en.md — 3 commits
• s07_skill_loading/code.py — 3 commits
• agents/s03_todo_write.py — 2 commits
• agents/s08_background_tasks.py — 2 commits
• agents/s09_agent_teams.py — 2 commits
• docs/zh — 2 commits

• fix: fix: remove hardcoded assistant acks after system message injection
• fix: Fix a bug where tool_result messages must appear before text in user messages
• fix: Fix empty tool-use response handling
• fix: Fix running background status in s_full
• fix: Fix s08 subagent tool argument mismatch
• fix: Fix s09 subagent tool argument mismatch
• fix: Fix s_full.py consistency: auto_compact keeps newest messages, nag reminder appends after tool_results
• fix: Fix separator inconsistency
• fix: Fix skill frontmatter parsing
• fix: Fix skill frontmatter parsing
• fix: Fix subprocess output decoding in s02
• fix: Fix unhandled OSError in subprocess and unsafe dict access in subagent (#159)
• fix: Fix: Add blockedBy check in claim_task to prevent LLM bypassing dependencies
• fix: Fix: Align ID extraction logic with _new_id using index [1]
• fix: Fix: Handle claim_task error response in agent idle loop
• fix: Fix: Sort task JSON files numerically instead of lexicographically
• fix: Merge main into fix/micro-compact-latest-batch
• fix: Merge pull request #118 from deanbear/fix-auto-compact-400
• fix: Merge pull request #122 from chablino/fix-S07
• fix: Merge pull request #133 from bluzername/fix/task-json-non-ascii
• …and 213 more

• 0 containers · 1 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

shareAI-lab/learn-claude-code was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.