mini-claude-code

English | 简体中文

Sister Projects: - mini-spring (simplified Spring framework) - mini-spring-cloud (simplified Spring Cloud framework) - mini-netty (simplified Netty framework)

About

mini-claude-code is a simplified Java implementation of the Claude Code programming agent that helps you quickly understand the core principles behind coding agents. The project extracts key mechanisms from the Agent Harness with extremely simplified code while preserving core functionality, including Agent Loop, tool dispatch, permission control, hooks, todo planning, subagents, skill loading, context compression, memory systems, task orchestration, background tasks, cron scheduling, multi-agent collaboration, team protocols, autonomous task claiming, and MCP plugins.

Each chapter breaks down one core mechanism of a coding agent, with each chapter on its own branch containing only the minimum code needed to understand that mechanism.

If this project helps you, please give it a STAR, thank you!

Features

• s01 Agent Loop — ReAct: Think-Act-Observe, LLM ⇄ Tool loop
• s02 Tool Dispatch — Tool Use: register-and-use, no loop changes needed
• s03 Permission — Guardrails: three-tier check, review before execution
• s04 Hooks — Lifecycle: four event points, cross-cutting logic separated from the loop
• s05 Todo — Planning: plan first then execute, trackable state
• s06 Subagent — Delegation: delegate to sub-agents with clean context isolation
• s07 Skill Loading — Lazy Skill Loading: index in prompt, body loaded on demand
• s08 Context Compact — Context Compression: four-layer compaction pipeline when full
• s09 Memory — Long-term Memory: what to remember, what to forget, when to consolidate
• s10 Task System — Task Orchestration: task graph + state machine + dependency checks
• s11 Background Tasks — Async: slow ops go background, Agent keeps thinking
• s12 Cron Scheduler — Scheduled Trigger: cron expressions, unattended execution
• s13 Agent Teams — Multi-Agent: lead assigns work, teammates execute in parallel
• s14 Team Protocols — Structured Communication: request_id + state machine between teammates
• s15 Autonomous Agents — Self-Organization: teammates scan board, claim unassigned work
• s16 MCP Plugin — MCP: dynamic tool pools, plug in when capabilities fall short

Usage

1. Prerequisites

Requires Java 17 and Maven.

Before running demos with a real model, set these environment variables in your shell:

export ANTHROPIC_BASE_URL='Your Anthropic-compatible API Base URL, e.g. https://api.deepseek.com/anthropic'
export MODEL_ID='Your model ID'
export ANTHROPIC_API_KEY='Your API Key'

2. Switch to a chapter branch

Each chapter has its own teaching branch. For example, to study s01:

git switch s01-agent-loop

3. Run the demo

Run a specific demo with Maven:

mvn -q compile exec:java -Dexec.mainClass=org.miniclaudecode.demo.S01AgentLoopDemo

Or use the provided script:

./run.sh s01

4. Read the source notes

Read changelog_en.md

Questions

Ask Questions Here

Contributing

Pull Requests are welcome.

Reference

• learn-claude-code (highly recommended)