🔥 kunchenguid/firstmate：与一个 Agent 对话，由一支团队交付

与一个 Agent 对话，由一支团队交付。

运行一个编程 Agent 很容易。但当你想并行完成三个项目任务——修复、调研、规划、审计——你就会变成一个不断切换标签页的人：照看会话、在仓库间复制粘贴上下文，还会忘记到底哪个终端里有失败的测试。

firstmate 颠覆了这一模式。你只需与一个 Agent——大副（first mate）——沟通，它会为你管理船员：在可见的会话后端中启动自主 Agent，为每个 Agent 分配干净的 git worktree，监督它们直至完成，并向你交付完成的 PR、已批准的本地合并或独立调研报告。对于更大的舰队，你可以选择启用持久化 secondmate：这些二副仍是普通的直属执行者，但可从本机或另一台可通过 SSH 访问的主机上、各自隔离的 firstmate home 中运行。

firstmate 不是模型、不是 harness、不是 skill、不是 MCP server，也不是 CLI。firstmate 是用于运行一支 Agent 团队的 Agent 发行版。Agent 发行版是一个可移植目录，包含指令、技能、工具、策略和状态约定，可将通用 Agent 转变为专用 Agent。无需安装应用：克隆的仓库就是发行版——包含 AGENTS.md、内置的 firstmate skills，以及任何终端编程 Agent 都能遵循的辅助脚本。在其中为你的主会话启动受支持的 harness，即会实例化你的大副，而你就是船长。

• 一个联络人 ——你只与大副沟通；它负责分派、监督，仅将真正的决策升级给你，并报告清晰的结果。
• 可见的船员团队 ——每名船员都在自己的 tmux 窗口、Herdr 标签页，或实验性的 zellij 标签页、cmux 工作区或 Orca 终端中工作；你可以观察或直接输入，大副负责协调。
• 一次性 worktree ——每项任务都在干净的 treehouse git worktree 中运行；当 backend=orca 时则使用 Orca 管理的 worktree，因此同一仓库上的并行工作不会发生冲突。
• 两类任务形态 ——交付任务（ship task）会提交已获授权的变更；当接收合同要求独立研究时，侦察任务（scout task）会留下独立调研报告。
• 明确的项目模式 ——每个项目通过 no-mistakes、direct-PR 或 local-only 交付，并可选用 +yolo 合并自主性标志。
• 可选 secondmate ——可选择启用持久化二副，它们在隔离的 firstmate home 中运行，拥有各自的 FM_HOME、状态、项目和会话锁；可部署在本地，也可将完整 home 部署至可通过 SSH 访问的主机。其更新与恢复机制均受到保护，绝不会将不可用的远程路径变成本地替代方案。
• 事件驱动、零 Token 监督 ——一个 bash watcher 在舰队上休眠，仅当有事项需要你处理时才唤醒大副；经过验证的主 harness 还具有回合结束兜底机制：当工作正在进行而监督未处于活跃状态时，它会阻止或跟进盲目停止。
• 可选 Relay ——使用一个本地 .env 配对令牌即可选择启用，使 firstmate 能同时回应你在 X 和 Discord 上的公开提及；它通过与聊天请求相同的生命周期处理常规、可逆的提及请求，确认已启动的工作，并在七天内针对真实里程碑和最终结果发布最多三条适于公开的完成跟进信息，同时不会改变非 Relay 行为。在帖子串中承诺的最终回复会成为持久化状态，并从磁盘进行协调，因此重启或会话压缩都不会使其丢失；正式启用前，试运行预览会在本地记录本应发送的回复和本应忽略的内容。
• 严格的项目边界 ——除 硬规则 1 授权的、受保护且经船长批准的有限操作外，大副对你的项目保持只读；其中包括 fleet sync 受保护的安全分支清理。所有其他项目变更均由船员在已配置的合并权限控制下执行。
• 可经受重启 ——全部状态均存储在磁盘和活跃会话后端中（硬性默认是 tmux；选择或自动检测时可使用 herdr 或 cmux；明确选择时可使用 zellij/orca）；可随时终止会话，下一次会话会进行协调——包括已确认死亡的 secondmate Agent——并继续工作。

