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:

ANTHROPICAPIKEY=yourapikey
ANTHROPICBASEURL=youranthropiccompatiblebaseurl
ANTHROPICMODEL=yourmodel_name

Run the first chapter:

cargo run -p s01agentloop

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 | s01agentloop | Agent Loop | Minimal runnable agent with user input, model response, tool calling, and a basic bash tool. Docs: s01.en.md. | | 02 | s02tooluse | Tool Use | Extract tools into a trait and add readfile, writefile, and editfile. Docs: s02.en.md. | | 03 | s03todowrite | Todo Planning | Add a todo tool so the agent can maintain a plan and execution state. Docs: s3.en.md. | | 04 | s04subagent | Subagent | Start fresh-context subagents for delegated exploration or subtasks. Docs: s4.en.md. | | 05 | s05skillloading | Skill Loading | Load skills from skills/ and inject skill content into context on demand. Docs: s05.en.md. | | 06 | s06contextcompact | Context Compact | Compact long context while preserving key state. Docs: s06.en.md. | | 07 | s07permissionsystem | Permission | Add permission modes and interactive confirmation for tool calls. Docs: s07.en.md. | | 08 | s08hooksystem | Hook System | Add lifecycle hooks around tool execution and agent events. Docs: s08.en.md. | | 09 | s09memorysystem | Memory | Add durable memory for preferences, facts, feedback, and references. Docs: s09.en.md. | | 10 | s10systemprompt | System Prompt | Manage system prompts through structured sections and templates. Docs: s10.en.md. | | 11 | s11errorrecovery | Error Recovery | Recover from tool failures, model errors, transport errors, and truncation. Docs: s11.en.md. | | 12 | s12tasksystem | Task System | Add structured task records with status, owner, and dependencies. Docs: s12.en.md. | | 13 | s13backgroundtasks | Background Tasks | Start, query, and manage long-running background commands. Docs: s13.en.md. | | 14 | s14cronscheduler | Cron Scheduler | Schedule future tasks and reinject them into the loop when due. Docs: s14.en.md. | | 15 | s15agentteams | Agent Teams | Organize multiple agents into teams with roles, inboxes, and messages. Docs: s15.en.md. | | 16 | s16teamprotocols | Team Protocols | Add durable request-response protocols for multi-agent collaboration. Docs: s16.en.md. | | 17 | s17autonomousagents | Autonomous Agents | Implement long-running workers with idle polling and task claiming. Docs: s17.en.md. | | 18 | s18worktreetaskisolation | Worktree Isolation | Use git worktrees to isolate task execution environments. Docs: s18.en.md. | | 19 | s19mcpplugin | MCP Plugin | Connect MCP/plugin tools to the same permission and tool-result loop. Docs: s19.en.md. | | 20 | s20toolrefactor | Tool Refactor | Refactor tool registration, routing, dispatch, and macro support. Docs: s20.en.md. | | Full | sfull | Complete Version | Integrate previous chapters into one complete agent harness. Docs: sfull.en.md. |

.
├── Cargo.toml
├── CONTRIBUTING.md
├── s01agentloop/
├── s02tooluse/
├── s03todowrite/
├── s04_subagent/
├── s05skillloading/
├── s06contextcompact/
├── s07permissionsystem/
├── s08hooksystem/
├── s09memorysystem/
├── s10systemprompt/
├── s11errorrecovery/
├── s12tasksystem/
├── s13backgroundtasks/
├── s14cronscheduler/
├── s15agentteams/
├── s16teamprotocols/
├── s17autonomousagents/
├── s18worktreetask_isolation/
├── s19mcpplugin/
├── s20toolrefactor/
├── s20toolrefactor_macros/
├── sfull/
└── skills/

cargo run -p s03todowrite

cargo run -p sfull

cargo check --workspace

cargo test --workspace

cargo fmt --all