从头实现 mini claude code

Sat, 28 Feb 2026 18:34:25 -0800

从头实现 mini claude code

简介

模型就是智能体。我们的工作就是给它工具, 然后让开。

项目地址：

Bash is all you need - A nano Claude Code–like agent, built from 0 to 1

Learn Claude Code – 从 0 到 1 构建 nano Claude Code-like agent

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


 THE AGENT PATTERN
 =================

 User --> messages[] --> LLM --> response
 |
 stop_reason == "tool_use"?
 / \
 yes no
 | |
 execute tools return text
 append results
 loop back -----------------> messages[]


 这是最小循环。每个 AI 编程 Agent 都需要这个循环。
 生产级 Agent 还会叠加策略、权限与生命周期层。

课程简介

12 个递进式课程, 从简单循环到隔离化的自治执行。每个课程添加一个机制。每个机制有一句格言。

s01 “One loop & Bash is all you need” — 一个工具 + 一个循环 = 一个智能体

s02 “加一个工具, 只加一个 handler” — 循环不用动, 新工具注册进 dispatch map 就行

s03 “没有计划的 agent 走哪算哪” — 先列步骤再动手, 完成率翻倍

s04 “大任务拆小, 每个小任务干净的上下文” — 子智能体用独立 messages[], 不污染主对话

s05 “用到什么知识, 临时加载什么知识” — 通过 tool_result 注入, 不塞 system prompt

s06 “上下文总会满, 要有办法腾地方” — 三层压缩策略, 换来无限会话

s07 “大目标要拆成小任务, 排好序, 记在磁盘上” — 文件持久化的任务图, 为多 agent 协作打基础

s08 “慢操作丢后台, agent 继续想下一步” — 后台线程跑命令, 完成后注入通知

s09 “任务太大一个人干不完, 要能分给队友” — 持久化队友 + 异步邮箱

s10 “队友之间要有统一的沟通规矩” — 一个 request-response 模式驱动所有协商

s11 “队友自己看看板, 有活就认领” — 不需要领导逐个分配, 自组织

s12 “各干各的目录, 互不干扰” — 任务管目标, worktree 管目录, 按 ID 绑定

核心模式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


def agent_loop(messages):
 while True:
 response = client.messages.create(
 model=MODEL, system=SYSTEM,
 messages=messages, tools=TOOLS,
 )
 messages.append({"role": "assistant",
 "content": response.content})

 if response.stop_reason != "tool_use":
 return

 results = []
 for block in response.content:
 if block.type == "tool_use":
 output = TOOL_HANDLERS[block.name](**block.input)
 results.append({
 "type": "tool_result",
 "tool_use_id": block.id,
 "content": output,
 })
 messages.append({"role": "user", "content": results})

每个课程在这个循环之上叠加一个机制 – 循环本身始终不变。

范围说明 (重要)

本仓库是一个 0->1 的学习型项目，用于从零构建 nano Claude Code-like agent。为保证学习路径清晰，仓库有意简化或省略了部分生产机制：

完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。
s12 仅提供教学用途的最小 append-only 生命周期事件流。
基于规则的权限治理与信任流程
会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制
完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)

仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。

快速开始

1
2
3
4
5
6
7
8


git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env # 编辑 .env 填入你的 ANTHROPIC_API_KEY

python agents/s01_agent_loop.py # 从这里开始
python agents/s12_worktree_task_isolation.py # 完整递进终点
python agents/s_full.py # 总纲: 全部机制合一

Web 平台

交互式可视化、分步动画、源码查看器, 以及每个课程的文档。

1

cd web && npm install && npm run dev # http://localhost:3000

学习路径

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


第一阶段: 循环 第二阶段: 规划与知识
================== ==============================
s01 Agent 循环 [1] s03 TodoWrite [5]
 while + stop_reason TodoManager + nag 提醒
 | |
 +-> s02 Tool Use [4] s04 子智能体 [5]
 dispatch map: name->handler 每个子智能体独立 messages[]
 |
 s05 Skills [5]
 SKILL.md 通过 tool_result 注入
 |
 s06 Context Compact [5]
 三层上下文压缩

第三阶段: 持久化 第四阶段: 团队
================== =====================
s07 任务系统 [8] s09 智能体团队 [9]
 文件持久化 CRUD + 依赖图 队友 + JSONL 邮箱
 | |
s08 后台任务 [6] s10 团队协议 [12]
 守护线程 + 通知队列 关机 + 计划审批 FSM
 |
 s11 自治智能体 [14]
 空闲轮询 + 自动认领
 |
 s12 Worktree 隔离 [16]
 任务协调 + 按需隔离执行通道

 [N] = 工具数量

项目结构

1
2
3
4
5
6
7


learn-claude-code/
|
|-- agents/ # Python 参考实现 (s01-s12 + s_full 总纲)
|-- docs/{en,zh,ja}/ # 心智模型优先的文档 (3 种语言)
|-- web/ # 交互式学习平台 (Next.js)
|-- skills/ # s05 的 Skill 文件
+-- .github/workflows/ci.yml # CI: 类型检查 + 构建

文档

心智模型优先: 问题、方案、ASCII 图、最小化代码。

课程	主题	格言
s01	Agent 循环	One loop & Bash is all you need
s02	Tool Use	加一个工具, 只加一个 handler
s03	TodoWrite	没有计划的 agent 走哪算哪
s04	子智能体	大任务拆小, 每个小任务干净的上下文
s05	Skills	用到什么知识, 临时加载什么知识
s06	Context Compact	上下文总会满, 要有办法腾地方
s07	任务系统	大目标要拆成小任务, 排好序, 记在磁盘上
s08	后台任务	慢操作丢后台, agent 继续想下一步
s09	智能体团队	任务太大一个人干不完, 要能分给队友
s10	团队协议	队友之间要有统一的沟通规矩
s11	自治智能体	队友自己看看板, 有活就认领
s12	Worktree + 任务隔离	各干各的目录, 互不干扰

学完之后 —— 从理解到落地

12 个课程走完, 你已经从内到外理解了 agent 的工作原理。两种方式把知识变成产品:

Kode Agent CLI – 开源 Coding Agent CLI

npm i -g @shareai-lab/kode

支持 Skill & LSP, 适配 Windows, 可接 GLM / MiniMax / DeepSeek 等开放模型。装完即用。

GitHub: shareAI-lab/Kode-cli

Kode Agent SDK – 把 Agent 能力嵌入你的应用

官方 Claude Code Agent SDK 底层与完整 CLI 进程通信 – 每个并发用户 = 一个终端进程。Kode SDK 是独立库, 无 per-user 进程开销, 可嵌入后端、浏览器插件、嵌入式设备等任意运行时。

GitHub: shareAI-lab/Kode-agent-sdk

姊妹教程: 从被动临时会话到主动常驻助手

