KairoCode

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+。

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

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

uv sync --extra dev

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

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

启动：

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

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

python -m kairocode --help

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

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 配置通常包含本机路径或令牌，默认不提交。

架构入口

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 观察作为替代证据。

验证

.\.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
• Source: yangf-Veda/KairoCode
• License: MIT
• Homepage: https://github.com/yangf-Veda/KairoCode#readme

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