# mini-claude-code

**Repository Path**: wangxiaopeng2/mini-claude-code

## Basic Information

- **Project Name**: mini-claude-code
- **Description**: Go实现mini版Claude code
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
AIGC:
  ContentProducer: '001191110102MAD55U9H0F10002'
  ContentPropagator: '001191110102MAD55U9H0F10002'
  Label: '1'
  ProduceID: 'd22aae9e-e26d-4bfb-af9f-cdf76d4c95d2'
  PropagateID: 'd22aae9e-e26d-4bfb-af9f-cdf76d4c95d2'
  ReservedCode1: '3881b6fc-335e-4505-ade8-b291ae1b6bb0'
  ReservedCode2: '3881b6fc-335e-4505-ade8-b291ae1b6bb0'
---

# Mini-Claude

基于 Go 的本地 AI Agent 运行时，KamaClaude (Python) 的 Go 语言重写。

双进程架构：**mini-core**（守护进程）+ **mini-claude**（CLI）/ **mini-tui**（TUI），通过 TCP NDJSON + JSON-RPC 2.0 通信。

## 快速开始

### 1. 编译

```bash
go build -o mini-core.exe ./cmd/mini-core/
go build -o mini-claude.exe ./cmd/mini-claude/
go build -o mini-tui.exe ./cmd/mini-tui/
```

### 2. 配置

复制环境变量模板并填入 API Key：

```bash
cp .env.example .env
# 编辑 .env，设置 LLM_API_KEY
```

或直接设置环境变量：

```bash
# Windows PowerShell
$env:LLM_API_KEY = "sk-ant-..."
$env:LLM_CHANNEL = "anthropic"   # 或 "openai"

# Linux/macOS
export LLM_API_KEY="sk-ant-..."
export LLM_CHANNEL="anthropic"
```

可选的配置文件方式：在 `~/.mini-claude/config.toml` 中写入 TOML 配置。

### 3. 启动守护进程

```bash
./mini-core
```

默认监听 `127.0.0.1:7437`。

### 4. 使用 CLI

```bash
# 连通性测试
./mini-claude ping
./mini-claude ping -m "hello"

# 执行一次性任务
./mini-claude run --goal "创建 hello.go，写一个 Hello World 程序"

# 多轮对话
./mini-claude chat

# 检查守护进程状态
./mini-claude core status

# 查看追踪日志
./mini-claude trace

# 版本号
./mini-claude version
```

### 5. 使用 TUI

```bash
./mini-tui
```

TUI 使用 Bubble Tea 终端 UI 框架，支持：
- 多行输入（Ctrl+S 发送）
- LLM 流式 token 实时渲染
- 工具调用折叠块
- 权限审批交互（方向键选择，Enter 确认）
- Ctrl+C 退出

## 架构

```
用户目标 → CLI/TUI → TCP JSON-RPC 2.0 NDJSON → mini-core daemon
                                                    ├── EventBus (发布-订阅)
                                                    ├── PermissionManager (6层评估 + 人工审批)
                                                    ├── SessionManager (会话 + 记忆)
                                                    ├── AgentRunner → AgentLoop (Plan→Act→Observe)
                                                    │    ├── LLM Provider (Anthropic/OpenAI)
                                                    │    ├── ToolRegistry (7个内置工具 + MCP扩展)
                                                    │    ├── Compactor (上下文自动压缩)
                                                    │    └── Invoker (权限检查 + 执行 + 重试)
                                                    └── SocketServer (TCP :7437)
```

## 项目结构

