LunarWerxs/AgentHydra · 上手攻略

  • 仓库：LunarWerxs/AgentHydra
  • 链接：https://github.com/LunarWerxs/AgentHydra
  • 分类：agent · experimental（周增 +14 stars，46 stars，MIT，TypeScript）
  • 作者：spark
  • 更新：2026-10-14

§0 自检（3 证 checklist）

证 内容 状态
GitHub URL 已 fetch https://github.com/LunarWerxs/AgentHydra 200 OK，全文已抓取 ✅
README 子模块 anchor ≥ 1 已锚 /blob/main/docs/REFERENCE.md、docs/CLIMAYTE.md、docs/AI_USAGE_SELFCHECK.md、docs/CLAUDE-DESKTOP-NATIVE-CONTROL.md ✅
顶会 / 引用 anchor 无（本地工具，未发表论文） ⚠️ 不适用，已标注

⚠️ 诚实标注：本仓库是 MIT-licensed 本地工具，与上游 claude-code-managerui 同源；README 自陈 "The old repo URL redirects, ~/.ccmanagerui moves to ~/.agenthydra on first run"——即把上一代产品直接搬过来做了改名与扩展。

§1 是什么

LunarWerxs/AgentHydra 是一个 Windows/macOS/Linux 本地桌面应用，把你所有本机的 AI 编程会话集中到一个窗口里——Claude Code、Codex、OpenCode 的全部会话（自己跑、CLI 跑的、Claude Desktop 跑的）按项目分组实时挂在侧栏。

它同时是一座账号调度塔：多个 Claude/Codex 账号的套餐、5 小时/周配额、当前用量一目了然，可以从 UI 里 Open / Quit / Create 实例。配 CliMayte worker 后，任务列表可以扇出到多个 Claude CLI 账号，一个号快欠费时 worker 自动切到下一个账号继续跑——典型用法是"5 个 Claude Max 账号轮班跑一天"。

底层特点：

  • 本地化：纯本地，零云服务、零账号。
  • MCP 原生：所有功能（whatsmyname、限查询、任务调度、CliMayte、orchestrator）都通过同一个 MCP server 暴露；其它 agent（Claude / Cursor / Codex …）可以直接调它。
  • 会话忠实：不替你"代跑"——AgentHydra 自己明确说"never runs claude headless, and the scheduler is off by default"；它读取 Claude Code、Codex、OpenCode 已经在磁盘上写的 history，让 UI 去做聚合和导航。

§2 解决什么问题

把"多 AI CLI/IDE × 多账号 × 多项目 × 多时间段"这件事变成：

  1. 一个侧栏：所有 Claude Code / Codex / OpenCode 会话（本地 + Login sync 看到的另一台），按项目分组，能筛选"运行中 / 等你回复"。
  2. 一个 Dev Servers 页：你的项目里 .claude/launch.json 或 package.json 的 dev 脚本所起的本地服务（CPU、内存、logs、错误、alert）都在里面，点开就在聊天右侧开一个浏览器窗。
  3. 一个账号表：所有 Claude/Codex 账号的套餐、5h 配额、本周配额、当前窗口、打开/退出/创建实例。
  4. 一个 Cost 仪表盘：按 day/model/project/account 切的成本（含 cache hit、>150k 长上下文调用、subagent 子开销），并给出"这一项能怎么省"的一句话修复。

换句话说：它不是"再做一个 AI"，而是给已经被 CLI/IDE 工具写得到处都是的 chat 状态做仓库管理。

§3 快速安装

3.1 Windows（最快，一行；非管理员）

irm https://raw.githubusercontent.com/LunarWerxs/AgentHydra/main/install.ps1 | iex

⚠️ README 明示"下载物先校 SHA-256 才解包"。

3.2 从 GitHub Releases 拿

  • Windows：.zip（约 12 MB，含应用本体 + tray icon + orchestrator）；单 .exe 是一个小启动器，第一次运行时从同一个 release 拉其余部分；两者都 self-update。
  • Linux / macOS：.tar.gz（约 8 MB；README 自报"macOS and Linux builds exist but are not verified yet"⚠️）。
  • 启动器第一次会 fetch 发布版对应的 Bun（按 Bun 官方 checksum 校验）+ Claude Code，不自带。