本仓库教的 agent 属于 用完即走 型 – 开终端、给任务、做完关掉, 下次重开是全新会话。Claude Code 就是这种模式。

但 OpenClaw (小龙虾) 证明了另一种可能: 在同样的 agent core 之上, 加两个机制就能让 agent 从"踹一下动一下"变成"自己隔 30 秒醒一次找活干":

心跳 (Heartbeat) – 每 30 秒系统给 agent 发一条消息, 让它检查有没有事可做。没事就继续睡, 有事立刻行动。
定时任务 (Cron) – agent 可以给自己安排未来要做的事, 到点自动执行。

再加上 IM 多通道路由 (WhatsApp/Telegram/Slack/Discord 等 13+ 平台)、不清空的上下文记忆、Soul 人格系统, agent 就从一个临时工具变成了始终在线的个人 AI 助手。

claw0 是我们的姊妹教学仓库, 从零拆解这些机制:

1

claw agent = agent core + heartbeat + cron + IM chat + memory + soul

1
2
3
4


learn-claude-code claw0
(agent 运行时内核: (主动式常驻 AI 助手:
 循环、工具、规划、 心跳、定时任务、IM 通道、
 团队、worktree 隔离) 记忆、Soul 人格)

Mini Claude Code Agent

Claude Code CLI 编程助手的最小实现版本。

概述

Mini Claude Code Agent 是 Claude Code 的简化版本，它允许 AI 模型通过一组强大的工具直接与您的代码库进行交互。它提供了一个命令行界面，使 Claude 能够：

读取和写入文件
执行 shell 命令
编辑文件中的文本
导航项目结构

此工具旨在与 LLM 模型一起使用，以提供交互式编码体验，LLM 可以直接对您的代码库进行更改。

功能特性

编程助手：使用大型语言模型作为核心 AI 引擎
文件操作：支持读取、写入和编辑文件
Shell 执行：可以在项目工作区中执行 shell 命令
MCP 集成：支持 Model Context Protocol，可连接多种 MCP 服务器扩展功能
Skills 系统：支持 Anthropic Skills 规范，可安装和调用专业技能
上下文压缩：智能的自动和手动上下文压缩，处理长对话的 token 限制
实时状态栏：显示 MCP 连接状态和上下文使用率，一目了然
安全限制：防止路径遍历和危险命令执行
实时反馈：在执行过程中提供视觉反馈
模块化架构：组织良好的代码库，便于维护和扩展

技术栈

TypeScript
Node.js
Anthropic AI SDK
MCP (Model Context Protocol) SDK

前提条件

Node.js >= 16.0.0
Anthropic 兼容的 API 密钥
代理 LLM 模型

快速启动

最快的启动方式：

设置环境变量：

1
2
3


export ANTHROPIC_API_KEY="your-api-key-here"
export ANTHROPIC_BASE_URL="your-anthropic-compatible-api-base-url"
export ANTHROPIC_MODEL="model-name"

使用 npx 直接运行（无需安装）：

1

npx -y @scipen/mini-claude-code

就是这么简单！助手会启动，你可以开始与它交互。

安装

1

npm install -g @scipen/mini-claude-code

或者从源码克隆并构建：

1
2
3


git clone https://github.com/scipenai/mini-claude-code.git
cd mini-claude-code
npm install

配置

将您的 Anthropic API 密钥设置为环境变量：

1
2
3


export ANTHROPIC_API_KEY="your-api-key-here"
export ANTHROPIC_BASE_URL="your-anthropic-compatable-api-base-url"
export ANTHROPIC_MODEL="model-name"

安装依赖

1

npm install

构建项目

1

npm run build

运行项目

开发模式运行

1

npm run dev

生产模式运行

1
2


npm run build
npm start

使用方法

启动程序后，您可以在终端中与代码助手进行交互：

输入您的需求或问题
助手将自动分析并执行相应的操作（如文件修改、命令执行等）
查看执行结果和输出

输入 exit 或 quit 退出程序。

可用命令

/help - 显示帮助信息
/clear - 清屏
/history - 显示对话历史
/reset - 重置对话历史
/compact - 手动压缩对话历史为摘要
/stats - 显示上下文使用统计
/save - 保存当前对话到文件
/load - 从文件加载对话历史
/todo - 显示待办事项状态
/skills - 管理和调用技能 (list/read)
exit/quit - 退出程序

上下文压缩

Mini Claude Code 支持智能的上下文压缩功能，可以处理长对话的 token 限制问题：

自动压缩：当 token 使用率达到 92% 时自动触发，透明地压缩对话历史为摘要
手动压缩：使用 /compact 命令手动压缩对话历史
统计查看：使用 /stats 命令查看当前的 token 使用情况

详细说明请参阅上下文压缩文档 (English)。

实时状态栏

在每次命令后显示实时状态信息：

1
2
3


┌──────────────────────────────────────────────────────────────────────────────┐
│ 🔌 MCP: 2 │ 🟢 Context: 45% │ 💬 Msgs: 67 │ 🎯 Skills: 3 │ 🤖 Agents: 2 │
└──────────────────────────────────────────────────────────────────────────────┘

MCP 状态：显示已连接的 MCP 服务器数量
上下文使用率：用颜色编码显示上下文使用百分比
- 🟢 绿色 (0-74%): 正常
- 🟡 黄色 (75-91%): 警告
- 🔴 红色 (92-100%): 临界（即将自动压缩）
消息数量：当前对话的消息总数
Skills 数量：已安装的技能数量
Agents 数量：自定义 Agent 数量（通过 /agents 创建）

详细说明请参阅状态栏文档 (English)。

Skills 系统

Mini Claude Code 支持 Anthropic Skills 规范，允许你安装和使用技能来扩展 AI 的能力。

什么是 Skills？

Skills 是包含专业指令和资源的文档，帮助 AI 更好地完成特定任务。例如：

PDF 处理技能
Excel 数据分析技能
代码审查技能
数据库迁移技能

快速开始

1

mkdir -p .mini-cc/skills/my-skill

创建 SKILL.md 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


cat > .mini-cc/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Description of what this skill does
---

# My Skill

## Instructions

[Your skill instructions here...]
EOF

在 Mini Claude Code 中使用：

1
2


/skills list # 列出所有可用技能
/skills read my-skill # 读取技能内容

详细文档请参阅：

MCP 集成

Mini Claude Code 支持 Model Context Protocol (MCP)，可以连接各种 MCP 服务器来扩展功能。

配置 MCP 服务器

在项目根目录创建 .mcp.json 文件：

1

cp .mcp.example.json .mcp.json

编辑配置文件添加你需要的 MCP 服务器。

支持三种传输方式：

stdio: 本地进程通信（默认）
streamable_http: HTTP 远程服务器（推荐）
sse: 旧版 HTTP/SSE（已弃用）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


