kunchenguid/firstmate

Talk to one agent. Ship with a crew

Summary

firstmate is a repository-based “agent distro”—not a model, CLI, or harness—that lets one primary coding-agent session coordinate a crew of autonomous workers. It routes work into isolated Git worktrees, supervises visible sessions, and returns pull requests, locally approved merges, or investigation reports.

What it is useful for

It is useful when several project tasks can proceed at once—for example, one worker can investigate a flaky login test while another adds dark mode. Each crewmate runs in its own visible tmux window by default, or in another supported session backend, and each ship task receives a clean worktree to avoid collisions between parallel changes.

The first mate acts as a liaison: it dispatches work, supervises progress, and brings back decisions that need the captain. Ship tasks can deliver changes through a pull request or an approved local merge, depending on project policy. Scout tasks produce standalone investigation reports instead of changing the project.

Projects can select modes such as no-mistakes, direct-PR, or local-only, with separately documented options for merge autonomy, branch prefixes, Gerrit publishing, and manual PR preparation. State is kept on disk and in the active session backend so sessions can reconcile after restarts. An event-driven watcher wakes the primary agent when supervision or a decision is needed.

Optional secondmates run from isolated homes locally or on an SSH-reachable host. Relay is also opt-in and can handle public mentions through X or Discord. These are additions to the core workflow rather than requirements.

How engineers can use it

You need Git, an authenticated GitHub CLI, a supported primary harness—such as Claude Code, Grok, Pi, Codex, OpenCode, Cursor Agent CLI, or Antigravity CLI—and the dependencies for a runtime backend. The documented starting sequence is:

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

Launch a harness from that checkout, for example:

claude
grok --trust
pi

AGENTS.md then provides the operating instructions. A typical request looks like:

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

Firstmate checks its toolchain, asking consent before installing or upgrading anything, then assigns isolated workers and reports the resulting PR for review.

tmux is the reference backend; other backends have different maturity levels and require their documented setup. Cursor additionally needs --trust and must run interactively because its headless mode lacks the turn-end hook. The Codex App is explicitly not yet a runtime backend. See the README’s linked backend documentation before choosing a non-default environment.