3.3 从源码跑

git clone https://github.com/LunarWerxs/AgentHydra.git
cd AgentHydra && bun install && bun install --cwd desk2
bun run build && bun run start

依赖：仅 Bun（源码构建需要）；运行依赖 Claude CLI 和/或 Claude Desktop（要用 Claude 功能就得有）；可选 Codex Desktop/CLI、OpenCode、Hermes Agent、~/.dsh（DeepSeek Harness）——它们各自的 session 文件存在时自动出现在 AgentHydra。

Windows 上做"实例管理"需要 Claude Desktop 的经典 Squirrel 安装版，不是 MSIX。

§4 核心用法

4.1 侧栏——只看

打开应用，左边一列就是所有 Claude Code / Codex / OpenCode 会话（含 Claude Desktop 的），按项目分组。能按"app / only running / only waiting on me"过滤，开 Login sync 后能看到另一台 PC 上的会话。

4.2 New——从哪儿开新会话

点 New，弹出项目网格：每行 = 一个项目（来自 Project Hydra、你加的目录、或者你过去跑过 chat 的任意位置），含 git 状态和"现在开了几个 chat"。在一级目录开的 chat 会被归档到它实际工作的项目。

4.3 Dev Servers——项目本地服务

去 Dev servers 页，对每个项目可 start/stop/restart、看 logs/errors/CPU/内存/alert。它先读 .claude/launch.json 或 package.json 的 dev 脚本——不需要额外配（README 标注："This was DevWebUI; it is part of AgentHydra now."）。

4.4 CliMayte——任务派发

把一个 todo list 交给 CliMayte：worker 把每项派到不同的 Claude CLI 账号的 chat（每个账号一个 visible chat），某账号接近 5h 限额时自动切到下一个继续推进。整个 flow 没有 console 窗口，但每条 worker 都能在 CliMayte view 里看和 steer，转录就是普通 session。

4.5 账号管理——Instances

Instances 页里每行 = 一个 Claude Desktop 实例（账号 / 套餐 / 配额 / 进程），可 open、focus、quit、create、delete（delete 要求你输名字）；Codex Desktop / CLI 同理。Settings → Instances → Desktop 里能开"Start debugger automatically"开 Claude 原生控制。

4.6 成本分析

"Cost by day / model / project / account"，原价（"以 list price 跑这些 token 要多少钱"），不算真实花费。还自带"可疑会话"面板——常失败的工具、context 被压缩的、code 两小时后从磁盘消失的——以及 "Recurring mistakes"，把每次失败的 shell 与其修复命令两两配对，一键 "Copy as rules" 导出为 agent rules。

CLI 版的同一份数：AgentHydra.exe --spend --json。

4.7 ChatGPT handoff

把当前任务和仓库打包成一个 .md（默认排除常见 secret 文件），拷一份 prompt，开 ChatGPT——你检查后自己按 Send。

4.8 通过 MCP 给外部 agent 用

整个项目都通过 MCP server 暴露，外部 agent 可调：

  • climayte_run / climayte_status / climayte_send / climayte_cancel / cli_limit_reset
  • whoami、usage_*（agent 先问"我是谁、还剩多少"，再决定派谁）
  • Orchestrator（orchestrator/ 目录下，policy 在 orch.py）做 sweeping / moving / archiving / naming 等家务

详见 docs/REFERENCE.md、docs/CLIMAYTE.md、docs/AI_USAGE_SELFCHECK.md。

§5 典型适用场景