{
 "mcpServers": [
 {
 "name": "filesystem",
 "transport": "stdio",
 "command": "npx",
 "args": [
 "-y",
 "@modelcontextprotocol/server-filesystem",
 "/path/to/directory"
 ]
 },
 {
 "name": "remote-service",
 "transport": "streamable_http",
 "url": "https://your-mcp-server.example.com/mcp"
 }
 ]
}

详细的 MCP 配置和使用说明，请参阅：

交互示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


User: 创建一个名为 hello.js 的新文件，打印 "Hello, World!"
Assistant: 我将创建一个名为 hello.js 的新文件，打印 "Hello, World!"。

Tool: write_file
{
 "path": "hello.js",
 "content": "console.log('Hello, World!');\n"
}

Result: wrote 26 bytes to hello.js

我已经创建了 hello.js 文件，其中包含一个简单的程序，在控制台打印 "Hello, World!"。您可以使用 `node hello.js` 运行它。

安全性

该助手包含全面的安全措施：

增强的命令检测：使用基于正则表达式的模式匹配来阻止危险命令
- 文件系统破坏（rm -rf /、mkfs、dd）
- 权限提升（sudo、su）
- 系统控制（shutdown、reboot、poweroff）
- 远程代码执行（curl | bash、wget | sh）
- Fork 炸弹和资源耗尽
- 以及更多（50+种模式）
路径遍历防护：限制文件访问到当前工作目录
超时保护：所有命令执行默认 30 秒超时
安全命令白名单：常见开发命令绕过检查以获得更好的性能
详细的错误消息：命令被阻止时提供清晰的反馈

详细的安全信息，请参阅安全文档

开发

版本管理

本项目使用自动化脚本进行版本管理。

快速参考：

1
2
3
4


# 仅更新版本号
npm run version:patch # 0.5.0 -> 0.5.1
npm run version:minor # 0.5.1 -> 0.6.0
npm run version:major # 0.5.1 -> 1.0.0

所有版本号会自动从 package.json 同步。

添加新工具

要向助手添加新工具：

在 src/tools/ 目录中创建新文件
实现工具功能
将工具定义添加到 src/tools/tools.ts
更新 src/tools/dispatcher.ts 中的分发器以处理新工具

代码组织

代码库遵循模块化架构：

config：配置和环境变量
core：核心助手逻辑和主执行循环
tools：单个工具实现和工具管理
types：TypeScript 类型定义
utils：常见操作的实用函数
scripts：构建和发布自动化脚本

附录

s01_agent_loop.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106


#!/usr/bin/env python3
"""
s01_agent_loop.py - The Agent Loop

The entire secret of an AI coding agent in one pattern:

 while stop_reason == "tool_use":
 response = LLM(messages, tools)
 execute tools
 append results

 +----------+ +-------+ +---------+
 | User | ---> | LLM | ---> | Tool |
 | prompt | | | | execute |
 +----------+ +---+---+ +----+----+
 ^ |
 | tool_result |
 +---------------+
 (loop continues)

This is the core loop: feed tool results back to the model
until the model decides to stop. Production agents layer
policy, hooks, and lifecycle controls on top.
"""

import os
import subprocess

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv(override=True)

if os.getenv("ANTHROPIC_BASE_URL"):
 os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)

client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
MODEL = os.environ["MODEL_ID"]

SYSTEM = f"You are a coding agent at {os.getcwd()}. Use bash to solve tasks. Act, don't explain."

TOOLS = [{
 "name": "bash",
 "description": "Run a shell command.",
 "input_schema": {
 "type": "object",
 "properties": {"command": {"type": "string"}},
 "required": ["command"],
 },
}]


def run_bash(command: str) -> str:
 dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
 if any(d in command for d in dangerous):
 return "Error: Dangerous command blocked"
 try:
 r = subprocess.run(command, shell=True, cwd=os.getcwd(),
 capture_output=True, text=True, timeout=120)
 out = (r.stdout + r.stderr).strip()
 return out[:50000] if out else "(no output)"
 except subprocess.TimeoutExpired:
 return "Error: Timeout (120s)"


# -- The core pattern: a while loop that calls tools until the model stops --
def agent_loop(messages: list):
 while True:
 response = client.messages.create(
 model=MODEL, system=SYSTEM, messages=messages,
 tools=TOOLS, max_tokens=8000,
 )
 # Append assistant turn
 messages.append({"role": "assistant", "content": response.content})
 # If the model didn't call a tool, we're done
 if response.stop_reason != "tool_use":
 return
 # Execute each tool call, collect results
 results = []
 for block in response.content:
 if block.type == "tool_use":
 print(f"\033[33m$ {block.input['command']}\033[0m")
 output = run_bash(block.input["command"])
 print(output[:200])
 results.append({"type": "tool_result", "tool_use_id": block.id,
 "content": output})
 messages.append({"role": "user", "content": results})


if __name__ == "__main__":
 history = []
 while True:
 try:
 query = input("\033[36ms01 >> \033[0m")
 except (EOFError, KeyboardInterrupt):
 break
 if query.strip().lower() in ("q", "exit", ""):
 break
 history.append({"role": "user", "content": query})
 agent_loop(history)
 response_content = history[-1]["content"]
 if isinstance(response_content, list):
 for block in response_content:
 if hasattr(block, "text"):
 print(block.text)
 print()

s02_tool_use.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148


#!/usr/bin/env python3
"""
s02_tool_use.py - Tools

The agent loop from s01 didn't change. We just added tools to the array
and a dispatch map to route calls.

 +----------+ +-------+ +------------------+
 | User | ---> | LLM | ---> | Tool Dispatch |
 | prompt | | | | { |
 +----------+ +---+---+ | bash: run_bash |
 ^ | read: run_read |
 | | write: run_wr |
 +----------+ edit: run_edit |
 tool_result| } |
 +------------------+

Key insight: "The loop didn't change at all. I just added tools."
"""

import os
import subprocess
from pathlib import Path

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv(override=True)

if os.getenv("ANTHROPIC_BASE_URL"):
 os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)

WORKDIR = Path.cwd()
client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
MODEL = os.environ["MODEL_ID"]

SYSTEM = f"You are a coding agent at {WORKDIR}. Use tools to solve tasks. Act, don't explain."


def safe_path(p: str) -> Path:
 path = (WORKDIR / p).resolve()
 if not path.is_relative_to(WORKDIR):
 raise ValueError(f"Path escapes workspace: {p}")
 return path


def run_bash(command: str) -> str:
 dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
 if any(d in command for d in dangerous):
 return "Error: Dangerous command blocked"
 try:
 r = subprocess.run(command, shell=True, cwd=WORKDIR,
 capture_output=True, text=True, timeout=120)
 out = (r.stdout + r.stderr).strip()
 return out[:50000] if out else "(no output)"
 except subprocess.TimeoutExpired:
 return "Error: Timeout (120s)"


