firstmate

firstmate is an open-source "agent distro" created by Kun Chen (kunchenguid) that solves the problem of managing multiple parallel coding agent sessions. Instead of tab-juggling between terminals and copy-pasting context between repos, you talk to a single coordinating agent — the first mate — which dispatches work to a crew of autonomous agents, supervises them, and hands you finished PRs, local merges, or investigation reports. The project is MIT-licensed, hosted on GitHub, and requires no app installation: the cloned repository itself is the distro.

What It Is

firstmate is not a model, not a harness, not a skill registry, and not an MCP server. It is a portable directory of instructions, skills, tooling, policies, and state conventions — an "agent distro" — that turns a general-purpose coding agent into a specialized crew coordinator. Launching a supported harness (Claude Code, Grok, Pi, Codex, or OpenCode) inside the cloned repo instantiates the first mate and makes the user the captain. The repo's AGENTS.md file serves as the always-loaded operating contract and routing index.

How the Crew Architecture Works

The core model is a single liaison pattern:

• You (the captain) chat only with the first mate via natural language requests and decisions.
• The first mate reads project state, routes tasks to crewmates, supervises the fleet with a zero-token event-driven bash watcher, and escalates only real decisions.
• Crewmates each run in their own tmux window, herdr/zellij tab, cmux workspace, or Orca terminal, with a clean git worktree (via the companion treehouse tool) so parallel work on one repo never collides.
• Two task shapes exist: "ship" tasks deliver authorized changes (PRs or local merges), and "scout" tasks produce standalone investigation reports.
• Optional secondmates extend the model to persistent local or SSH-reachable remote second mates with their own isolated firstmate homes, state, and session locks.

Supported Harnesses and Backends

firstmate designates Claude Code, Grok, and Pi as equal co-primary harness recommendations, each with verified turn-end guard paths. Codex and OpenCode are also verified and supported with harness-specific supervision tradeoffs. Runtime session backends include tmux (the reference default), herdr, zellij, Orca, and cmux — each with dedicated setup documentation. The first mate detects and offers to install supported missing tools after user approval.

Built-in Skills and Supervision

The distro ships several user-invocable skills accessible via slash commands (or $ prefix in Codex):

• /afk — away-mode supervision with batched digest escalation
• /ahoy — recap of visible session events since the last captain message
• /bearings — a four-section fleet status digest, optionally written to a dated file with live PR enrichment
• /updatefirstmate — self-update the running firstmate and its secondmates
• /stow — sweep the session for uncaptured durable knowledge and route findings to disk

Supervision is event-driven and zero-token: a bash watcher sleeps on the fleet and wakes the first mate only when something needs attention. All state lives on disk and in the active session backend, making the system restart-proof — killing the session and relaunching reconciles confirmed-dead agents and carries on.

Optional Relay and Public Mention Handling

An opt-in Relay feature, enabled with a single local .env pairing token, allows the first mate to answer public mentions on X (Twitter) and Discord, act on normal reversible mention requests through the same task lifecycle as chat requests, and post up to three public-safe completion follow-ups within seven days for genuine milestones. Final replies promised in a thread become durable disk state so a restart or compacted conversation cannot lose them. A dry-run preview mode records would-be replies locally before go-live.

Current Status and Adoption Signal

The repository was created in June 2026 and, according to GitHub metadata, has accumulated approximately 2,955 stars and 954 forks with 657 open issues as of early August 2026, indicating rapid early traction. The project is actively maintained under the MIT license by Kun Chen, with the last push recorded on August 7, 2026. Documentation covers architecture, configuration, remote secondmates, each runtime backend, supervision protocols per harness, and a contributing guide with dev/test commands.