每项功能的完整细节均位于 docs/architecture.md。

• 一个已验证的主 Agent harness：Claude Code、Grok、Pi、pi-signed、Oh My Pi（omp）、Codex、OpenCode 或 Cursor Agent CLI。
• Git 和 GitHub CLI，需通过 gh auth login 完成认证。
• 所选运行时后端的 CLI 与依赖项；tmux 是参考默认值。

大副会检测受支持但缺失的工具，并在你批准后提供安装选项。各后端的设置说明链接见下方文档。

Claude Code、Grok 和 Pi 是运行主 firstmate 会话时同等推荐的三个首选方案，其中 pi-signed 作为 Pi 独立的签名包装器身份受到支持。Claude Code 使用已跟踪的 Stop hook 来实现无需 Token 的 watcher 重启和重新唤醒；Grok 使用后台通知唤醒周期；Pi 使用其已跟踪的主 watcher 扩展。三者在按照各自文档设置启动时，均具有已验证的回合结束保护路径。请选择最符合你的订阅和工作流的方案。

作为 Pi 分支的 Oh My Pi（omp）也已验证可作为主 harness 使用，它采用与 Pi 相同的、由扩展拥有的 watcher 模型，并具有更强的回合结束保护：其阻塞式 session_stop hook 会强制继续，而非仅请求继续。Codex 和 OpenCode 也经过验证并被支持作为主 harness；Codex 使用有界的前台检查点，OpenCode 使用 TUI 插件，因此二者相比三个首选方案具有更多与 harness 相关的监督取舍。Cursor Agent CLI 也已验证可作为主 harness 使用，它通过项目作用域内已跟踪的 .cursor/hooks.json 实现，其 stop hook 会在回合之间停驻于 watcher 上，形态最接近 Claude Code。请使用 --trust 启动，否则其项目 hooks 不会加载；它在无头模式 cursor-agent -p 中也没有回合结束 hook，因此请以交互方式运行主会话。

gh auth login
git clone https://github.com/kunchenguid/firstmate
cd firstmate

然后启动任一首选 harness；此后由 AGENTS.md 接管：

Claude Code

Grok

Pi

pi
# 或者，在已安装签名包装器时
FM_PI_HARNESS=pi-signed pi-signed

Oh My Pi

omp
# 或者，从 Claude Code pane 内启动时
FM_OMP_HARNESS=omp omp

