local-test-mcp

learn-claude-code-rs

English | 中文

A progressive AI Agent Harness tutorial written in Rust.

This repository is a Rust-oriented learning path for building an agent harness. It starts with the smallest agent loop and gradually adds tools, planning, subagents, skills, context compaction, permissions, hooks, memory, multi-agent collaboration, worktree isolation, MCP/plugins, and tool routing.

This project was inspired by shareAI-lab/learn-claude-code. Its chapter design, content organization, and some code ideas reference that project to a certain extent, then reimplement and adapt them for the Rust ecosystem. It is not a line-by-line copy or a simple port; it reorganizes the agent harness topic itself into a runnable Rust tutorial.

Each chapter is an independent runnable Rust crate. You can read them in order or jump directly into a topic to see how a harness capability is expressed through data structures, runtime loops, tool interfaces, and durable state.

Why This Repo

Most LLM examples stop at tool calling. This repo focuses on the runtime around the model:

• tool dispatch
• permissions
• skills
• memory
• context compaction
• subagents
• background work
• team protocols
• worktree isolation
• MCP plugins
• typed tool routing

Architecture

Audience

• People who want to understand the internals of coding agents instead of only using existing products.
• People who want to write AI agents, CLI tools, or automation tools in Rust.
• Readers who already know LLM APIs and want to learn tool use, subagents, permissions, hooks, memory, and related engineering structures.
• People interested in the infrastructure behind Claude Code, Codex, Devin, Cursor Agent, and similar coding agents.

Quick Start

Prepare Rust:

rustup update
cargo --version

Configure the model API. The examples use an Anthropic-compatible SDK interface and read configuration from environment variables:

cp .env.example .env

Edit .env:

ANTHROPIC_API_KEY=your_api_key
ANTHROPIC_BASE_URL=your_anthropic_compatible_base_url

Run the first chapter:

cargo run -p s01_agent_loop

Run the integrated version:

cargo run -p sfull

Check the whole workspace:

cargo check --workspace

Learning Path

Each chapter is an independent crate that can be run, read, and modified on its own. Reading in order is recommended because later chapters build on earlier structures.

Chapter	Directory	Topic	Description
01	s01_agent_loop	Agent Loop	Minimal runnable agent with user input, model response, tool calling, and a basic bash tool. Docs: s01.en.md.
02	s02_tool_use	Tool Use	Extract tools into a trait and add read_file, write_file, and edit_file. Docs: s02.en.md.
03	s03_todo_write	Todo Planning	Add a todo tool so the agent can maintain a plan and execution state. Docs: s3.en.md.
04	s04_subagent	Subagent	Start fresh-context subagents for delegated exploration or subtasks. Docs: s4.en.md.
05	s05_skill_loading	Skill Loading	Load skills from skills/ and inject skill content into context on demand. Docs: s05.en.md.
06	s06_context_compact	Context Compact	Compact long context while preserving key state. Docs: s06.en.md.
07	s07_permission_system	Permission	Add permission modes and interactive confirmation for tool calls. Docs: s07.en.md.
08	s08_hook_system	Hook System	Add lifecycle hooks around tool execution and agent events. Docs: s08.en.md.
09	s09_memory_system	Memory	Add durable memory for preferences, facts, feedback, and references. Docs: s09.en.md.
10	s10_system_prompt	System Prompt	Manage system prompts through structured sections and templates. Docs: s10.en.md.
11	s11_error_recovery	Error Recovery	Recover from tool failures, model errors, transport errors, and truncation. Docs: s11.en.md.