```
mini-claude/
├── cmd/
│   ├── mini-core/main.go       # 守护进程入口
│   ├── mini-claude/main.go     # CLI 入口
│   └── mini-tui/main.go        # TUI 入口
├── internal/
│   ├── agent/loader.go         # Agent Profile TOML 加载
│   ├── bus/                    # JSON-RPC 2.0 协议层
│   ├── compact/                # 上下文压缩（LLM 6段摘要）
│   ├── config/                 # 4级配置加载
│   ├── context/                # 执行上下文（消息+状态）
│   ├── eventbus/               # 进程内事件总线
│   ├── llm/                    # LLM Provider（Anthropic/OpenAI）
│   ├── loop/                   # Agent Loop（Plan→Act→Observe）
│   ├── mcp/                    # MCP stdio 客户端
│   ├── memory/                 # 上下文文件加载
│   ├── permission/             # 权限系统（6层评估+审批）
│   ├── runner/                 # Agent Runner（组装依赖）
│   ├── runs/                   # Run ID 和路径管理
│   ├── session/                # 会话管理
│   ├── skill/                  # Skill 加载（Markdown+frontmatter）
│   ├── task/                   # 任务系统（JSON存储CRUD）
│   ├── tools/                  # 工具系统
│   │   ├── invocation.go       # 调用执行器（校验→权限→执行→重试）
│   │   └── builtin/            # 内置工具（bash/read/write/list/task*）
│   ├── trace/                  # 追踪系统
│   └── transport/              # IPC 传输层（TCP NDJSON）
├── tui/                        # TUI 界面
│   ├── app.go                  # Bubble Tea 主 Model
│   ├── styles.go               # Lip Gloss 样式
│   └── components/             # UI 组件
│       ├── stream.go           # LLM 流式渲染
│       ├── toolblock.go        # 工具调用折叠块
│       ├── permission.go       # 权限审批
│       └── input.go            # 多行输入
├── go.mod / go.sum
├── .env.example
└── 技术方案.md
```

## IPC 命令

命令通过 TCP NDJSON + JSON-RPC 2.0 传输：

| 方法 | 用途 |
|------|------|
| `ping` | 连通性测试 |
| `agent.run` | 执行一次性任务 |
| `session.create` | 创建会话 |
| `session.sendMessage` | 发送消息 |
| `session.getHistory` | 获取历史 |
| `session.close` | 关闭会话 |
| `session.compact` | 手动压缩上下文 |
| `permission.respond` | 权限审批响应 |
| `event.subscribe` | 订阅事件流 |

## 事件流

守护进程通过 EventBus 发布事件，经 IpcBroadcaster 推送到订阅客户端：

- `core.started` / `run.started` / `run.finished`
- `step.started` / `step.finished`
- `llm.token` / `llm.usage`
- `tool.call_started` / `tool.call_finished`
- `permission.requested` / `permission.granted` / `permission.denied`
- `session.created` / `session.closed`
- `context.compacted`

## 内置工具

| 工具名 | 功能 | 默认权限 |
|--------|------|---------|
| `bash` | 执行 shell 命令 | Ask |
| `write_file` | 写入文件 | Ask |
| `read_file` | 读取文件 | Allow |
| `list_dir` | 列出目录 | Allow |
| `task_create` | 创建任务 | Allow |
| `task_update` | 更新任务 | Allow |
| `task_list` | 列出任务 | Allow |

## 权限系统

6 层评估链：

1. **工具黑名单** — 危险命令直接拒绝
2. **工具白名单** — 安全工具直接允许
3. **全局策略** — policy.toml 定义的默认策略
4. **工具级策略** — 单个工具的 allow/deny 规则
5. **路径模式匹配** — 正则匹配输入参数
6. **人工审批** — 以上均无法裁决时，发布 PermissionRequestedEvent 等待用户响应

## 配置

支持 4 级优先级（后者覆盖前者）：

1. 内建默认值
2. `~/.mini-claude/config.toml`（TOML）
3. `.env` 文件
4. 环境变量

## MCP 集成

支持通过 MCP（Model Context Protocol）stdio 子进程接入外部工具。配置方式见 `config.toml` 中的 `[mcp.servers]` 段。

## 开发

```bash
# 编译全部
go build ./...

# 运行守护进程
go run ./cmd/mini-core/

# 运行 CLI
go run ./cmd/mini-claude/ ping

# 运行 TUI
go run ./cmd/mini-tui/
```

## 与原项目（Python）的对应关系

| Python | Go | 说明 |
|--------|-----|------|
| `asyncio` | `goroutine` + `channel` | 天然并发 |
| `asyncio.Future` | `chan Decision` | 权限审批等待 |
| `pydantic.BaseModel` | `struct` + JSON tag | 编译期类型安全 |
| `Protocol` | `interface` | 鸭子类型 → 显式接口 |
| `Textual` | `Bubble Tea` + `Lip Gloss` | TUI 框架 |
| `argparse` | `Cobra` | CLI 框架 |
| `tomllib` | `BurntSushi/toml` | TOML 读写 |