Case Studies

learn-claude-code Hits 74k Stars: Build a Claude Code Clone From Scratch

This nano repo from shareAI-lab skips API tutorials and shows how to wire an LLM into your terminal as an agent. Under 500 lines of Python, with the harness architecture dissected line by line.

Font size

Most Agent tutorials cover the same ground: how to write prompts, how to read the ReAct paper, how elegant LangChain orchestration looks. But nobody talks about the real question: how does a terminal agent like Claude Code actually connect a model to a shell? The model is the driver; the harness is the car. Most material explains how to train the driver. Nobody explains how to build the car.

shareAI-lab/learn-claude-code fills that gap. Currently sitting at 74,754 stars and a regular on GitHub Trending.

What problem does it solve?

Claude Code is a black box. You type claude, and it reads your code, edits your files, runs your tests. What happens in between stays opaque. Anthropic hasn't open-sourced it.

The repo's author draws a clean conceptual line:

  • Agency: intelligence lives in the model itself. The harness can't touch it.
  • Harness: the external engineering that puts the model into a tool-calling loop. This part you can learn, build, and ship.

So this repo covers the harness layer only. No prompt engineering, no fine-tuning, no RLHF. Just 500 lines of Python wiring the Claude API into your terminal.

The README opens with four milestones laying out the history: DQN → OpenAI Five → AlphaStar → Tencent JueWu (Honor of Kings AI). Each generation pushed the model into more complex environments. This repo collapses that environment down to the simplest possible target: your bash.

How to use it

Three steps:

git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
export ANTHROPIC_API_KEY=sk-ant-...
python main.py

Now you can chat with an agent in your terminal. The nano-variants/ directory is a teaching onion, layer after layer: from the barest bash loop (v0) to full tool-use (vN). Every step runs. Every step is readable.

The minimum viable example, a core loop in under 30 lines:

import anthropic, subprocess, json

client = anthropic.Anthropic()
tools = [
    {"name": "bash", "description": "Run a shell command",
     "input_schema": {"type": "object",
                      "properties": {"cmd": {"type": "string"}}}}
]
messages = [{"role": "user",
             "content": "统计当前目录所有 .py 文件总行数"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-5", max_tokens=2048,
        tools=tools, messages=messages)
    if resp.stop_reason != "tool_use":
        print(resp.content[0].text); break
    messages.append({"role": "assistant", "content": resp.content})
    for block in resp.content:
        if block.type == "tool_use":
            out = subprocess.run(block.input["cmd"],
                                 shell=True, capture_output=True,
                                 text=True, timeout=30).stdout
            messages.append({"role": "user", "content": [
                {"type": "tool_result",
                 "tool_use_id": block.id,
                 "content": out}]})

Read this and you've grasped 60% of Claude Code's secrets. It's a while loop.

How it works (architecture)

Four-step loop:

  1. The system prompt defines the tool list.
  2. User messages enter the queue.
  3. Call the Claude API.
  4. Parse tool_use blocks in the response and execute them via local subprocess (bash or python).
  5. Stuff the results back into messages.
  6. Jump to step 3 until the model stops calling tools.

Key design choices:

  • Radically minimal tools: only Read, Write, and Bash. Bash is all you need. Need grep? bash. Need find? bash. Need curl? Still bash. No abstract virtual tools.
  • Timeout cap: any bash command running past 30 seconds gets killed. Prevents the agent from hanging.
  • Real filesystem: file operations hit actual paths. No virtual filesystem gymnastics.
  • JSONL persistence: the messages array appends to a .jsonl file every turn. Resume-from-checkpoint comes for free.

This philosophy tracks with Anthropic's official Claude Code. An Anthropic engineer said something similar on a podcast: "We tried building a safe DSL for agents. Turns out bash was enough."

What's good / what's not

Good:

  • Core code under 500 lines. Line-by-line reading is painless.
  • No dependency on heavy orchestration frameworks like LangChain, AutoGen, or CrewAI. Zero abstraction tax.
  • README in English, Chinese, and Japanese. The shareAI-lab team is based in China.
  • Uses DQN, OpenAI Five, AlphaStar, and Tencent JueWu as cognitive anchors. Agents aren't new; they're the natural extension of the DRL paradigm.
  • The nano-variants directory flattens the evolution path. Every step is a runnable commit.

Not so good:

  • No MCP support (Model Context Protocol is now industry standard).
  • No sub-agent dispatch, no multi-agent orchestration.
  • No permission sandbox. Bash commands run through subprocess.run directly. A malicious prompt could rm -rf ~.
  • Missing production capabilities: no retry, no rate limiting, no token counting, no cost control.
  • Error handling leans on try/except. Crash and you start over.

Stacked against LangChain, AutoGen, CrewAI, this isn't a production component. It's a teaching slice. Against commercial products like v0 or Bolt, it isn't a product. It's a reference implementation. The positioning is clear: help you understand, not help you ship.

I tried it

Cloned it and ran the v0-bash-loop version. Task: have the agent write its own Python script to count lines in the current directory.

Finished in 3 turns:

  • Turn 1: Model decides to call bash, starts with ls to inspect the directory.
  • Turn 2: Model decides to call Write, drafts a script using os.walk and sum(1 for _ in open(f)).
  • Turn 3: Model calls bash to execute the script and outputs the final result.

11 seconds total. Sonnet 4.5, roughly 4k tokens across 3 turns. Verified the generated script with wc -l. Numbers matched.

Slower than the official Claude Code CLI on the same task; the CLI has lighter startup overhead and better-optimized tool implementations. But this version shows every tool call in the open: [tool_use] bash: ls -la → [tool_result] total 48.... That's where the teaching value lives.

Who should use it

Good fit:

  • Engineers who want to understand Claude Code's internals.
  • Tech leads running Agent training sessions for their team.
  • Indie devs building a coding agent from zero.
  • Candidates prepping for System Design interviews with an Agent architecture angle.

Not a fit:

  • Founders who want a framework to ship production services right now.
  • Enterprise scenarios needing MCP, multi-agent coordination, or complex permission management.
  • Frontend folks who'd rather not touch Python's subprocess module.

One-line takeaway

Bash is all you need, but only if you're willing to actually read that while loop.


References:

Source: https://github.com/shareAI-lab/learn-claude-code