learn-claude-code: Build AI Coding Agents from Scratch with Python

Introduction

The learn-claude-code repository by shareAI-lab provides a comprehensive, progressive tutorial for understanding and building AI coding agents. This project aims to demystify how powerful agents like Claude Code, Kode, and Cursor Agent function, guiding you through the process of creating one from the ground up. Starting with a remarkably concise 16-line Bash agent, the tutorial evolves through five versions, each introducing a fundamental concept to build a sophisticated AI agent. The core philosophy, "Model as Agent," is central to this learning journey, demonstrating that the model's capabilities, combined with simple tools, are the secret to effective agent design.

Installation

Getting started with learn-claude-code is straightforward. Follow these steps to set up the environment and run the agent versions:

# Install dependencies
pip install -r requirements.txt

# Configure your API
cp .env.example .env
# Edit .env with your API key (supports Anthropic, OpenAI, Gemini, etc.)

# Run any version
python v0_bash_agent.py  # Minimal
python v1_basic_agent.py # Core agent loop
python v2_todo_agent.py  # + Todo planning
python v3_subagent.py    # + Subagents
python v4_skills_agent.py # + Skills

Examples

The repository presents a unique learning path through five distinct agent versions, each building upon the last:

v0: Bash is All You Need (~50 lines, ~16 lines for mini version): Introduces the simplest agent with just one Bash tool, demonstrating that the core agent logic can be incredibly compact. It uses recursive self-calls for subagents.
v1: Model as Agent (~200 lines): Expands to four core tools (bash, read, write, edit), showcasing the complete agent loop within a single function.
v2: Structured Planning (~300 lines): Integrates a Todo tool to enable explicit planning and manage complex tasks with constraints.
v3: Subagent Mechanism (~450 lines): Introduces a Task tool to spawn isolated child agents, maintaining clean context management.
v4: Skills Mechanism (~550 lines): Adds a Skill tool and SKILL.md files, providing on-demand domain expertise and treating knowledge as a first-class citizen.

The core pattern for every coding agent is elegantly simple:

while True:
    response = model(messages, tools)
    if response.stop_reason != "tool_use":
        return response.text
    results = execute(response.tool_calls)
    messages.append(results)

Additionally, the repository includes an Agent Builder Skill to help scaffold new agent projects:

# Scaffold a new agent project
python skills/agent-builder/scripts/init_agent.py my-agent

# Or with specific complexity level
python skills/agent-builder/scripts/init_agent.py my-agent --level 0  # Minimal
python skills/agent-builder/scripts/init_agent.py my-agent --level 1  # 4 tools (default)

Why Use learn-claude-code?

This repository is an invaluable resource for anyone looking to truly understand the mechanics behind modern AI coding agents. By building agents from scratch, you gain deep insights into:

Fundamental Agent Concepts: Learn the core principles of tool use, planning, subagents, and skills that power sophisticated AI systems.
Practical Implementation: Get hands-on experience with Python code that demonstrates these concepts in a clear, incremental manner.
Demystifying AI: Break down the complexity of AI agents into manageable, understandable components, proving that "the model is 80%, code is 20%."
Foundation for Custom Agents: Use this project as a template to fork and customize for your own agent development needs.

It's an educational journey that reshapes your understanding of what makes a true AI agent.