Configuration & state files
Every config/ file, the key data/ and state/ files, .env, and the environment variables worth knowing — with defaults and whether secondmates inherit them.
docs/configuration.md (about 2,400 lines) is the authoritative owner of layout and schemas. This page indexes the parts you are likely to touch. All of config/, data/, state/, projects/ and .env are local and gitignored.
config/ — your operating choices#
Each file is tiny, often one word. Absent means default.
| File | Purpose | Default (absent) | Inherited by secondmates |
|---|---|---|---|
backend |
tmux / herdr / zellij / orca / cmux |
auto-detect, then tmux | yes |
crew-harness |
harness for crewmates | first mate's own | yes (literal file) |
crew-dispatch.json |
natural-language dispatch rules (Scaling) | none | yes |
secondmate-harness |
<harness> [<model>] [<effort>] for secondmate launches |
crew-harness → own | no |
claude-permission-mode |
bypass or auto |
bypass (--dangerously-skip-permissions) |
yes |
claude-account, pi-account |
pin worker logins | ambient login | no |
backlog-backend |
manual to hand-edit the backlog |
tasks-axi |
yes |
brief-include.md |
standing text appended to every brief | none | no |
calm |
on / off |
off |
no |
supervision-branch-model, supervision-branch-effort |
Pi supervision-branch pins (/supervision-model) |
follow main | no |
supervision-host |
headless supervision beside non-Pi primaries; off opts any home out |
on for a Claude primary; off for Cursor, OpenCode, omp, Grok, Codex | no |
keep-ai-trailers |
presence flag → keep AI co-author trailers in fleet commits | off (trailers stripped) | yes |
startup-memory-budget |
token budget for captain/learnings memory | 7500 | yes |
stow-pass-horizon |
opt into pass-count memory decay | wall-clock only | no |
wedge-alarm |
away-mode alert channels: off, auto, osascript, herdr, command:<cmd> |
auto (macOS notification) |
— |
fleet-ledger |
presence flag → state/fleet-ledger.jsonl |
off | no |
herdr-presentation-spaces |
on / off for one workspace per task |
on for Herdr ≥0.8.0 | yes |
trace-context |
W3C trace-context to workers | off | yes |
turnend-churn-absorb |
pane churn counts as activity | off | no |
wedge-defer-parked-gate |
defer wedge alarm at the first mate's own gate | off | no |
watched-tools.json |
tools to watch for updates | not armed | no |
launch-env-allowlist |
env names passed to workers ("not a sandbox") | unfiltered | — |
lavish-axi-host |
per-machine Lavish server address | ambient | yes |
cmux-socket-password |
cmux control-socket password | CMUX_SOCKET_PASSWORD |
— |
x-mode.env |
generated Relay watcher cadence | — | — |
"—" means the doc doesn't state inheritance for that file. When inheritance matters, check the row for that file in the on-demand operational-home-layout skill (.agents/skills/operational-home-layout/SKILL.md), which moved out of AGENTS.md in September 2026.
.env#
| Key | Enables |
|---|---|
FMX_PAIRING_TOKEN (+ FMX_RELAY_URL, FMX_DRY_RUN) |
Relay |
TYPESAFE_API_KEY |
typed dispatch resolution (Jev) |
FM_MAIL_USER, FM_MAIL_PASS, FM_IMAP_HOST/PORT, FM_SMTP_HOST/PORT |
mail plane |
Tracked config#
| File | What |
|---|---|
.tasks.toml |
tasks-axi backend config: data/backlog.md, done_keep = 10, archive data/done-archive.md |
.no-mistakes.yaml |
this repo's own gate: commands.lint: bin/fm-lint.sh, evidence on orphan branch no-mistakes/evidence |
.claude/settings.json, .pi/extensions/, .omp/extensions/, .cursor/hooks.json, .codex/hooks.json, .opencode/plugins/, .grok/hooks/ |
harness integration (Harnesses) |
data/ — durable records#
| File | What | Who writes |
|---|---|---|
backlog.md |
the task queue: In flight / Queued / Done, dependencies, holds | tasks-axi (via the first mate) |
projects.md |
project registry: mode, yolo, branch prefix, forge | first mate (project-management) |
secondmates.md |
local and remote routing table | secondmate seed helpers |
captain.md |
your preferences and working style | first mate, inspect-then-update; curated by /stow |
captain-shared.md |
preferences propagated read-only to secondmates | primary only |
learnings.md |
fleet gotchas: dated, evidence-backed, pruned | first mate / /stow |
memory-archive.md |
cold tier for expired memory | /stow |
<id>/brief.md, <id>/report.md |
task contract; scout deliverable | fm-brief.sh; the worker |
status-report-<date>.md |
/bearings file output |
/bearings |
Edit captain.md yourself
data/captain.md is the right place for durable preferences ("always squash", "never touch the payments module without asking", "prefer codex for Rust"). The first mate reads it at every session start. /stow keeps it pruned.
state/ — runtime#
| Path | What |
|---|---|
.lock, .lock-session |
per-home session lock |
.wake-queue |
durable actionable wakes |
.last-watcher-beat, .watch-triage.log, .watch-cycle-exits.log, .watcher-down |
watcher health |
.afk, .afk-contract, .subsuper-* |
away and quiet posture |
.lease-<task> |
main/branch actor lease |
<id>.status, <id>.meta, <id>.inbox/, <id>.busy-state |
per task (Briefs & status) |
fleet-ledger.jsonl |
opt-in ledger |
public-followup/, x-outbox/ |
Relay promises; dry-run outbox |
reconcile-requests/ |
board "reconcile" requests |
Environment variables worth knowing#
| Var | Default | What |
|---|---|---|
FM_HOME |
repo root | which home to operate on; fm-send.sh requires it explicitly |
FM_BACKEND |
— | backend override for new spawns |
FM_POLL |
15 | watcher cycle, seconds |
FM_HEARTBEAT / FM_HEARTBEAT_MAX |
600 / 7200 | backstop cadence |
FM_STALE_ESCALATE_SECS |
240 | idle-without-proof threshold |
FM_BUSY_TURN_MAX_SECS |
3600 | max single busy turn |
FM_PAUSE_RESURFACE_SECS |
14400 | recheck for paused / captain-held |
FM_WEDGE_DEMAND_INSPECT_COUNT |
3 | stale wakes before a deep inspection |
FM_MAX_DEFER_SECS |
300 | away-mode injection defer before the wedge alarm |
FM_CODEX_WATCH_CHECKPOINT |
180 | Codex foreground checkpoint |
FM_SNAPSHOT_UNDATED_HOLD_AGE_DAYS |
14 | hold becomes aged |
FM_FLEET_PRUNE |
1 | prune merged branches in clones |
FM_BOOTSTRAP_DETECT_ONLY |
— | 1 = read-only bootstrap |
FM_ZELLIJ_SESSION |
firstmate |
Zellij session name |
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS |
— | 1 enables /calm on Claude Code (you set it) |
Two things are set on every worker launch automatically:
COMPACT_ADVISER_DISABLE=1(no knob)- Claude attribution cleared (
attribution:{commit:"",pr:"",sessionUrl:false}), Devin attribution off, plus a per-task hooks path that strips AI commit trailers.
Firstmate never adds an agent as a co-author. The one knob is config/keep-ai-trailers: with that presence flag set, the attribution-off settings and the strip hooks are skipped, and each harness's own attribution applies (Devin's user-config setting, which defaults to on). The flag is local and gitignored, and secondmate homes inherit it.