场景 用法
一个人多个 Claude Max 账号轮班跑长任务 CliMayte：worker 自动切号
同时在 5 个项目里跑 Claude Code New 页 + 侧栏分项目
看哪一个项目今天开支最大、哪些 subagent 在浪费 Cost 仪表盘 → 删掉未用的 skill/MCP、给 >150k context 提个醒
公司里只有一台 PC 想共享 desktop 实例给同事看 用 Login sync 让另一台 PC view-only
想用 Claude 控制 Claude（agent 打 agent） orchestrator MCP，调 climayte_run，按 AI_USAGE_SELFCHECK 先做 whoami
偶尔需要把任务扔给 ChatGPT ChatGPT handoff：自动打包 + 拷 prompt + 开页面
看到 .jsonl 想进编辑器直接看 右键 raw session，下载 / 复制 / 在编辑器里打开

§6 坑与注意（≥6 坑）

  1. Windows 桌面实例管理 ≠ MSIX：必须用经典 Squirrel 安装版 Claude Desktop。MSIX 装的找不到 instance。
  2. macOS / Linux 构建存在但 README 自报"未验证" ⚠️——愿意当 early adopter 的可跑，但稳定性没保证。
  3. Codex / OpenCode 是 read-only：在 AgentHydra 里能看到和读它们的会话，但回复只支持 Claude。要回 Codex/OpenCode 的消息得切到原 client。
  4. scheduler 默认关闭 + 从启动器版本起拒绝 headless 新跑：不会替你偷偷在后台跑 claude。但 CliMayte 显式 invoke 会派单到真实账号 chat（可见、可 steer）。
  5. 网络出站有限：AgentHydra 主要读本地文件 + 跟 localhost 通信；自主出站只走 studio.connections.icu（一个 LunarWerx 转发 GitHub release feed 的中继，请求只发 app 版本 + OS tag + 随机 install id，IP 不存），只用来查更新。设 AGENTHYDRA_NO_PING=1 即直连 GitHub。
  6. MCManagerUI 迁移：旧 CCManagerUI_* 环境变量仍可用，第一次跑自动把 ~/.ccmanagerui 搬到 ~/.agenthydra。迁移期间配置里写 CCManagerUI.exe 的脚本/快捷方式顺手改改名。
  7. Delete 实例需要输名字：README 明确"as a precaution"——别让脚本一键删错了。
  8. ⚠️ 本攻略没有独立审计 orchestrator 的 MCP 鉴权/限查询覆盖度——多账号轮班的 security model 见 docs/REFERENCE.md，上生产前自验。

§7 与同类对比

维度 LunarWerxs/AgentHydra Claude Squad / Conductor Cursor / Windsurf
形态 本地聚合 UI + MCP 一个新会话起在一个新 git worktree IDE 编辑器
数据来源 读你在 Claude Code/CLI/Desktop 留下的 history（不自己启动） 新开 headless 会话 内置
多账号调度 CliMayte worker 自动切号 不涉及 不涉及
成本视图 day/model/project/account，可疑会话面板 无 内置
Agent 互操作 原生 MCP（外部 agent 可调用全部功能） 无 MCP 部分支持
项目级 Dev Servers 自带，读 .claude/launch.json / package.json dev 无 插件
数据主权 完全本地 半托管 云端

⚠️ 不存在"用 AgentHydra 替代 Cursor"——它是一款 dashboard，不是 IDE。你仍然用你的 Claude Code / Codex / OpenCode CLI/IDE 进行实际编码，AgentHydra 在它们的侧边做汇总/调度/成本。

§8 一句话推荐结论

一句话：给"我已经用 Claude Code + Codex + 几个号 + 多个项目"的人搭的本地仪表盘 + 多账号 orchestrator。

适用：深度 Claude Code 多账号玩家、要给多项目排成本的人、想给自家 agent 暴露 MCP 调度的 builder。

不适用：刚装 Claude Code 一个号一个项目的小白（用不上调度）；只想要一个 IDE 的人（这是个 dashboard，不是 IDE）；对 macOS/Linux 稳定性敏感的人（README 明示未验证 ⚠️）。

最大风险：实验阶段 + macOS/Linux 未官方验证 + 多账号编排时若 MCP 鉴权配置疏漏会让 CliMayte worker 切号不规范——上 multi-account 编排前先把 docs/REFERENCE.md + docs/AI_USAGE_SELFCHECK.md 看一遍、给 orchestrator 设独立账号池。