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:
- The system prompt defines the tool list.
- User messages enter the queue.
- Call the Claude API.
- Parse
tool_useblocks in the response and execute them via localsubprocess(bash or python). - Stuff the results back into
messages. - 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? Stillbash. 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
messagesarray appends to a.jsonlfile 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-variantsdirectory 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.rundirectly. A malicious prompt couldrm -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
lsto inspect the directory. - Turn 2: Model decides to call Write, drafts a script using
os.walkandsum(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
subprocessmodule.
One-line takeaway
Bash is all you need, but only if you're willing to actually read that while loop.
References:
- shareAI-lab/learn-claude-code GitHub repo
- Current star count: 74,754 (as of writing)