The first mate drives these; interactive entrypoints work by hand too, while *-lib.sh files are sourced helpers.
Each file also starts with a short header comment.
| Script | Description |
|---|---|
fm-bootstrap.sh |
Detect required toolchain and version problems, optional capability facts, primary-checkout TANGLE: problems, and actionable clone refresh outcomes; refresh project clones best-effort; locally sync live secondmate homes; set up opt-in X mode; install tools only after consent |
fm-fleet-sync.sh |
Fetch clones, fast-forward safe default-branch states, self-heal clean detached ancestor drift, report unsafe drift as STUCK:, and safely prune branches whose remote is gone |
fm-update.sh |
Self-update the running firstmate repo and registered secondmate homes with fast-forward-only pulls from origin |
fm-backlog-handoff.sh |
Move already-judged in-scope queued backlog items from the main home into a seeded secondmate home |
fm-backlog-audit.sh |
Read-only audit for backlog/state drift between data/backlog.md, state/*.meta, and local adoption signals |
fm-brief.sh |
Scaffold a ship brief with a worktree-isolation assertion, a report-only scout brief with --scout, or a secondmate charter with --secondmate |
fm-cognee-lookup-gate.sh |
Fail-closed local evidence gate for Cognee lookup modes; automatic lookup is disabled by default and manual verified lookup remains hint-only |
fm-ensure-agents-md.sh |
Ensure project AGENTS.md is the real memory file and CLAUDE.md symlinks to it |
fm-guard.sh |
Warn when the primary checkout is tangled, when queued wakes are pending, or when watcher liveness is not proved by a fresh beacon plus a live matching lock |
fm-home-seed.sh |
Lease/provision a secondmate home transactionally, clone projects, initialize gates, and maintain data/secondmates.md |
fm-memory-lookup.sh |
Manual read-only Cognee memory lookup for optional pre-dispatch hints; opens local source paths before brief attachment and stays non-blocking when unavailable |
fm-spawn.sh |
Spawn one task, several id=repo pairs, or a persistent secondmate with --secondmate; ship/scout spawns require an isolated treehouse worktree; secondmate spawns locally sync the home before launch |
fm-project-mode.sh |
Resolve a project's delivery mode and +yolo flag from data/projects.md |
fm-route.sh |
Classify a task into a deterministic route profile, harness, model, effort, reason, override, and risk flags without changing spawn behavior |
fm-merge-local.sh |
Fast-forward a local-only project's local default branch after approval |
fm-review-diff.sh |
Review a crewmate branch against the authoritative base, with optional --stat output |
fm-cognee-lookup.sh |
Read-only Cognee lookup wrapper with dry-run fixtures and guarded live POST /api/v1/search; treats answers as hints and delegates source proof to local manifest/source verification |
fm-cognee-manifest-check.sh |
Validate TSV Cognee manifest rows and verify SOURCE_ID, SOURCE_PATH, or SEED_FILE answer references against reopened local files |
fm-marker-lib.sh |
Shared from-firstmate request marker and detector sourced by fm-send.sh, fm-brief.sh, and tests |
fm-watch-arm.sh |
Verified per-home watcher re-arm; reports started, healthy, or FAILED; --restart relaunches only this home's watcher |
fm-watch-session.sh |
Durable home-scoped tmux runner that loops through fm-watch-arm.sh for harness lanes without reliable tracked background tasks |
fm-watch.sh |
Singleton-safe always-on watcher; absorbs benign wakes in bash, queues and exits only for actionable wakes, and reverts to daemon-owned one-shot behavior while state/.afk exists |
fm-supervise-daemon.sh |
Presence-gated sub-supervisor for walk-away (/afk) supervision: wraps fm-watch.sh, uses the shared wake classifier, self-handles routine wakes in bash, and escalates only captain-relevant events as one verified, batched, single-line digest prefixed with a sentinel marker |
fm-crew-state.sh |
Print one stable current-state line for a crew by reconciling its matching no-mistakes run-step, even when the pane has closed, with pane and status-log fallback |
fm-tangle-lib.sh |
Shared default-branch resolution and primary-checkout tangle classification sourced by bootstrap and guard |
fm-ff-lib.sh |
Shared guarded fast-forward helper for /updatefirstmate origin pulls and no-fetch local secondmate syncs |
fm-tasks-axi-lib.sh |
Shared tasks-axi compatibility probe sourced by bootstrap and teardown |
fm-wake-drain.sh |
Atomically drain queued watcher wakes before handling supervision work, then run the watcher-liveness guard |
fm-wake-lib.sh |
Shared durable wake queue and portable lock helpers sourced by the watcher, drain, arm, guard, and daemon |
fm-classify-lib.sh |
Shared captain-relevant wake classifier sourced by the watcher and sub-supervisor daemon |
fm-send.sh |
Send one verified literal line (or --key Escape) to a direct-report window; exits non-zero on confirmed swallowed Enter; bare kind=secondmate targets are marked as from-firstmate; slash commands and codex $... skill invocations get popup-settle before Enter; text sends pause FM_SEND_SETTLE seconds after success |
fm-tmux-lib.sh |
Shared tmux pane primitives for busy detection, dim-ghost-aware and border-aware composer detection, and verified submit retry |
fm-peek.sh |
Print a bounded tail of a crewmate pane |
fm-pr-check.sh |
Record pr= and a verified pr_head= when available for a PR-ready task, then arm the watcher's merge poll |
fm-promote.sh |
Promote a scout task in place so it becomes a protected ship task |
fm-teardown.sh |
Return a clean, landed ship worktree or retire/release a secondmate home; requires scout reports, checks child work, and prints the backlog reminder |
fm-harness.sh |
Detect the running harness; resolve the effective crewmate harness |
fm-lock.sh |
Per-home firstmate session lock |
fm-x-lib.sh |
Shared X-mode .env, alternate env-file, relay, dry-run config, and reply-thread splitting helpers sourced by the poll and reply clients |
fm-x-poll.sh |
Do one bounded X relay poll; without FMX_PAIRING_TOKEN it is silent, with a pending mention it stashes the full inbox JSON, including in_reply_to, and prints x-mention <request_id> |
fm-x-reply.sh |
Post or dry-run preview a composed public-safe X reply, auto-splitting long text into {request_id,text,texts} threads; reads text from an argument, stdin, or --text-file |