What Are Secondmates in Firstmate and How They Differ from Crewmates

Secondmates in Firstmate are persistent, isolated homes that maintain their own projects, backlog, and workers, whereas crewmates are ephemeral agents spawned for a single task and terminated immediately after completion.

Firstmate is an open-source execution framework that manages distributed work through a hierarchical agent model. Understanding the distinction between secondmates and crewmates is essential for architecting scalable deployments, as these two agent types handle fundamentally different lifecycle and isolation requirements according to the kunchenguid/firstmate source code.

Defining Secondmates and Crewmates

What Are Secondmates?

Secondmates are durable, isolated environments that function as secondary Firstmate homes. According to the architecture documentation in docs/architecture.md, a secondmate maintains its own projects/ directory tree, independent data/backlog.md, and dedicated worker processes. They are created once using bin/fm-home-seed.sh (or bin/fm-remote-home-seed.sh for remote variants) and persist across multiple task executions until explicitly torn down with bin/fm-teardown.sh.

What Are Crewmates?

Crewmates are transient execution agents designed for single-task operations. As implemented in tests/fm-turnend-guard.test.sh, crewmates are instantiated via make_crewmate_worktree_dir and exist only for the duration of a specific ship or scout operation. They share the primary home's configuration and project registry, lacking their own backlog or isolated storage.

Key Architectural Differences

The execution model distinguishes these agents across four critical dimensions:

Lifecycle Duration Secondmates follow a persistent lifecycle model defined in bin/fm-home-seed.sh and bin/fm-teardown.sh, remaining active across many routing decisions. Crewmates are spawned on-demand by bin/fm-spawn.sh (without the --secondmate flag) and automatically terminate when their assigned task completes.

Isolation Scope A secondmate owns a complete Firstmate home environment, including its own projects/ tree and data/backlog.md. This isolation allows secondmates to function as independent fleets. Crewmates operate within the primary home's workspace, directly observing the primary's wake queue without intermediate routing layers.

Supervision Model Supervision of secondmates is hierarchical: the primary home manages the secondmate's health, but the secondmate runs its own internal supervision loop. In contrast, crewmates are supervised entirely by the primary home, with their status lines absorbed directly into the primary's wake queue as ordinary events.

Status Signal Handling As verified in tests/fm-watch-triage.test.sh, secondmate status streams are treated as routed-reply channels and are never absorbed as normal crewmate status signals. This distinction ensures that the primary home can distinguish between internal task completion (crewmate) and fleet-level health reports (secondmate).

Working with Secondmates

Creating Local Secondmates

To establish a persistent local secondmate, use the seeding script. This registers the secondmate in data/secondmates.md and initializes its isolated environment:

# Create a persistent local secondmate with ID 'sm1'

bin/fm-home-seed.sh sm1

Remote Secondmate Deployment

Secondmates support remote deployment via SSH, placing a complete Firstmate home on a separate host. The primary instance retains routing and supervision control while the remote home maintains its own projects and workers as documented in docs/remote-secondmates.md:

# Seed a remote secondmate (ID: rsm) on an SSH-accessible host

bin/fm-remote-home-seed.sh rsm my-ssh-alias \
    /remote/firstmate/root /remote/secondmate/home \
    projectA=https://example.com/projectA.git projectB

Launching Tasks and Teardown

Tasks are dispatched to secondmates using the --secondmate flag with bin/fm-spawn.sh. When retiring a secondmate, use the guarded teardown script to ensure proper cleanup:

# Spawn a crewmate inside the secondmate home to execute work

bin/fm-spawn.sh sm1 --secondmate

# Gracefully retire a secondmate (local or remote)

bin/fm-teardown.sh sm1

Crewmate Execution Patterns

Crewmates are spawned for immediate task execution without persistent state. The spawn script creates these ephemeral agents within the primary home's context:

# Spawn a standard crewmate for a single task

bin/fm-spawn.sh -- crewmate-task-id

Unlike secondmates, crewmates created via bin/fm-spawn.sh without the --secondmate flag cannot be targeted for remote execution and do not require explicit teardown, as they terminate automatically upon task completion.

Summary

• Secondmates are persistent, isolated Firstmate homes defined in docs/remote-secondmates.md that maintain their own projects/ directories, data/backlog.md, and worker fleets across multiple task cycles.
• Crewmates are ephemeral agents created by bin/fm-spawn.sh for single-task execution, sharing the primary home's configuration and terminating automatically after completion.
• Secondmates support both local and remote deployment via bin/fm-home-seed.sh and bin/fm-remote-home-seed.sh, while crewmates execute only within their target home environment.
• Status signals from secondmates are routed separately from crewmate events, as enforced by the supervision logic in tests/fm-watch-triage.test.sh.

Frequently Asked Questions

Can a secondmate run on a different host than the primary Firstmate instance?

Yes. Secondmates support remote deployment through bin/fm-remote-home-seed.sh, which provisions a complete Firstmate home on an SSH-reachable host. The primary instance maintains routing and supervision responsibilities while the remote secondmate retains its own isolated projects, backlog, and workers.

Why would I use a secondmate instead of a regular crewmate?

Use a secondmate when you need persistent isolation for long-running projects or distributed fleets. Secondmates maintain state across tasks via their own data/backlog.md and projects/ tree, making them suitable for secondary fleets. Crewmates are appropriate for short-lived, stateless tasks that do not require persistent storage or cross-task continuity.

How does Firstmate prevent secondmate status signals from interfering with crewmate supervision?

The supervision layer treats secondmate status streams as routed-reply channels rather than ordinary wake events. As tested in tests/fm-watch-triage.test.sh, the classification logic explicitly prevents absorption of secondmate status signals into the primary crewmate supervision queue, ensuring clean separation between fleet-level health reports and task-level status updates.

Do crewmates require manual teardown like secondmates?

No. Crewmates are ephemeral by design and terminate automatically upon task completion. Secondmates require explicit retirement via bin/fm-teardown.sh because they persist as autonomous homes with their own supervision loops and state management.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}