请将此 checkout 作为 omp 的工作目录启动：它会自动发现已跟踪的 .omp/extensions/*.ts 文件，无需信任对话框；如果还用 -e 显式指定这些文件，每个文件都会被加载两次。

对于 Grok，每个克隆副本需要执行一次 --trust，以便加载项目 hooks 和回合结束保护；也可以在 Grok 内使用 /hooks-trust。对于 Pi，首次启动时请针对每个克隆副本批准一次项目信任提示，以便已跟踪的 .pi/extensions/*.ts 文件自动加载。Pi 的 /calm 开关会隐藏受支持的会话记录界面元素，包括被规范归类的 Firstmate 运营用户行；在活跃运行期间，它会使用仅限 Calm 模式的动画工作船，同时保留全部模型上下文和会话数据。这些被 Calm 隐藏的运营输入仍是普通的 user-role 消息，其传递、排序、权限、持久化和导出均不变。该偏好会针对有效的 Firstmate home 持久保存，关闭后将恢复常规渲染。Calm 当前的行为与支持范围 独立于其按版本划分的维护者证据。Pi 的 /supervision-model 命令可仅为监督分支固定成本更低的模型和更浅的推理强度，候选范围来自 Pi 自身报告的可用模型和思考级别；若不固定，该分支通常遵循你自己的对话模型与强度设置。详见配置 schema。

> ahoy! 看看我的 github 项目 xyz，然后修复不稳定的登录测试并添加深色模式

# firstmate 会检查其工具链（安装任何内容前都会征求你的同意），
# 在 projects/ 下克隆项目，并在活跃后端中启动两个隔离的 worker。
# 数分钟后：

  PR 已准备好供审查，船长：https://github.com/you/xyz/pull/42
  （修复不稳定的登录测试——风险：低——CI 通过）

> 好，合并它

tmux（默认）以及其他所有受支持后端（herdr、zellij、Orca、cmux）的设置指南均在下方文档中链接。

你（船长）
      │  聊天：请求、决策、“合并它”
      ▼

┌─────────────────────────────────────┐ │ firstmate （本仓库） │ │ 读取 projects/ + firstmate 路由 │ │ 写入受保护的 backlog/briefs/state │ └──┬──────────────┬───────────────┬───┘ │ 后端发送 / 状态文件 │ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │fm-task1│ │fm-task2│ ... │fm-taskN│ tmux 窗口、herdr/zellij 标签页、cmux 工作区或 Orca 终端 │船员 │ │船员 │ │船员 │ 每个会话各运行一个自主 Agent └───┬────┘ └───┬────┘ └───┬────┘ ▼ ▼ ▼ treehouse worktree、Orca worktree，或隔离的 secondmate home │ ├─ ship：项目模式 ► PR/本地合并 ► 清理 │ └─ scout：报告位于 data//report.md ► 决策清单 ► 转发发现 ► 清理

你与大副聊天。它将每项请求路由至拥有各自会话端点和 git worktree 的船员，通过零 Token 的事件驱动 watcher 监督舰队，并向你交付完成的 PR、获批准的本地合并或调研报告。可选 secondmate 将此能力扩展至持久化的本地二副或远程完整 home 二副；分派配置文件允许你指定由哪个 harness 处理何种任务；选择启用的 Relay 则让同一舰队回应公开提及。codex-app 尚不是运行时后端；docs/codex-app-backend.md 定义了 Codex App 的边界。

完整架构——监督引擎、worktree 隔离、secondmate、分派配置文件、项目模式、可选 Relay、fleet sync 和自我更新——位于 docs/architecture.md。

Firstmate 提供以下可由用户调用的内置 skills。Claude 和 grok 使用此处显示的斜杠形式；codex 使用相同名称但以 $ 开头，例如 $afk。

Bearings 调用示例：

• /bearings 仅在聊天中返回最新的四部分摘要。
• /bearings include PRs 保持仅聊天模式，并选择启用实时 PR 信息补充。
• /bearings file 从头替换今天的 data/status-report-<YYYY-MM-DD>.md，并从四部分聊天摘要中链接该文件。
• /bearings file include PRs 将带日期的报告与实时 PR 信息补充结合起来。

仅供 Agent 使用的参考 skills 位于 .agents/skills/ 下。[原文在此处截断：are lo]

Talk to one agent. Ship with a crew.

You can run one coding agent easily. But the moment you want three project tasks done in parallel - fixes, investigations, plans, audits - you become a tab-juggler: babysitting sessions, copy-pasting context between repos, forgetting which terminal had the failing test.

firstmate flips the model. You talk to a single agent - the first mate - and it runs the crew for you: spawning autonomous agents in a visible session backend, giving each a clean git worktree, supervising them to completion, and handing you finished PRs, approved local merges, or standalone investigation reports. For larger fleets, you can opt in to persistent secondmates: second mates that are still ordinary direct reports, but run from their own isolated firstmate homes on this machine or another SSH-reachable host.

firstmate is not a model, not a harness, not a skill, not an MCP server, and not a CLI. firstmate is an agent distro for running a crew of agents. An agent distro is a portable directory of instructions, skills, tooling, policies, and state conventions that turns a general-purpose agent into a specialized one. There is no app to install: the cloned repo is the distro - AGENTS.md, bundled firstmate skills, and helper scripts that any terminal coding agent can follow. Launching a supported harness inside it for your primary session instantiates your first mate - and makes you the captain.

• One liaison - you talk only to the first mate; it dispatches, supervises, escalates only real decisions, and reports plain outcomes.
• A visible crew - every crewmate works in its own tmux window, Herdr tab, or experimental zellij tab, cmux workspace, or Orca terminal you can watch or type into; the first mate reconciles.
• Disposable worktrees - each task runs in a clean treehouse git worktree, or an Orca-managed worktree when backend=orca, so parallel work on one repo never collides.
• Two task shapes - ship tasks deliver authorized changes; scout tasks leave standalone investigation reports when the intake contract warrants separate research.
• Explicit project modes - each project ships via no-mistakes, direct-PR, or local-only, with an optional +yolo merge-autonomy flag.
• Optional secondmates - opt in to persistent second mates that run from isolated firstmate homes with their own FM_HOME, state, projects, and session lock, either locally or as a whole home on an SSH-reachable host, with guarded updates and recovery that never turns an unavailable remote route into a local replacement.
• Event-driven, zero-token supervision - a bash watcher sleeps on the fleet and wakes the first mate only when something needs you; verified primary harnesses also get a turn-end backstop that blocks or follows up on a blind stop when work is under way and supervision is not live.
• Optional Relay - opt in with one local .env pairing token so firstmate can answer your public mentions on X and Discord alike, act on normal reversible mention requests through the same lifecycle as chat requests, acknowledge spawned work, and post up to three public-safe completion follow-ups within seven days for genuine milestones and the final outcome without changing non-Relay behavior; a final reply promised in a thread becomes durable state that is reconciled from disk, so a restart or a compacted conversation cannot lose it; dry-run preview records would-be replies and dismissals locally before go-live.
• Strict project boundary - the first mate is read-only over your projects except for the narrow guarded and captain-approved operations authorized by hard rule 1, including fleet sync's guarded safe branch pruning; crewmates make every other project change behind the configured merge authority.
• Restart-proof - all state lives on disk and in the active session backend (tmux by hard default, herdr or cmux when selected or auto-detected, zellij/orca when explicitly selected); kill the session anytime and the next one reconciles, including confirmed-dead secondmate agents, and carries on.

Full detail on every feature lives in docs/architecture.md.

• A verified primary agent harness: Claude Code, Grok, Pi, pi-signed, Oh My Pi (omp), Codex, OpenCode, or Cursor Agent CLI.
• Git and the GitHub CLI, authenticated through gh auth login.
• The CLI and dependencies for your selected runtime backend; tmux is the reference default.

The first mate detects and offers to install supported missing tools after you approve. Backend-specific setup is linked in Documentation.

Claude Code, Grok, and Pi are equal co-primary recommendations for running the primary firstmate session, with pi-signed supported as Pi's distinct signed-wrapper identity. Claude Code uses a tracked Stop hook for tokenless watcher re-arm and rewake, Grok uses background-notify wake cycles, and Pi uses its tracked primary watcher extension. All three have verified turn-end guard paths when launched with their documented setup. Pick whichever one matches your subscription and workflow.

Oh My Pi (omp), a Pi fork, is verified as a primary with the same extension-owned watcher model as Pi and a stronger turn-end guard: its blocking session_stop hook compels a continuation instead of requesting one. Codex and OpenCode are also verified and supported as primary harnesses; Codex uses bounded foreground checkpoints, and OpenCode uses a TUI plugin, so both carry more harness-specific supervision tradeoffs than the three co-primaries. Cursor Agent CLI is verified as a primary too, using a tracked project-scope .cursor/hooks.json whose stop hook parks on the watcher between turns, closest in shape to Claude Code's. Launch it with --trust, or none of its project hooks load; it also has no turn-end hook in headless cursor-agent -p, so run the primary session interactively.

gh auth login
git clone https://github.com/kunchenguid/firstmate
cd firstmate

Then launch one of the co-primary harnesses; AGENTS.md takes over from there:

Claude Code

Grok

Pi

pi
# or, when the signed wrapper is installed
FM_PI_HARNESS=pi-signed pi-signed

Oh My Pi

omp
# or, when starting from inside a Claude Code pane
FM_OMP_HARNESS=omp omp

Start omp with this checkout as its working directory: it auto-discovers the tracked .omp/extensions/*.ts files with no trust dialog, and naming them with -e as well would load each twice.

For Grok, --trust is needed once per clone so project hooks and the turn-end guard load; /hooks-trust inside Grok works too. For Pi, approve the project trust prompt once per clone on first launch so the tracked .pi/extensions/*.ts files auto-load. Pi's /calm toggle hides supported transcript chrome, including canonically classified Firstmate operational user rows, and uses a Calm-only animated working boat during active runs while preserving all model context and session data. Those Calm-hidden operational inputs remain ordinary user-role messages with unchanged delivery, ordering, authority, persistence, and exports. The preference persists for the effective Firstmate home, and toggling it off restores ordinary rendering. Calm's current behavior and supported limits are separate from its version-scoped maintainer evidence. Pi's /supervision-model command pins a cheaper model and a shallower reasoning effort for the supervision branch alone, from the eligible models and thinking levels Pi itself reports, and with no pin the branch normally follows your own conversation's model and effort; see the configuration schema.

> ahoy! look at my github project xyz, then fix the flaky login test and add dark mode

# firstmate checks its toolchain (asking your consent before installing anything),
# clones the project under projects/ and spawns two isolated workers in the active backend.
# Minutes later:

  PR ready for review, captain: https://github.com/you/xyz/pull/42
  (fix flaky login test - risk: low - CI green)

> alright merge it

Setup guides for tmux (the default) and every other supported backend (herdr, zellij, Orca, cmux) are linked in Documentation below.

            you (the captain)
                  │  chat: requests, decisions, "merge it"
                  ▼
 ┌─────────────────────────────────────┐
 │ firstmate            (this repo)    │
 │ reads projects/ + firstmate routes  │
 │ writes guarded backlog/briefs/state │
 └──┬──────────────┬───────────────┬───┘
    │ backend sends / status files │
    ▼              ▼               ▼
 ┌────────┐   ┌────────┐      ┌────────┐
 │fm-task1│   │fm-task2│  ... │fm-taskN│   tmux windows, herdr/zellij tabs, cmux workspaces, or Orca terminals
 │crewmate│   │crewmate│      │crewmate│   one autonomous agent each
 └───┬────┘   └───┬────┘      └───┬────┘
     ▼            ▼               ▼
  treehouse worktree, Orca worktree, or isolated secondmate home
     │
     ├─ ship: project mode ► PR/local merge ► teardown
     │
     └─ scout: report at data/<id>/report.md ► decision inventory ► relay findings ► teardown

You chat with the first mate. It routes each request to a crewmate in its own session endpoint and git worktree, supervises the fleet with a zero-token event-driven watcher, and brings you finished PRs, approved local merges, or investigation reports. Optional secondmates extend this to persistent local or whole-home remote second mates, dispatch profiles let you steer which harness handles which task, and opt-in Relay lets the same fleet answer public mentions. codex-app is not a runtime backend yet; docs/codex-app-backend.md owns the Codex App boundary.

Full architecture - the supervision engine, worktree isolation, secondmates, dispatch profiles, project modes, optional Relay, fleet sync, and self-update - is in docs/architecture.md.

Firstmate ships these user-invocable built-in skills. Claude and grok use the slash form shown here; codex uses the same names with $, such as $afk.

Bearings invocation examples:

• /bearings returns the fresh four-section digest in chat only.
• /bearings include PRs keeps chat-only mode and opts into live PR enrichment.
• /bearings file replaces today's data/status-report-<YYYY-MM-DD>.md from scratch and links it from the four-section chat digest.
• /bearings file include PRs combines the dated report with live PR enrichment.

Agent-only reference skills live under .agents/skills/ and are loaded by firstmate at the trigger points named in AGENTS.md.

Firstmate's skills live in two separate places with different audiences:

• .agents/skills/ - agent-loaded skills (this section's table, plus firstmate's agent-only reference skills). Every one of these assumes a live firstmate home and is meaningless, or actively misleading, installed anywhere else, so each carries metadata.internal: true in its frontmatter. That flag hides them from installer discovery (tools like the skills.sh npx skills add installer) without affecting how firstmate itself loads them - frontmatter metadata is inert to the agent's own skill loader.

• skills/ - public, installer-facing skills meant to be installed standalone into any project, independent of firstmate. Each one is a self-contained skill with no dependency on firstmate's paths, tools, or vocabulary. Today that is skills/stow, a generic session-knowledge-sweep skill that routes findings by explicit instruction first, then existing local conventions, then a private .stow-notes.md fallback, and curates tiered entries through decay, local archival, and user-approved on-demand offload proposals. It intentionally shares no code with the firstmate-internal .agents/skills/stow it is named after, so the two can evolve independently.

• docs/architecture.md - maintainer architecture for the crew, supervision, worktrees, secondmates, and project modes.

• docs/configuration.md - environment variables, FM_HOME, runtime backend selection, optional Relay and its X and Discord setup steps, trusted external process-event adapter setup, the files you set, and harness support.

• docs/extension-bindings.md - maintainer architecture for the narrow trusted external process-event-adapter/1 package, binding, handshake, and evidence boundary.

• docs/remote-secondmates.md - current setup, routing, transfer, recovery, and safety behavior for whole-home remote second mates.

• docs/calm.md - current Pi /calm behavior and supported presentation limits.

• docs/voice-relay.md - the optional spoken interface: setup on both machines, measured round-trip cost, what a spoken answer may read, and what this build does not do yet.

• docs/wedge-alarm.md - configure the active alert for an away-mode escalation delivery that gets stuck.

• docs/tmux-backend.md - current setup and limits for the tmux reference backend.

• docs/herdr-backend.md - current setup, CI coverage, safety boundaries, and limits for the Herdr backend.

• docs/zellij-backend.md - current setup and limits for the experimental Zellij backend.

• docs/orca-backend.md - current setup and limits for the experimental Orca backend.

• docs/cmux-backend.md - current setup, socket security, and limits for the experimental cmux backend.

• docs/codex-app-backend.md - the current blocked Codex App backend boundary and rollout contract.

• docs/verification/runtime-backends.md - active maintainer verification for runtime backend guarantees.

• docs/gitlab-merge-watch.md - maintainer verification for watching and merging GitLab merge requests on arbitrary instances.

• docs/turnend-guard.md - the primary session's current "no turn ends blind" backstop, scope, loop safety, and compatibility limits.

• docs/verification/supervision.md - active maintainer verification for session-start, guard, continuity, and wedge integrations.

• docs/supervision-protocols/ - rendered primary-harness watcher protocols for Claude, Codex, OpenCode, Pi and pi-signed, omp, Grok, Cursor, and unknown harness fallback.

• docs/scripts.md - the bin/ toolbelt reference.

• docs/documentation-audiences.md - documentation audiences and the machine-checked placement boundary.

• AGENTS.md - the supervisor contract, role boundary, and routing index for conditional procedures.

• CONTRIBUTING.md - how to contribute, including the dev/test commands.

Contributions are welcome - see CONTRIBUTING.md for the workflow, repo conventions, and how to run the tests.

MIT - see LICENSE.