Octogent
用上下文、任务清单和可控终端协调多个 Claude Code 会话。
README 清楚说明本地 API、PTY、持久化目录、worktree、会话上限及清理命令，MIT 文件和仓库社交链接也提供了基本来源归属。扣分在于没有展示权限最小化模型或高影响操作的逐步确认；测试表明程序会读取 Claude/Codex OAuth 凭据、向 Anthropic/OpenAI 服务发送令牌，并可能改写 Codex auth.json，但所给材料未说明令牌脱敏、文件权限、用户同意、审计或完整的数据保留边界。依赖被锁定安装并通过 CI 构建，但没有依赖审计、更新策略或漏洞处置证据。worktree 提供部分隔离和可恢复性，然而对终端 kill、代理文件修改及外部 PR 等效果没有完整回滚保证。
README、包元数据、CI 和测试对 Node 22、pnpm、Claude Code、PTY、状态检测及用量读取的描述大体一致。依赖和必需二进制被明确列出，CLI/OAuth 回退、缓存、限流和凭据缺失均有覆盖；但项目尚未发布到 npm，PTY 无法跨 API 重启恢复，且当前文档只覆盖 Claude Code，因此可用性仍受本机工具和非公开接口影响。错误消息测试较充分，明确区分凭据缺失、权限范围不足、未授权、限流、解析错误和后台刷新状态，故 failure_messages 获满分。
目标用户和文档、数据库、API、前端、多代理并行等场景描述明确，tentacle、共享终端和 worktree 模式提供适度适配。边界也指出这是个人探索、当前仅文档化 Claude Code、需要外部二进制且存在 32 会话默认上限。扣分在于代理状态触发依赖终端文本标记和空闲超时启发式；虽然测试覆盖分块与 ANSI 情况，却没有展示可配置、结构化的触发协议或误判处置。环境要求和可调变量清楚，但 Node 22、git、gh、curl、Claude/Codex 凭据及本地 PTY 形成较强环境约束。
README 的概念、工作方式、快速开始、要求、持久化和文档索引组织完整，安装状态及本地和全局安装步骤尤其清楚；已明确列出 API 重启后 PTY 丢失、stale 记录、npm 未发布、文档仅覆盖 Claude Code等限制。MIT 许可证与 package.json 一致，故 license 获满分。扣分在于 0.1.0 之外没有变更日志、发布记录或兼容性承诺；名称总体一致，但 README 的 Deck 称谓缺少定义。示例主要是安装命令、场景和链接，所给材料没有 FAQ 内容。维护仅能从个人账号、社交链接及暂停审查 PR 的声明推断，缺少明确维护者身份、支持承诺和更新路径。
文件化上下文、todo 委派、可见的多终端控制、消息传递、worktree 隔离和本地 UI 构成可直接理解的工作产物，相比手工管理多个终端具有可信的增量价值。扣分在于所给证据主要是设计说明、截图引用和针对内部解析/状态逻辑的测试，没有静态证据量化任务完成率、协调开销下降或大规模编排效果。成本面仅展示用量读取和会话上限，未解释模型调用、并行代理、磁盘、凭据暴露及人工监督成本与收益的权衡。
主要能力可追溯到 README 的具体文件布局、命令和运行约束，package.json、CI 及测试对版本、构建链、状态检测、OAuth 回退和错误行为提供交叉支持。扣分在于完整实现文件、锁文件、被链接的详细文档和截图内容未提供，许多编排、消息、终端生命周期及 worktree 声明无法在本材料内逐项核对。README 会区分愿景、当前安装状态和若干限制，但仍有营销性价值陈述未与测量结果或独立证据分开。
- 该程序会读取本机 Claude/Codex OAuth 凭据，并可能把刷新后的 Codex 令牌写回 auth.json；使用前应审查实际实现中的文件权限、日志脱敏、网络目标和令牌保留方式。
- 代理可运行终端、修改共享工作区并并行执行 todo；应先在低权限测试仓库中使用 worktree，并为提交、推送、PR、删除和 kill 操作建立人工确认与恢复流程。
- npm 包尚未发布，PTY 在 API 重启后不可恢复；应固定所审查的提交和依赖锁文件，并为 stale 会话及未提交改动准备清理方案。
- 状态检测包含对终端文本和超时的启发式判断，界面中的 idle 或 processing 状态不应被视为代理已安全完成任务的证明。
这个 Agent 能做什么，适合哪些场景？
Octogent 是运行在本地的 Claude Code 编排面板，用来管理多个并行编码会话，而不是取代终端代理本身。它把每项工作组织为 `.octogent/tentacles/<tentacle-id>/` 下的 tentacle，其中包含 `CONTEXT.md`、`todo.md` 以及笔记或交接文件。其本地 API 管理终端记录、PTY 会话、持久化和 WebSocket 传输，Deck 界面则读取任务文件并展示代理状态、转录和空闲事件。协调代理可以从未完成的待办项生成工作提示、启动子代理，并通过短消息收集完成情况、阻塞原因和交接信息。终端既可共享主工作区，也可在 `.octogent/worktrees/<worktree-id>/` 中使用独立 Git worktree；项目脚手架保存在仓库内，运行状态和转录则存放在用户目录。它适合愿意自托管本地工具、以 Claude Code 为主要执行环境，并需要同时监督多条开发工作流的个人开发者。
Octogent 启动本地 API 和 Web UI，并为项目创建 .octogent/ 脚手架、稳定的项目 ID，以及从 8787 开始选择的可用 API 端口。Deck 直接读取 tentacle 内的 CONTEXT.md、todo.md 和补充 Markdown 文件，解析 todo.md 的复选框，并根据未完成项生成子代理工作提示。本地 API 创建和管理 Claude Code 终端及 PTY 会话；多个终端可以共享一个 tentacle，也可以在 octogent/<worktree-id> 分支对应的独立 worktree 中运行。Claude hooks 通过回调把代理状态、转录和空闲事件传给 API，界面再通过 WebSocket 展示这些信息。代理之间可以发送完成报告、阻塞信息和交接说明，而运行元数据、转录和监控缓存会持久化到 ~/.octogent/projects/<project-id>/state/。
- 同时处理文档、数据库、API 和前端工作的独立开发者，可为每个领域建立单独 tentacle，避免多个终端之间的上下文混杂。
- 需要把大型改造拆成多个可追踪任务的技术负责人，可在
todo.md中维护复选框条目，并据此启动多个工作代理。 - 希望保留人工监督能力的 Claude Code 用户，可在同一面板中查看并控制每个子代理，而不是只依赖代理内部的子代理机制。
- 需要并行试验且不希望所有修改落在主工作区的开发者，可使用基于
octogent/<worktree-id>分支的 worktree 终端。 - 经常因浏览器刷新或切换界面而丢失观察上下文的用户，可利用项目状态、转录和 tentacle 文件的本地持久化继续跟踪工作。
这个 Agent 有哪些优点和局限？
- 以
CONTEXT.md、todo.md和补充文件作为持久、可检查的共享上下文，减少对单一聊天记录的依赖。 - 不仅聚合多个终端，还支持由一个 Claude Code 代理分派工作、启动可见的子代理并交换交接消息。
- 共享工作区和 Git worktree 两种终端模式兼顾快速协作与分支隔离。
- 本地 API、WebSocket 界面、hooks、转录和运行状态形成了比纯终端输出更完整的监督层。
- 默认最多保留 32 个活动 PTY 会话，并允许通过
OCTOGENT_MAX_TERMINAL_SESSIONS调整上限，以限制主机资源占用。
- 核心工作流和现有文档围绕 Claude Code，缺少其他模型平台的可验证使用说明，迁移到其他提供商并非开箱即用。
- 尚未发布到 npm；采用者必须克隆源码、安装依赖、构建并从本地目录安装 CLI。
- PTY 会话无法跨 API 重启存活；重启后无法重新连接的运行记录会被标记为
stale，需要人工检查和清理。 - 运行需要 Node.js 22+、Claude Code CLI、git、gh 和 curl 等多项本地依赖，其中部分功能还依赖 Claude hooks。
- 项目目前不积极审查拉取请求，依赖上游合并贡献或获得维护反馈存在不确定性。
如何安装或部署这个 Agent？
当前尚未发布到 npm，因此 npm install -g octogent 还不可用。需要 Node.js 22+、已安装的 claude、用于 worktree 的 git、用于 GitHub 拉取请求功能的 gh，以及 Claude hook 回调使用的 curl。本地开发步骤：
git clone https://github.com/hesamsheikh/octogent.git
cd octogent
pnpm install
pnpm dev从克隆目录安装全局 CLI：
pnpm install
pnpm build
npm install -g .
octogent首次运行会自动创建 .octogent/，分配项目 ID，选择从 8787 开始的可用本地端口并打开界面。若不希望自动打开浏览器，可设置 OCTOGENT_NO_OPEN=1。
如何使用这个 Agent？
在目标项目中运行 octogent；进行源码开发时则在仓库中执行 pnpm dev。为一项工作建立 .octogent/tentacles/<tentacle-id>/，用 CONTEXT.md 描述范围，在 todo.md 中写入可勾选任务，并按需加入笔记或交接 Markdown 文件。随后将终端连接到该 tentacle；既可以启动单个工作代理，也可以从多个未完成的待办项启动并行工作。通过 Deck 查看终端输出、代理状态和转录，并利用代理间消息收集完成、阻塞及交接信息。共享终端直接修改主工作区；需要隔离时使用 worktree 终端。可用 octogent terminal list、stop、kill 和 prune 检查或清理终端记录。
这个 Agent 与同类方案有什么区别？
与 Claude Code 自带的子代理启动机制相比，Octogent 强调让开发者直接看到并控制每个工作代理，并使用 tentacle 文件、待办项和消息构建父代理—工作代理流程。它也不只是多终端面板：终端生命周期之外，还加入了作用域上下文、任务委派、持久化转录和可选 Git worktree 隔离。
常见问题
是否可以直接从 npm 安装？
pnpm install 和 pnpm build，再执行 npm install -g .，或使用 pnpm dev 进行本地开发。它是否支持 OpenAI API、Codex 或 ChatGPT？
codex，但没有提供 Codex、ChatGPT 或 OpenAI API 的安装、适配器或运行步骤，因此不能视为已验证支持。API 或浏览器重启后任务会保留吗？
stale。并行代理会不会相互覆盖代码？
.octogent/worktrees/<worktree-id>/、对应 octogent/<worktree-id> 分支的 worktree 终端。数据存放在哪里，是否必须使用托管服务？
.octogent/，运行状态、转录、监控缓存及元数据位于 ~/.octogent/projects/<project-id>/state/。没有说明必须使用外部托管服务。