def run_read(path: str, limit: int = None) -> str:
 try:
 text = safe_path(path).read_text()
 lines = text.splitlines()
 if limit and limit < len(lines):
 lines = lines[:limit] + [f"... ({len(lines) - limit} more lines)"]
 return "\n".join(lines)[:50000]
 except Exception as e:
 return f"Error: {e}"


def run_write(path: str, content: str) -> str:
 try:
 fp = safe_path(path)
 fp.parent.mkdir(parents=True, exist_ok=True)
 fp.write_text(content)
 return f"Wrote {len(content)} bytes to {path}"
 except Exception as e:
 return f"Error: {e}"


def run_edit(path: str, old_text: str, new_text: str) -> str:
 try:
 fp = safe_path(path)
 content = fp.read_text()
 if old_text not in content:
 return f"Error: Text not found in {path}"
 fp.write_text(content.replace(old_text, new_text, 1))
 return f"Edited {path}"
 except Exception as e:
 return f"Error: {e}"


# -- The dispatch map: {tool_name: handler} --
TOOL_HANDLERS = {
 "bash": lambda **kw: run_bash(kw["command"]),
 "read_file": lambda **kw: run_read(kw["path"], kw.get("limit")),
 "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
 "edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
}

TOOLS = [
 {"name": "bash", "description": "Run a shell command.",
 "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
 {"name": "read_file", "description": "Read file contents.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
 {"name": "write_file", "description": "Write content to file.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
 {"name": "edit_file", "description": "Replace exact text in file.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
]


def agent_loop(messages: list):
 while True:
 response = client.messages.create(
 model=MODEL, system=SYSTEM, messages=messages,
 tools=TOOLS, max_tokens=8000,
 )
 messages.append({"role": "assistant", "content": response.content})
 if response.stop_reason != "tool_use":
 return
 results = []
 for block in response.content:
 if block.type == "tool_use":
 handler = TOOL_HANDLERS.get(block.name)
 output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
 print(f"> {block.name}: {output[:200]}")
 results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
 messages.append({"role": "user", "content": results})


if __name__ == "__main__":
 history = []
 while True:
 try:
 query = input("\033[36ms02 >> \033[0m")
 except (EOFError, KeyboardInterrupt):
 break
 if query.strip().lower() in ("q", "exit", ""):
 break
 history.append({"role": "user", "content": query})
 agent_loop(history)
 response_content = history[-1]["content"]
 if isinstance(response_content, list):
 for block in response_content:
 if hasattr(block, "text"):
 print(block.text)
 print()

s_full.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735


#!/usr/bin/env python3
"""
s_full.py - Full Reference Agent

Capstone implementation combining every mechanism from s01-s11.
Session s12 (task-aware worktree isolation) is taught separately.
NOT a teaching session -- this is the "put it all together" reference.

 +------------------------------------------------------------------+
 | FULL AGENT |
 | |
 | System prompt (s05 skills, task-first + optional todo nag) |
 | |
 | Before each LLM call: |
 | +--------------------+ +------------------+ +--------------+ |
 | | Microcompact (s06) | | Drain bg (s08) | | Check inbox | |
 | | Auto-compact (s06) | | notifications | | (s09) | |
 | +--------------------+ +------------------+ +--------------+ |
 | |
 | Tool dispatch (s02 pattern): |
 | +--------+----------+----------+---------+-----------+ |
 | | bash | read | write | edit | TodoWrite | |
 | | task | load_sk | compress | bg_run | bg_check | |
 | | t_crt | t_get | t_upd | t_list | spawn_tm | |
 | | list_tm| send_msg | rd_inbox | bcast | shutdown | |
 | | plan | idle | claim | | | |
 | +--------+----------+----------+---------+-----------+ |
 | |
 | Subagent (s04): spawn -> work -> return summary |
 | Teammate (s09): spawn -> work -> idle -> auto-claim (s11) |
 | Shutdown (s10): request_id handshake |
 | Plan gate (s10): submit -> approve/reject |
 +------------------------------------------------------------------+

 REPL commands: /compact /tasks /team /inbox
"""

import json
import os
import re
import subprocess
import threading
import time
import uuid
from pathlib import Path
from queue import Queue

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv(override=True)
if os.getenv("ANTHROPIC_BASE_URL"):
 os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)

WORKDIR = Path.cwd()
client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
MODEL = os.environ["MODEL_ID"]

TEAM_DIR = WORKDIR / ".team"
INBOX_DIR = TEAM_DIR / "inbox"
TASKS_DIR = WORKDIR / ".tasks"
SKILLS_DIR = WORKDIR / "skills"
TRANSCRIPT_DIR = WORKDIR / ".transcripts"
TOKEN_THRESHOLD = 100000
POLL_INTERVAL = 5
IDLE_TIMEOUT = 60

VALID_MSG_TYPES = {"message", "broadcast", "shutdown_request",
 "shutdown_response", "plan_approval_response"}


# === SECTION: base_tools ===
def safe_path(p: str) -> Path:
 path = (WORKDIR / p).resolve()
 if not path.is_relative_to(WORKDIR):
 raise ValueError(f"Path escapes workspace: {p}")
 return path

def run_bash(command: str) -> str:
 dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
 if any(d in command for d in dangerous):
 return "Error: Dangerous command blocked"
 try:
 r = subprocess.run(command, shell=True, cwd=WORKDIR,
 capture_output=True, text=True, timeout=120)
 out = (r.stdout + r.stderr).strip()
 return out[:50000] if out else "(no output)"
 except subprocess.TimeoutExpired:
 return "Error: Timeout (120s)"

def run_read(path: str, limit: int = None) -> str:
 try:
 lines = safe_path(path).read_text().splitlines()
 if limit and limit < len(lines):
 lines = lines[:limit] + [f"... ({len(lines) - limit} more)"]
 return "\n".join(lines)[:50000]
 except Exception as e:
 return f"Error: {e}"

def run_write(path: str, content: str) -> str:
 try:
 fp = safe_path(path)
 fp.parent.mkdir(parents=True, exist_ok=True)
 fp.write_text(content)
 return f"Wrote {len(content)} bytes to {path}"
 except Exception as e:
 return f"Error: {e}"

def run_edit(path: str, old_text: str, new_text: str) -> str:
 try:
 fp = safe_path(path)
 c = fp.read_text()
 if old_text not in c:
 return f"Error: Text not found in {path}"
 fp.write_text(c.replace(old_text, new_text, 1))
 return f"Edited {path}"
 except Exception as e:
 return f"Error: {e}"


# === SECTION: todos (s03) ===
class TodoManager:
 def __init__(self):
 self.items = []

 def update(self, items: list) -> str:
 validated, ip = [], 0
 for i, item in enumerate(items):
 content = str(item.get("content", "")).strip()
 status = str(item.get("status", "pending")).lower()
 af = str(item.get("activeForm", "")).strip()
 if not content: raise ValueError(f"Item {i}: content required")
 if status not in ("pending", "in_progress", "completed"):
 raise ValueError(f"Item {i}: invalid status '{status}'")
 if not af: raise ValueError(f"Item {i}: activeForm required")
 if status == "in_progress": ip += 1
 validated.append({"content": content, "status": status, "activeForm": af})
 if len(validated) > 20: raise ValueError("Max 20 todos")
 if ip > 1: raise ValueError("Only one in_progress allowed")
 self.items = validated
 return self.render()

 def render(self) -> str:
 if not self.items: return "No todos."
 lines = []
 for item in self.items:
 m = {"completed": "[x]", "in_progress": "[>]", "pending": "[ ]"}.get(item["status"], "[?]")
 suffix = f" <- {item['activeForm']}" if item["status"] == "in_progress" else ""
 lines.append(f"{m} {item['content']}{suffix}")
 done = sum(1 for t in self.items if t["status"] == "completed")
 lines.append(f"\n({done}/{len(self.items)} completed)")
 return "\n".join(lines)

 def has_open_items(self) -> bool:
 return any(item.get("status") != "completed" for item in self.items)


# === SECTION: subagent (s04) ===
def run_subagent(prompt: str, agent_type: str = "Explore") -> str:
 sub_tools = [
 {"name": "bash", "description": "Run command.",
 "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
 {"name": "read_file", "description": "Read file.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}},
 ]
 if agent_type != "Explore":
 sub_tools += [
 {"name": "write_file", "description": "Write file.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
 {"name": "edit_file", "description": "Edit file.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
 ]
 sub_handlers = {
 "bash": lambda **kw: run_bash(kw["command"]),
 "read_file": lambda **kw: run_read(kw["path"]),
 "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
 "edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
 }
 sub_msgs = [{"role": "user", "content": prompt}]
 resp = None
 for _ in range(30):
 resp = client.messages.create(model=MODEL, messages=sub_msgs, tools=sub_tools, max_tokens=8000)
 sub_msgs.append({"role": "assistant", "content": resp.content})
 if resp.stop_reason != "tool_use":
 break
 results = []
 for b in resp.content:
 if b.type == "tool_use":
 h = sub_handlers.get(b.name, lambda **kw: "Unknown tool")
 results.append({"type": "tool_result", "tool_use_id": b.id, "content": str(h(**b.input))[:50000]})
 sub_msgs.append({"role": "user", "content": results})
 if resp:
 return "".join(b.text for b in resp.content if hasattr(b, "text")) or "(no summary)"
 return "(subagent failed)"


# === SECTION: skills (s05) ===
class SkillLoader:
 def __init__(self, skills_dir: Path):
 self.skills = {}
 if skills_dir.exists():
 for f in sorted(skills_dir.rglob("SKILL.md")):
 text = f.read_text()
 match = re.match(r"^---\n(.*?)\n---\n(.*)", text, re.DOTALL)
 meta, body = {}, text
 if match:
 for line in match.group(1).strip().splitlines():
 if ":" in line:
 k, v = line.split(":", 1)
 meta[k.strip()] = v.strip()
 body = match.group(2).strip()
 name = meta.get("name", f.parent.name)
 self.skills[name] = {"meta": meta, "body": body}

 def descriptions(self) -> str:
 if not self.skills: return "(no skills)"
 return "\n".join(f" - {n}: {s['meta'].get('description', '-')}" for n, s in self.skills.items())

 def load(self, name: str) -> str:
 s = self.skills.get(name)
 if not s: return f"Error: Unknown skill '{name}'. Available: {', '.join(self.skills.keys())}"
 return f"<skill name=\"{name}\">\n{s['body']}\n</skill>"


# === SECTION: compression (s06) ===
def estimate_tokens(messages: list) -> int:
 return len(json.dumps(messages, default=str)) // 4

def microcompact(messages: list):
 indices = []
 for i, msg in enumerate(messages):
 if msg["role"] == "user" and isinstance(msg.get("content"), list):
 for part in msg["content"]:
 if isinstance(part, dict) and part.get("type") == "tool_result":
 indices.append(part)
 if len(indices) <= 3:
 return
 for part in indices[:-3]:
 if isinstance(part.get("content"), str) and len(part["content"]) > 100:
 part["content"] = "[cleared]"

def auto_compact(messages: list) -> list:
 TRANSCRIPT_DIR.mkdir(exist_ok=True)
 path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
 with open(path, "w") as f:
 for msg in messages:
 f.write(json.dumps(msg, default=str) + "\n")
 conv_text = json.dumps(messages, default=str)[:80000]
 resp = client.messages.create(
 model=MODEL,
 messages=[{"role": "user", "content": f"Summarize for continuity:\n{conv_text}"}],
 max_tokens=2000,
 )
 summary = resp.content[0].text
 return [
 {"role": "user", "content": f"[Compressed. Transcript: {path}]\n{summary}"},
 {"role": "assistant", "content": "Understood. Continuing with summary context."},
 ]


# === SECTION: file_tasks (s07) ===
class TaskManager:
 def __init__(self):
 TASKS_DIR.mkdir(exist_ok=True)

 def _next_id(self) -> int:
 ids = [int(f.stem.split("_")[1]) for f in TASKS_DIR.glob("task_*.json")]
 return max(ids, default=0) + 1

 def _load(self, tid: int) -> dict:
 p = TASKS_DIR / f"task_{tid}.json"
 if not p.exists(): raise ValueError(f"Task {tid} not found")
 return json.loads(p.read_text())

 def _save(self, task: dict):
 (TASKS_DIR / f"task_{task['id']}.json").write_text(json.dumps(task, indent=2))

 def create(self, subject: str, description: str = "") -> str:
 task = {"id": self._next_id(), "subject": subject, "description": description,
 "status": "pending", "owner": None, "blockedBy": [], "blocks": []}
 self._save(task)
 return json.dumps(task, indent=2)

 def get(self, tid: int) -> str:
 return json.dumps(self._load(tid), indent=2)

 def update(self, tid: int, status: str = None,
 add_blocked_by: list = None, add_blocks: list = None) -> str:
 task = self._load(tid)
 if status:
 task["status"] = status
 if status == "completed":
 for f in TASKS_DIR.glob("task_*.json"):
 t = json.loads(f.read_text())
 if tid in t.get("blockedBy", []):
 t["blockedBy"].remove(tid)
 self._save(t)
 if status == "deleted":
 (TASKS_DIR / f"task_{tid}.json").unlink(missing_ok=True)
 return f"Task {tid} deleted"
 if add_blocked_by:
 task["blockedBy"] = list(set(task["blockedBy"] + add_blocked_by))
 if add_blocks:
 task["blocks"] = list(set(task["blocks"] + add_blocks))
 self._save(task)
 return json.dumps(task, indent=2)

 def list_all(self) -> str:
 tasks = [json.loads(f.read_text()) for f in sorted(TASKS_DIR.glob("task_*.json"))]
 if not tasks: return "No tasks."
 lines = []
 for t in tasks:
 m = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]"}.get(t["status"], "[?]")
 owner = f" @{t['owner']}" if t.get("owner") else ""
 blocked = f" (blocked by: {t['blockedBy']})" if t.get("blockedBy") else ""
 lines.append(f"{m} #{t['id']}: {t['subject']}{owner}{blocked}")
 return "\n".join(lines)

 def claim(self, tid: int, owner: str) -> str:
 task = self._load(tid)
 task["owner"] = owner
 task["status"] = "in_progress"
 self._save(task)
 return f"Claimed task #{tid} for {owner}"


# === SECTION: background (s08) ===
class BackgroundManager:
 def __init__(self):
 self.tasks = {}
 self.notifications = Queue()

 def run(self, command: str, timeout: int = 120) -> str:
 tid = str(uuid.uuid4())[:8]
 self.tasks[tid] = {"status": "running", "command": command, "result": None}
 threading.Thread(target=self._exec, args=(tid, command, timeout), daemon=True).start()
 return f"Background task {tid} started: {command[:80]}"

 def _exec(self, tid: str, command: str, timeout: int):
 try:
 r = subprocess.run(command, shell=True, cwd=WORKDIR,
 capture_output=True, text=True, timeout=timeout)
 output = (r.stdout + r.stderr).strip()[:50000]
 self.tasks[tid].update({"status": "completed", "result": output or "(no output)"})
 except Exception as e:
 self.tasks[tid].update({"status": "error", "result": str(e)})
 self.notifications.put({"task_id": tid, "status": self.tasks[tid]["status"],
 "result": self.tasks[tid]["result"][:500]})

 def check(self, tid: str = None) -> str:
 if tid:
 t = self.tasks.get(tid)
 return f"[{t['status']}] {t.get('result', '(running)')}" if t else f"Unknown: {tid}"
 return "\n".join(f"{k}: [{v['status']}] {v['command'][:60]}" for k, v in self.tasks.items()) or "No bg tasks."

 def drain(self) -> list:
 notifs = []
 while not self.notifications.empty():
 notifs.append(self.notifications.get_nowait())
 return notifs


# === SECTION: messaging (s09) ===
class MessageBus:
 def __init__(self):
 INBOX_DIR.mkdir(parents=True, exist_ok=True)

 def send(self, sender: str, to: str, content: str,
 msg_type: str = "message", extra: dict = None) -> str:
 msg = {"type": msg_type, "from": sender, "content": content,
 "timestamp": time.time()}
 if extra: msg.update(extra)
 with open(INBOX_DIR / f"{to}.jsonl", "a") as f:
 f.write(json.dumps(msg) + "\n")
 return f"Sent {msg_type} to {to}"

 def read_inbox(self, name: str) -> list:
 path = INBOX_DIR / f"{name}.jsonl"
 if not path.exists(): return []
 msgs = [json.loads(l) for l in path.read_text().strip().splitlines() if l]
 path.write_text("")
 return msgs

 def broadcast(self, sender: str, content: str, names: list) -> str:
 count = 0
 for n in names:
 if n != sender:
 self.send(sender, n, content, "broadcast")
 count += 1
 return f"Broadcast to {count} teammates"


# === SECTION: shutdown + plan tracking (s10) ===
shutdown_requests = {}
plan_requests = {}


# === SECTION: team (s09/s11) ===
class TeammateManager:
 def __init__(self, bus: MessageBus, task_mgr: TaskManager):
 TEAM_DIR.mkdir(exist_ok=True)
 self.bus = bus
 self.task_mgr = task_mgr
 self.config_path = TEAM_DIR / "config.json"
 self.config = self._load()
 self.threads = {}

 def _load(self) -> dict:
 if self.config_path.exists():
 return json.loads(self.config_path.read_text())
 return {"team_name": "default", "members": []}

 def _save(self):
 self.config_path.write_text(json.dumps(self.config, indent=2))

 def _find(self, name: str) -> dict:
 for m in self.config["members"]:
 if m["name"] == name: return m
 return None

 def spawn(self, name: str, role: str, prompt: str) -> str:
 member = self._find(name)
 if member:
 if member["status"] not in ("idle", "shutdown"):
 return f"Error: '{name}' is currently {member['status']}"
 member["status"] = "working"
 member["role"] = role
 else:
 member = {"name": name, "role": role, "status": "working"}
 self.config["members"].append(member)
 self._save()
 threading.Thread(target=self._loop, args=(name, role, prompt), daemon=True).start()
 return f"Spawned '{name}' (role: {role})"

 def _set_status(self, name: str, status: str):
 member = self._find(name)
 if member:
 member["status"] = status
 self._save()

 def _loop(self, name: str, role: str, prompt: str):
 team_name = self.config["team_name"]
 sys_prompt = (f"You are '{name}', role: {role}, team: {team_name}, at {WORKDIR}. "
 f"Use idle when done with current work. You may auto-claim tasks.")
 messages = [{"role": "user", "content": prompt}]
 tools = [
 {"name": "bash", "description": "Run command.", "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
 {"name": "read_file", "description": "Read file.", "input_schema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}},
 {"name": "write_file", "description": "Write file.", "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
 {"name": "edit_file", "description": "Edit file.", "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
 {"name": "send_message", "description": "Send message.", "input_schema": {"type": "object", "properties": {"to": {"type": "string"}, "content": {"type": "string"}}, "required": ["to", "content"]}},
 {"name": "idle", "description": "Signal no more work.", "input_schema": {"type": "object", "properties": {}}},
 {"name": "claim_task", "description": "Claim task by ID.", "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}}, "required": ["task_id"]}},
 ]
 while True:
 # -- WORK PHASE --
 for _ in range(50):
 inbox = self.bus.read_inbox(name)
 for msg in inbox:
 if msg.get("type") == "shutdown_request":
 self._set_status(name, "shutdown")
 return
 messages.append({"role": "user", "content": json.dumps(msg)})
 try:
 response = client.messages.create(
 model=MODEL, system=sys_prompt, messages=messages,
 tools=tools, max_tokens=8000)
 except Exception:
 self._set_status(name, "shutdown")
 return
 messages.append({"role": "assistant", "content": response.content})
 if response.stop_reason != "tool_use":
 break
 results = []
 idle_requested = False
 for block in response.content:
 if block.type == "tool_use":
 if block.name == "idle":
 idle_requested = True
 output = "Entering idle phase."
 elif block.name == "claim_task":
 output = self.task_mgr.claim(block.input["task_id"], name)
 elif block.name == "send_message":
 output = self.bus.send(name, block.input["to"], block.input["content"])
 else:
 dispatch = {"bash": lambda **kw: run_bash(kw["command"]),
 "read_file": lambda **kw: run_read(kw["path"]),
 "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
 "edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"])}
 output = dispatch.get(block.name, lambda **kw: "Unknown")(**block.input)
 print(f" [{name}] {block.name}: {str(output)[:120]}")
 results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
 messages.append({"role": "user", "content": results})
 if idle_requested:
 break
 # -- IDLE PHASE: poll for messages and unclaimed tasks --
 self._set_status(name, "idle")
 resume = False
 for _ in range(IDLE_TIMEOUT // max(POLL_INTERVAL, 1)):
 time.sleep(POLL_INTERVAL)
 inbox = self.bus.read_inbox(name)
 if inbox:
 for msg in inbox:
 if msg.get("type") == "shutdown_request":
 self._set_status(name, "shutdown")
 return
 messages.append({"role": "user", "content": json.dumps(msg)})
 resume = True
 break
 unclaimed = []
 for f in sorted(TASKS_DIR.glob("task_*.json")):
 t = json.loads(f.read_text())
 if t.get("status") == "pending" and not t.get("owner") and not t.get("blockedBy"):
 unclaimed.append(t)
 if unclaimed:
 task = unclaimed[0]
 self.task_mgr.claim(task["id"], name)
 # Identity re-injection for compressed contexts
 if len(messages) <= 3:
 messages.insert(0, {"role": "user", "content":
 f"<identity>You are '{name}', role: {role}, team: {team_name}.</identity>"})
 messages.insert(1, {"role": "assistant", "content": f"I am {name}. Continuing."})
 messages.append({"role": "user", "content":
 f"<auto-claimed>Task #{task['id']}: {task['subject']}\n{task.get('description', '')}</auto-claimed>"})
 messages.append({"role": "assistant", "content": f"Claimed task #{task['id']}. Working on it."})
 resume = True
 break
 if not resume:
 self._set_status(name, "shutdown")
 return
 self._set_status(name, "working")

 def list_all(self) -> str:
 if not self.config["members"]: return "No teammates."
 lines = [f"Team: {self.config['team_name']}"]
 for m in self.config["members"]:
 lines.append(f" {m['name']} ({m['role']}): {m['status']}")
 return "\n".join(lines)

 def member_names(self) -> list:
 return [m["name"] for m in self.config["members"]]


# === SECTION: global_instances ===
TODO = TodoManager()
SKILLS = SkillLoader(SKILLS_DIR)
TASK_MGR = TaskManager()
BG = BackgroundManager()
BUS = MessageBus()
TEAM = TeammateManager(BUS, TASK_MGR)

# === SECTION: system_prompt ===
SYSTEM = f"""You are a coding agent at {WORKDIR}. Use tools to solve tasks.
Prefer task_create/task_update/task_list for multi-step work. Use TodoWrite for short checklists.
Use task for subagent delegation. Use load_skill for specialized knowledge.
Skills: {SKILLS.descriptions()}"""


# === SECTION: shutdown_protocol (s10) ===
def handle_shutdown_request(teammate: str) -> str:
 req_id = str(uuid.uuid4())[:8]
 shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
 BUS.send("lead", teammate, "Please shut down.", "shutdown_request", {"request_id": req_id})
 return f"Shutdown request {req_id} sent to '{teammate}'"

# === SECTION: plan_approval (s10) ===
def handle_plan_review(request_id: str, approve: bool, feedback: str = "") -> str:
 req = plan_requests.get(request_id)
 if not req: return f"Error: Unknown plan request_id '{request_id}'"
 req["status"] = "approved" if approve else "rejected"
 BUS.send("lead", req["from"], feedback, "plan_approval_response",
 {"request_id": request_id, "approve": approve, "feedback": feedback})
 return f"Plan {req['status']} for '{req['from']}'"


# === SECTION: tool_dispatch (s02) ===
TOOL_HANDLERS = {
 "bash": lambda **kw: run_bash(kw["command"]),
 "read_file": lambda **kw: run_read(kw["path"], kw.get("limit")),
 "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
 "edit_file": lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
 "TodoWrite": lambda **kw: TODO.update(kw["items"]),
 "task": lambda **kw: run_subagent(kw["prompt"], kw.get("agent_type", "Explore")),
 "load_skill": lambda **kw: SKILLS.load(kw["name"]),
 "compress": lambda **kw: "Compressing...",
 "background_run": lambda **kw: BG.run(kw["command"], kw.get("timeout", 120)),
 "check_background": lambda **kw: BG.check(kw.get("task_id")),
 "task_create": lambda **kw: TASK_MGR.create(kw["subject"], kw.get("description", "")),
 "task_get": lambda **kw: TASK_MGR.get(kw["task_id"]),
 "task_update": lambda **kw: TASK_MGR.update(kw["task_id"], kw.get("status"), kw.get("add_blocked_by"), kw.get("add_blocks")),
 "task_list": lambda **kw: TASK_MGR.list_all(),
 "spawn_teammate": lambda **kw: TEAM.spawn(kw["name"], kw["role"], kw["prompt"]),
 "list_teammates": lambda **kw: TEAM.list_all(),
 "send_message": lambda **kw: BUS.send("lead", kw["to"], kw["content"], kw.get("msg_type", "message")),
 "read_inbox": lambda **kw: json.dumps(BUS.read_inbox("lead"), indent=2),
 "broadcast": lambda **kw: BUS.broadcast("lead", kw["content"], TEAM.member_names()),
 "shutdown_request": lambda **kw: handle_shutdown_request(kw["teammate"]),
 "plan_approval": lambda **kw: handle_plan_review(kw["request_id"], kw["approve"], kw.get("feedback", "")),
 "idle": lambda **kw: "Lead does not idle.",
 "claim_task": lambda **kw: TASK_MGR.claim(kw["task_id"], "lead"),
}

TOOLS = [
 {"name": "bash", "description": "Run a shell command.",
 "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},
 {"name": "read_file", "description": "Read file contents.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}}, "required": ["path"]}},
 {"name": "write_file", "description": "Write content to file.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"]}},
 {"name": "edit_file", "description": "Replace exact text in file.",
 "input_schema": {"type": "object", "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}}, "required": ["path", "old_text", "new_text"]}},
 {"name": "TodoWrite", "description": "Update task tracking list.",
 "input_schema": {"type": "object", "properties": {"items": {"type": "array", "items": {"type": "object", "properties": {"content": {"type": "string"}, "status": {"type": "string", "enum": ["pending", "in_progress", "completed"]}, "activeForm": {"type": "string"}}, "required": ["content", "status", "activeForm"]}}}, "required": ["items"]}},
 {"name": "task", "description": "Spawn a subagent for isolated exploration or work.",
 "input_schema": {"type": "object", "properties": {"prompt": {"type": "string"}, "agent_type": {"type": "string", "enum": ["Explore", "general-purpose"]}}, "required": ["prompt"]}},
 {"name": "load_skill", "description": "Load specialized knowledge by name.",
 "input_schema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}},
 {"name": "compress", "description": "Manually compress conversation context.",
 "input_schema": {"type": "object", "properties": {}}},
 {"name": "background_run", "description": "Run command in background thread.",
 "input_schema": {"type": "object", "properties": {"command": {"type": "string"}, "timeout": {"type": "integer"}}, "required": ["command"]}},
 {"name": "check_background", "description": "Check background task status.",
 "input_schema": {"type": "object", "properties": {"task_id": {"type": "string"}}}},
 {"name": "task_create", "description": "Create a persistent file task.",
 "input_schema": {"type": "object", "properties": {"subject": {"type": "string"}, "description": {"type": "string"}}, "required": ["subject"]}},
 {"name": "task_get", "description": "Get task details by ID.",
 "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}}, "required": ["task_id"]}},
 {"name": "task_update", "description": "Update task status or dependencies.",
 "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}, "status": {"type": "string", "enum": ["pending", "in_progress", "completed", "deleted"]}, "add_blocked_by": {"type": "array", "items": {"type": "integer"}}, "add_blocks": {"type": "array", "items": {"type": "integer"}}}, "required": ["task_id"]}},
 {"name": "task_list", "description": "List all tasks.",
 "input_schema": {"type": "object", "properties": {}}},
 {"name": "spawn_teammate", "description": "Spawn a persistent autonomous teammate.",
 "input_schema": {"type": "object", "properties": {"name": {"type": "string"}, "role": {"type": "string"}, "prompt": {"type": "string"}}, "required": ["name", "role", "prompt"]}},
 {"name": "list_teammates", "description": "List all teammates.",
 "input_schema": {"type": "object", "properties": {}}},
 {"name": "send_message", "description": "Send a message to a teammate.",
 "input_schema": {"type": "object", "properties": {"to": {"type": "string"}, "content": {"type": "string"}, "msg_type": {"type": "string", "enum": list(VALID_MSG_TYPES)}}, "required": ["to", "content"]}},
 {"name": "read_inbox", "description": "Read and drain the lead's inbox.",
 "input_schema": {"type": "object", "properties": {}}},
 {"name": "broadcast", "description": "Send message to all teammates.",
 "input_schema": {"type": "object", "properties": {"content": {"type": "string"}}, "required": ["content"]}},
 {"name": "shutdown_request", "description": "Request a teammate to shut down.",
 "input_schema": {"type": "object", "properties": {"teammate": {"type": "string"}}, "required": ["teammate"]}},
 {"name": "plan_approval", "description": "Approve or reject a teammate's plan.",
 "input_schema": {"type": "object", "properties": {"request_id": {"type": "string"}, "approve": {"type": "boolean"}, "feedback": {"type": "string"}}, "required": ["request_id", "approve"]}},
 {"name": "idle", "description": "Enter idle state.",
 "input_schema": {"type": "object", "properties": {}}},
 {"name": "claim_task", "description": "Claim a task from the board.",
 "input_schema": {"type": "object", "properties": {"task_id": {"type": "integer"}}, "required": ["task_id"]}},
]


# === SECTION: agent_loop ===
def agent_loop(messages: list):
 rounds_without_todo = 0
 while True:
 # s06: compression pipeline
 microcompact(messages)
 if estimate_tokens(messages) > TOKEN_THRESHOLD:
 print("[auto-compact triggered]")
 messages[:] = auto_compact(messages)
 # s08: drain background notifications
 notifs = BG.drain()
 if notifs:
 txt = "\n".join(f"[bg:{n['task_id']}] {n['status']}: {n['result']}" for n in notifs)
 messages.append({"role": "user", "content": f"<background-results>\n{txt}\n</background-results>"})
 messages.append({"role": "assistant", "content": "Noted background results."})
 # s10: check lead inbox
 inbox = BUS.read_inbox("lead")
 if inbox:
 messages.append({"role": "user", "content": f"<inbox>{json.dumps(inbox, indent=2)}</inbox>"})
 messages.append({"role": "assistant", "content": "Noted inbox messages."})
 # LLM call
 response = client.messages.create(
 model=MODEL, system=SYSTEM, messages=messages,
 tools=TOOLS, max_tokens=8000,
 )
 messages.append({"role": "assistant", "content": response.content})
 if response.stop_reason != "tool_use":
 return
 # Tool execution
 results = []
 used_todo = False
 manual_compress = False
 for block in response.content:
 if block.type == "tool_use":
 if block.name == "compress":
 manual_compress = True
 handler = TOOL_HANDLERS.get(block.name)
 try:
 output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
 except Exception as e:
 output = f"Error: {e}"
 print(f"> {block.name}: {str(output)[:200]}")
 results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
 if block.name == "TodoWrite":
 used_todo = True
 # s03: nag reminder (only when todo workflow is active)
 rounds_without_todo = 0 if used_todo else rounds_without_todo + 1
 if TODO.has_open_items() and rounds_without_todo >= 3:
 results.insert(0, {"type": "text", "text": "<reminder>Update your todos.</reminder>"})
 messages.append({"role": "user", "content": results})
 # s06: manual compress
 if manual_compress:
 print("[manual compact]")
 messages[:] = auto_compact(messages)


# === SECTION: repl ===
if __name__ == "__main__":
 history = []
 while True:
 try:
 query = input("\033[36ms_full >> \033[0m")
 except (EOFError, KeyboardInterrupt):
 break
 if query.strip().lower() in ("q", "exit", ""):
 break
 if query.strip() == "/compact":
 if history:
 print("[manual compact via /compact]")
 history[:] = auto_compact(history)
 continue
 if query.strip() == "/tasks":
 print(TASK_MGR.list_all())
 continue
 if query.strip() == "/team":
 print(TEAM.list_all())
 continue
 if query.strip() == "/inbox":
 print(json.dumps(BUS.read_inbox("lead"), indent=2))
 continue
 history.append({"role": "user", "content": query})
 agent_loop(history)
 print()

Agent on 酒中仙

从头实现 mini claude code

从头实现 mini claude code

简介

Learn Claude Code – 从 0 到 1 构建 nano Claude Code-like agent

课程简介

核心模式

范围说明 (重要)

快速开始

Web 平台

学习路径

项目结构

文档

学完之后 —— 从理解到落地

Kode Agent CLI – 开源 Coding Agent CLI

Kode Agent SDK – 把 Agent 能力嵌入你的应用

姊妹教程: 从被动临时会话到主动常驻助手

Mini Claude Code Agent

概述

功能特性

技术栈

前提条件

快速启动

安装

配置

安装依赖

构建项目

运行项目

开发模式运行

生产模式运行

使用方法

可用命令

上下文压缩

实时状态栏

Skills 系统

什么是 Skills？

快速开始

MCP 集成

配置 MCP 服务器

交互示例

安全性

开发

版本管理

添加新工具

代码组织

附录

s01_agent_loop.py

s02_tool_use.py

s_full.py