# KairoCode

> Terminal AI Coding Agent prototype with Agent Loop, MCP tools, permission guardrails, memory, and multi-agent collaboration.

- **Type:** MCP server
- **Install:** `agentstack add mcp-yangf-veda-kairocode`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yangf-Veda](https://agentstack.voostack.com/s/yangf-veda)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yangf-Veda](https://github.com/yangf-Veda)
- **Source:** https://github.com/yangf-Veda/KairoCode
- **Website:** https://github.com/yangf-Veda/KairoCode#readme

## Install

```sh
agentstack add mcp-yangf-veda-kairocode
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# KairoCode

KairoCode 是一个用 Python 实现的本地终端 AI 编程 Agent，目标是复刻 Claude Code 类工具的核心工程路径：在 Textual TUI 中对话、规划、调用工具、执行多轮 Agent Loop，并在权限护栏内读写代码、运行命令和协调子 Agent。

这个仓库定位为可运行原型，不是生产级代码执行沙箱。它用于探索 Agent Loop、工具调用、权限控制、上下文管理、MCP 扩展和多 Agent 协作等 LLM 应用工程能力。

## 项目实现截图与证据

下面的素材优先展示 Windows Terminal 中真实运行的 KairoCode TUI。前四组是实际操作截图，随后是可直接播放的 MCP GIF 演示；架构图、流程图和命令输出 SVG 作为补充证据，用来说明实现边界和可复现验证。

### TUI 启动

启动后进入 `DEFAULT` 权限模式，显示当前工作目录、模型名称、输入框和状态栏。

### 自然语言对话

真实对话中，KairoCode 会结合当前工作目录说明自身能力边界，包括项目内文件操作、环境感知、流程协作和安全限制。

### Slash 命令补全

`/help` 是本地命令，不进入模型对话历史；截图展示 TUI 内的命令系统和状态栏。

### 多 Agent 后台任务

示例中主 Agent 同时派发两个子 Agent：一个负责电商系统实施计划，一个负责外卖系统实施计划。TUI 中可以看到后台任务 ID、子代理名称和运行状态。

### MCP 本地文档服务演示

演示中要求模型只使用 MCP 工具，不使用内置 `read_file` / `grep` / `glob`。KairoCode 通过 `local_docs` MCP server 列出 `docs/` 文档、读取 `technical-highlights.md`、搜索 `Agent Loop`，并在 TUI 中展示 `mcp__local_docs__list_docs`、`mcp__local_docs__read_doc`、`mcp__local_docs__search_docs` 等真实工具调用。

### Agent Loop 工具调用

离线 fake provider 触发真实 Agent Loop，模型请求 `read_file`，KairoCode 执行工具并把结果回灌给下一轮模型输出。

### 权限审批

当模型请求 `write_file` 时，默认权限模式会在执行前进入人在回路审批；截图停在审批界面，未批准写入文件。

### 系统架构

### Agent Loop 执行流

### API-free Demo 输出

`examples/fake_provider_demo.py` 使用内置 fake provider 复现一次模型发起 `read_file` 工具调用、KairoCode 执行工具、工具结果回灌、模型继续生成最终回复的闭环。

### CLI 与质量验证

## 核心亮点

- **真实 Agent Loop**：模型可以多轮选择工具、读取工具结果并继续推理，不是单轮聊天包装。
- **统一工具系统**：内置文件读写、精确编辑、命令执行、glob、grep，并能接入 MCP 远端工具。
- **Plan Mode**：支持先进入只读规划模式，再切回执行模式推进任务。
- **权限系统**：危险命令黑名单、项目路径沙箱、权限模式和人在回路审批组成默认安全边界。
- **上下文工程**：系统提示分层、环境信息注入、计划提醒、上下文压缩和 Prompt Too Long 恢复路径。
- **会话与记忆**：JSONL 会话持久化、历史恢复、项目记忆索引注入和异步记忆刷新。
- **多 Agent 协作**：支持 SubAgent、后台任务、消息续派、Git worktree 隔离和 Team/Coordinator Mode。
- **工程质量**：围绕核心模块建立单元测试、TUI 行为测试、lint、format 和类型检查。

## 能力矩阵

| 工程域 | 当前能力 | 主要模块 | 验证方式 |
|---|---|---|---|
| Agent Loop | 多轮工具调用、取消、用量统计、自然停止 | `agent/`, `conversation.py` | `tests/test_agent.py`, `tests/test_run_to_completion.py` |
| 工具系统 | `read_file`、`write_file`、`edit_file`、`bash`、`glob`、`grep` | `tool/` | `tests/test_tool.py`, `tests/tool/` |
| 权限安全 | 黑名单、路径沙箱、规则匹配、审批模式 | `permission/` | `tests/test_permission_core.py` |
| Provider | Anthropic 与 OpenAI 兼容协议、流式事件、token usage | `llm/` | `tests/test_anthropic_provider.py`, `tests/test_openai_provider.py` |
| MCP | stdio/http 配置、连接管理、工具适配、权限复用 | `mcp/` | `tests/test_mcp_*.py` |
| 上下文压缩 | token 估算、摘要压缩、恢复段、手动 `/compact` | `compact/` | `tests/test_compact_layer1.py` |
| 会话与记忆 | JSONL 存档、`/resume`、项目记忆、自动刷新 | `session/`, `memory/` | `tests/test_session.py`, `tests/test_memory.py`, `tests/test_tui_app.py` |
| Slash 命令 | `/help`、`/status`、`/memory`、`/permission`、`/session` 等 | `command/` | `tests/test_command_*.py` |
| Skill 与 Hook | 项目级 skill、工具白名单、生命周期 hook | `skills/`, `hook/` | `tests/test_skills*.py`, `tests/test_hook_system.py` |
| SubAgent | 内置/项目级角色、后台任务、`SendMessage` 续派 | `subagent/`, `task/` | `tests/subagent/`, `tests/task/` |
| Worktree | 子 Agent Git worktree 隔离、cwd 注入、`/worktree` | `worktree/` | `tests/test_worktree_*.py` |
| Team | 队员邮箱、共享任务、Coordinator Mode、后端抽象 | `team/`, `coordinator/` | `tests/team/` |

## 快速开始

环境要求：Python 3.12+。

```powershell
python -m pip install -e ".[dev]"
Copy-Item .kairocode/config.yaml.example .kairocode/config.yaml
```

如果使用 `uv`，可以用锁文件复现依赖解析结果：

```powershell
uv sync --extra dev
```

编辑 `.kairocode/config.yaml`，填入自己的 provider。示例：

```yaml
providers:
  - name: DeepSeek
    protocol: openai
    model: deepseek-chat
    base_url: https://api.deepseek.com
    api_key: your-deepseek-api-key

features:
  coordinator_mode: false
  fork_teammate: false
```

启动：

```powershell
kairocode
# 或
python -m kairocode --config .kairocode/config.yaml
```

如果只想验证入口是否可用：

```powershell
python -m kairocode --help
```

不配置真实 API Key 也可以先运行内置 fake-provider demo，观察一次模型请求工具、工具结果回灌、最终回复的最小闭环：

```powershell
python examples/fake_provider_demo.py
```

## 配置与安全

真实密钥配置文件是 `.kairocode/config.yaml`，已经被 `.gitignore` 忽略。不要把真实 API Key 提交到仓库；公开仓库只提交 `.kairocode/config.yaml.example`。

权限配置示例位于 `.kairocode/settings.yaml.example`。启动时按以下优先级加载：

1. `.kairocode/settings.local.yaml`：个人本地规则，已忽略。
2. `.kairocode/settings.yaml`：项目共享规则。
3. `~/.kairocode/settings.yaml`：用户全局规则。

权限模式包括 `default`、`acceptEdits`、`plan` 和 `bypassPermissions`。危险命令黑名单和路径沙箱属于硬性护栏，即使在 `bypassPermissions` 下也不会主动放开高风险命令或项目外写入。

MCP 项目级配置使用根目录 `.kairocode.yaml`，可参考 `docs/mcp/mcp-servers.example.yaml`。真实 MCP 配置通常包含本机路径或令牌，默认不提交。

## 架构入口

```text
src/kairocode/
  agent/        Agent Loop 与工具执行编排
  command/      Slash 命令注册、分发和内置命令
  compact/      上下文压缩、恢复段和 token 估算
  hook/         生命周期 hook 加载、匹配和执行
  llm/          Anthropic/OpenAI provider 适配
  mcp/          MCP 配置、连接管理和工具适配
  memory/       项目记忆读取、写入和索引注入
  permission/   权限规则、沙箱、审批与模式
  session/      会话 JSONL 存档、恢复和列表
  skills/       Skill 加载、激活和工具白名单
  subagent/     子 Agent 定义、加载和内置角色
  task/         后台任务管理和任务工具
  team/         Team 协作、邮箱、共享任务和执行后端
  tool/         内置工具与注册中心
  tui/          Textual 终端界面
  worktree/     Git worktree 隔离、会话和清理
```

更完整的数据流说明见 [docs/architecture.md](docs/architecture.md)。

## Demo

推荐 Demo 路径：

1. 先运行 `python examples/fake_provider_demo.py`，无需 API Key 复现一次工具调用闭环。
2. 配置一个 OpenAI 兼容 provider。
3. 启动 `kairocode`。
4. 输入一个需要读取、搜索或修改当前项目文件的任务。
5. 观察模型发起工具调用、权限审批、工具结果回灌和最终回复。
6. 运行本地测试或 `git diff` 检查变更。

详细步骤见 [docs/demo.md](docs/demo.md)。如果当前环境没有 tmux，可以用 CLI help、单元测试、工具/权限测试和人工 TUI 观察作为替代证据。

## 验证

```powershell
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check --no-cache .
.\.venv\Scripts\python.exe -m ruff format --check --no-cache .
.\.venv\Scripts\python.exe -m mypy src\kairocode
.\.venv\Scripts\python.exe -m kairocode --help
git diff --check
```

没有使用项目虚拟环境时，可以把 `.\.venv\Scripts\python.exe` 替换为 `python`。

## 文档

- [架构说明](docs/architecture.md)
- [技术亮点](docs/technical-highlights.md)
- [Demo 指南](docs/demo.md)
- [作品提交说明](docs/submission.md)
- [Roadmap](docs/roadmap.md)
- [完整文档索引](docs/README.md)

## 推荐阅读路径

如果想快速理解项目，推荐按下面顺序看：

1. [README 能力矩阵](#能力矩阵)：确认项目覆盖哪些 Agent 工程模块。
2. [架构说明](docs/architecture.md)：看用户输入、模型、工具、权限和结果回灌的数据流。
3. [技术亮点](docs/technical-highlights.md)：看 Agent Loop、权限系统、上下文工程、MCP 和多 Agent 协作的设计取舍。
4. [Demo 指南](docs/demo.md)：看如何本地复现工具调用和权限观察。

## Roadmap

已完成的主线能力包括工具系统、权限系统、MCP、上下文压缩、会话/记忆、Slash 命令、Skill/Hook、SubAgent、Worktree 和 Team 协作。

下一期优先补强：

- Agent 执行轨迹导出与工具调用回放，提升可观测性和 Demo 说服力。
- `/resume` 的交互体验和异常恢复验证，闭合记忆与会话恢复链路。
- 针对真实任务的轻量评测集，量化工具调用成功率、权限拦截和任务完成率。

完整路线图见 [docs/roadmap.md](docs/roadmap.md)。

## License

MIT License. See [LICENSE](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yangf-Veda](https://github.com/yangf-Veda)
- **Source:** [yangf-Veda/KairoCode](https://github.com/yangf-Veda/KairoCode)
- **License:** MIT
- **Homepage:** https://github.com/yangf-Veda/KairoCode#readme

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yangf-veda-kairocode
- Seller: https://agentstack.voostack.com/s/yangf-veda
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.