Screenshots

GitHub 地址：https://github.com/hesamsheikh/octogent

简介

Octogent​ 是一个构建在 Claude Code 之上的本地多智能体编排（Orchestration）层。它的名字源于“Octopus”（章鱼）和“Agent”（智能体），寓意像章鱼一样，用一个大脑（开发者）协调多条触手（AI 智能体）并行工作。

如果你曾因同时打开多个 Claude Code 终端而感到混乱——分不清哪个窗口在处理数据库迁移，哪个在重构前端，Octogent 就是你的救星。它不是要替代 Claude Code，而是为其添加了上下文隔离、任务队列和父子智能体通信能力。通过将“聊天上下文”转化为“文件化的工作区”，它让单个开发者能轻松驾驭一个 AI 智能体团队。

主要功能

1. 触手（Tentacles）：上下文隔离的工作区

Octogent 的核心概念是 Tentacle（触手）。每个 Tentacle 是文件系统中的一个独立文件夹（位于 .octogent/tentacles/），包含：

• CONTEXT.md：该工作区的专属上下文（如“仅关注用户认证模块”）。

• todo.md：待执行的任务列表，作为智能体的指令源。

• notes：智能体在协作中产生的临时笔记。

这解决了 AI 编程中常见的“上下文污染”问题。你可以让“触手 A”专注修复 Bug，让“触手 B”同时编写文档，两者互不干扰。

2. 任务驱动与智能体孵化

• 任务即指令：智能体从 todo.md中读取任务并执行，完成后标记状态。任务本身就是自然语言指令。

• 父智能体管理子智能体：一个“协调者” Claude Code 智能体可以读取任务列表，自动孵化（Spawn）新的子智能体去并行处理不同任务，并接收它们的完成报告。

3. 本地 Web 仪表盘与 API

Octogent 提供了一个本地 Web UI（默认端口 8787），用于实时监控所有 Tentacle 的状态、任务进度和智能体间的消息流。同时，其底层 API 支持对智能体生命周期进行编程式控制。

安装与配置

环境要求

• Node.js 22+

• Claude CLI：必须已安装并配置好 claude命令行工具。

• Git：用于工作树（Worktree）管理。

• 推荐工具：gh（GitHub CLI）用于 PR 相关功能。

安装步骤

由于 Octogent 尚未发布到 npm registry，目前仅支持源码安装：

1. 克隆仓库

   git clone https://github.com/hesamsheikh/octogent.git
   cd octogent

2. 安装依赖

   pnpm install

3. 构建与全局安装（可选 CLI）

   pnpm build
   npm install -g .  # 将 octogent 命令安装到全局

首次运行配置

1. 在项目根目录执行 pnpm dev或直接运行 octogent。

2. 首次启动时，Octogent 会自动在项目根目录创建 .octogent/脚手架，生成唯一的项目 ID，并尝试打开浏览器访问 Web UI。

3. 数据持久化：运行时状态（如会话记录）保存在 ~/.octogent/projects/下，而 Tentacle 的上下文数据保存在项目本地。

如何使用

基础工作流：单人多任务

1. 创建 Tentacle：在 UI 中或通过 CLI 创建一个名为 docs-refactor的 Tentacle。

2. 编写 Context：编辑 .octogent/tentacles/docs-refactor/CONTEXT.md，明确范围：“你负责 src/docs/目录下的所有 Markdown 文件，请统一格式。”

3. 添加任务：在同目录的 todo.md中写入：

   - [ ] 修复 API 参考文档中的过期接口描述
   - [ ] 为所有代码示例添加语法高亮标签

4. 启动智能体：在 UI 中为该 Tentacle 启动一个 Claude Code 会话。智能体会读取 Context 和 todo，开始逐个完成任务并打勾。

进阶工作流：智能体经理（Manager Agent）

1. 创建一个 managerTentacle，其 todo.md中列出宏观任务：“重构登录模块”、“优化数据库查询”。

2. 启动一个“经理”智能体。它会分析任务，自动为每个子任务创建新的 Tentacle 和子智能体。

3. 经理智能体通过 Octogent 的消息机制接收子智能体的进度报告，实现全自动的“拆解-分发-汇总”流程。

应用场景实例（无代码）

场景一：全栈应用的“分模块”大重构

痛点：你需要同时重构后端的 API 接口、前端的调用逻辑以及数据库的 Schema。在单一聊天窗口中切换上下文极易出错。

Octogent 方案：

1. 创建三个 Tentacle：api-refactor、frontend-adapt、db-migration。

2. 在每个 Tentacle 的 CONTEXT.md 中精确定义边界和依赖（如“前端需等待 API 版本号更新后再适配”）。

3. 通过 UI 同时启动三个 Claude Code 智能体。你可以像项目经理一样，在仪表盘上同时监控三个模块的进度，而不会把指令发错窗口。

场景二：开源项目的“社区贡献”自动化筛选

痛点：作为维护者，你需要处理大量 Issue 和 PR，手动分类和分配任务非常耗时。

Octogent 方案：

1. 创建一个 issue-triagerTentacle，配置其定期运行（通过 Cron）。

2. 其 todo.md由脚本自动填充：“分析 Issue #123 是否为 Bug”、“给 PR #456 打上 needs-review标签”。

3. Claude Code 智能体作为“机器人助手”，自动执行分类、打标签、甚至回复标准化评论的任务，你只需在 UI 中审核结果。

场景三：技术栈迁移的“渐进式”验证

痛点：将项目从 JavaScript 迁移到 TypeScript，担心一次性迁移导致项目不可用。

Octogent 方案：

1. 创建多个 Tentacle，每个负责一个目录（如 migrate-auth、migrate-utils）。

2. 设置任务为“将 src/auth/目录下的 JS 文件转换为 TS，并修复类型错误”。

3. 逐个激活 Tentacle，在一个模块完全测试通过后，再启动下一个。这种“增量式”迁移通过 Tentacle 的隔离性得到了完美保障。

总结

Octogent 填补了“强大 AI 编程工具”与“可管理的工作流”之间的空白。它将 Claude Code 从一个单纯的对话式编码助手，升级为一个可编排、可观测、可复用的智能体基础设施。对于独立开发者或小团队，它是管理复杂多任务开发的“力量倍增器”。

GitHub 地址：https://github.com/hesamsheikh/octogent