Under the hood · 61 claims
The coding-agent community has spent a year working out how to get real output from Claude Code. Write your CLAUDE.md properly. Keep a second model to check the first. Never let an agent grade its own work. Isolate parallel work in git worktrees. Keep your docs current. Don't trust a green build.
That body of practice is real, and it is almost entirely unenforced. It lives in threads, talks, and a discipline you have to remember at 2am.
Verified 2026-07-29 against ~/fleet-desktop on main (HEAD 61878292). Paths are relative to app/core/src/ unless stated.
Fleet does these as architecture. Not as advice inside a prompt, but as code paths that run whether or not the person using it has ever heard of the practice.
Below is the list, verified against the source. Every section ends with the working notes that map its items to the code that proves them.
Claims 1-10
1
Every worker has to hand back a proof: a command to run, or a file that must exist and be non-empty. Fleet re-runs the command in the worker's own directory and reads the exit code. The worker's claim that it worked is not part of the decision.
2
The proof gate re-executes; it never reads a self-report. This is the "judge is not the generator" rule from the multi-agent threads, wired in as the only path to Done.
3
No proof attached, a command that errors, a file that is missing or empty, a check that could not be run at all: all of these fail. There is no branch where an unavailable check counts as a passed check.
4
When a session ends its turn with no passing proof, Fleet marks it still working, not complete. The old and very common failure mode, treating idle as done, is closed by construction.
5
Fleet parses the real per-target test summaries instead of reading the last line or the exit code. A test target that ignores your filter, prints its own "ok", and exits 0 has fooled a lot of people. It does not fool this.
6
Pass attaches the proof. Fail re-dispatches with what specifically went wrong. After a set number of rounds it escalates loudly to you. There is no path where it loops forever.
7
After several identical failures the re-dispatch becomes a pivot: discard the non-converging approach and try a fundamentally different one. The pivot spends one of the existing attempts, so it cannot extend the budget.
8
For design work, a proof that is just "the screenshot file exists" would pass an ugly page and a good one identically. Fleet routes the render to an adversarial critic on a different model lineage, scored against a bundled anti-slop checklist. A slop verdict blocks Done and re-briefs the builder.
9
The critic needs either a Gemini key or the codex CLI on the machine. Missing one is announced, not absorbed. A machine that had a critic configured and lost it escalates like any other broken check.
10
A 46-rule anti-slop linter catches the cheap failures (overused fonts, gray on color, pure black, bounce easing) for free. It can only fail fast or defer, never pass, so a broken linter cannot approve anything. It runs for workers in their own git worktree, where Fleet can prove which files that worker actually wrote.
What proves claims 1-10
Proof gate, judge is not generator, fail-closed, idle is not done
proof.rs module header + run_check; socket.rs run_turn_end_gate / settle_unproven_turn; CLAUDE.md "Done-signal is PROOF-gated, not idle-gated"
Test verdict that cannot lie
verdict.rs header, rules 1-6 (issue #178: harness = false target ignoring the filter)
Bounded re-dispatch and the pivot
done_loop.rs header, max_loops default 3, DoneLoopOutcome::Exhausted, K-identical-failures pivot
Taste gate, critic absence announced
taste_gate.rs header; Critic::{Gemini,Codex,Unavailable}, CriticAbsence, resolve at taste_gate.rs:517-590; enforcement wired at socket.rs:4490 via crate::taste_gate_plan
Deterministic pre-gate
detector.rs header (impeccable 3.2.1, 46 rules, Detected::Inconclusive can never become Clean); scope limited to SpawnOptions::worktree workers, stated in the header
Claims 11-17
11
Parallel agents in one checkout overwrite each other. Fleet gives each worker a real git worktree on a fresh branch, so five workers on one repo never collide. If you ask for isolation against something that is not a real git tree, the spawn fails loudly instead of silently falling back.
12
The work stays reviewable after the worker is gone.
13
Push its own branch, open a draft PR through gh, put the proof verdict in the body, and stamp the URL on the record. A worker that died with commits gets one too, marked unverified, because that is when the artifact matters most.
14
Both are refused in code and asserted by tests on the argument list. Missing preconditions (no remote, no GitHub origin, gh not authenticated, nothing to push) skip before the first remote write and never block the proof verdict.
15
Recovery checkpoints the worktree first. A checkpoint that cannot commit escalates instead of killing. Work is never traded for tidiness.
16
git stash is per worktree, which git does not give you by default.All worktrees of a repo share one global stash stack, so two workers stashing in their own directories silently eat each other's saved work. Fleet pins each stash under a per-worktree ref that git isolates automatically, and refuses to reap a worktree whose stash is still pinned.
17
Fleet clones the base repo's build directories using APFS copy-on-write. Cloning a 13 GB cache took under 10 seconds and 80 MB of real disk. The alternative, one shared cache, serializes every worker behind a build lock, which defeats the point of running them in parallel.
What proves claims 11-17
Worktree per worker, kill keeps branch
worktree.rs header; add/remove; WorktreeError hard-fails a non-git base
Draft PR on finish, never main, never force
draft_pr.rs header + safety contract; argv unit tests on the GitRun seam; fires from CoreCtx::maybe_draft_pr
Checkpoint before stop
freeze.rs layer 3 checkpoint_commit; reaper.rs orchestration note
Per-worktree stash
stash.rs header (refs/worktree/fleet-stash, never refs/stash); removal refusal on a pinned ref
APFS build-cache clone
cache_seed.rs header, measured numbers (13 GB clone in 9.8s / 80 MB; ~2.0 GB divergence)
Claims 18-28
18
Claude Code fires a hook when it would show a permission dialog. Fleet parks that hook open, shows you a card, and prints your decision straight back down the still-open connection. No screen scraping, no typing "y" into a terminal, no polling.
19
Ask about everything, supervised, auto, full, or full-Claude-auto. It decides how the ambiguous middle is handled: raise a card, hand it to Claude's own classifier, or run it.
20
Force-push, recursive force-delete, dropping or truncating a table, a production deploy, and killing a process always raise a card. The dial cannot lift that floor and neither can a toggle. A stray pkill claude would kill the orchestrator itself.
21
Risk classification scans a quote-stripped copy to avoid false alarms on quoted file paths, but the catastrophic check runs against the raw string. psql -c 'drop table users' is stamped catastrophic.
22
On the supervised setting the ambiguous middle raises a card rather than trusting an automatic classifier. Safe actions still run, so a 3am job makes progress, and the judgment calls are waiting for you in the morning.
23
Repeated denials of the same class are treated as a signal. First the worker gets a nudge telling it the lane is closed. If it hammers the same class again with no productive progress in between, it is paused with one card offering release or stop, and further requests of that class are auto-denied without new cards. This came from a real incident where a worker responded to four correct denials with four cleverer disguises of the same read.
24
The remembered rule is scoped to one worker and one tool, and the never-lane is excluded by invariant.
25
A worker's approval request also reaches the orchestrator, which presents it through Claude's native question tool so remote control renders a real Approve/Deny. It relays your answer. It cannot fabricate one, and the catastrophic floor refuses remote approval outright. Deny is always allowed.
26
Credentials go from a native input field to the macOS Keychain and are injected into a worker's process environment at spawn. The model sees the key name and a masked preview. The value is never in a settings file, an event, a database row, or a transcript, and a Keychain write failure is an error, never a silent plaintext fallback.
27
The imported-cookie type is deliberately not serializable, so it cannot ride an event or a socket even by accident, and its debug output prints [redacted]. What you and the model see is a count and a hostname. Scope is the one site you are signed in to, never the whole jar.
28
The control socket requires a per-session token plus a peer-credential ancestry check. An indeterminate check is refused. Deny-only commands are always allowed. A worker cannot even read the token, because reads of it are gated by the classifier.
What proves claims 18-28
Hooks to inbox, click is the return value
inbox.rs header (one-shot channel keyed by card_id, decision printed back down the open hook connection); .claude-docs/hooks-inbox.md
Five autonomy levels
prefs.rs:61-101 AutonomyLevel, DEFAULT = Auto
Catastrophic and process-kill floor, raw-command stamping, supervised fails closed
socket.rs:3088-3135 the ordered routing contract, route_pre_tool_use; classify.rs:2941 is_catastrophic, RE_CATASTROPHIC, RE_PROD_DEPLOY; contract test four_autonomy_levels_route_each_lane_correctly
Deny-loop circuit breaker
breaker.rs header, the 2026-07-11 incident, BENCH_STRIKES, note_nudge_delivered, note_progress, is_benched
Session allow rules exclude the never-lane
allow.rs header, three fail-closed invariants, scope (worker, tool)
Remote approval relays a real tap
socket.rs:501-525 + inbox.rs decide_via_ctl (HotZoneRefused); prefs.rs RemoteApprovalPolicy; socket.rs:1573 refusal string
Secret value never reaches the model
secrets.rs header, three invariants; mask, env_for_spawn; SpawnSpec non-Serialize with hand-written redacting Debug (driver.rs)
Cookie import redaction
browser_session.rs header; ImportedCookie not Serialize, Debug prints [redacted]; cookie_host_matches
Control-socket token plus ancestry
socket.rs:1557-1891; util.rs:85-123; classify.rs:57-70 read-gates ctl-token
Claims 29-39
29
No external CLI is required, so this works on a shipped app. A missing scorer, missing python, a non-zero exit, unparseable output, or a timeout all count as gate failed. There is no silent pass.
30
One per wave, only when there is real work (a failed gate, stale facts, or new gotchas to fold in). The scribe edits the docs; the supervisor does not. The scribe is deliberately not marked as orchestrator-spawned so it cannot re-trigger the pipeline and loop.
31
On first contact with a project that has no passing CLAUDE.md, Fleet generates one from the build brief, with the behavioral rules, a currency clause, and a gotchas section. Missing means create. Weak means upgrade. Present but unscorable means leave the human's file alone.
32
Fleet queries npm, PyPI, and crates.io, caches each fact with its source URL and fetch date, and expires it after seven days. A failed lookup is never stamped with today's date, so a network outage cannot mint a fact that looks fresh.
33
A lint pass finds three things: a claim in CLAUDE.md that disagrees with a reference doc, a reference doc nothing links to (so no agent will ever load it), and the same versioned fact stated two different ways in two places. Findings quote both sides so the fixer can tell which is right.
34
Search rediscovers. A compiled page compounds. The wiki is merged conservatively, pages only grow, and nothing here deletes knowledge.
35
Failures are fingerprinted, grouped, and once the same failure mode has hit enough distinct workers it is compiled into a wiki rule so the next worker does not walk into it.
36
Roughly two gigabytes of past conversation on a typical machine, searched with ripgrep and a JSON parse. No API call, no model, no billing. Snippets are secret-redacted, results are capped, and a missing ripgrep is reported as unavailable rather than as zero results.
37
A deterministic digest of recent work, promises, and open items is generated from files and in-memory state and injected into the new session's prompt. Zero tokens to produce, secret-stripped, byte-capped, and it fails to empty rather than blocking the launch.
38
A card that expires, or that dies with the app, used to vanish along with the question. Now registration writes a ledger row that terminalizes on resolution. The ledger is explicitly not an approval channel: resolving a row changes only the record.
39
Spawned, verified, failed, pivoted, killed, errored, settled, recovered. Append-only, best-effort, and it can never block a state transition. This is the raw material everything above learns from.
What proves claims 29-39
Bundled CLAUDE.md scorer, scribe on real drift
memory_hygiene.rs header steps 1-4; AUDIT_PASS_FLOOR; run_audit_docs; scribe not spawned_by_captain
Repo readiness bootstrap
readiness.rs header; missing/create, weak/upgrade, unscorable/leave alone; readiness table
Currency engine
currency.rs header; 7-day TTL, provenance, fail-closed never today-stamps a failed lookup
Doc lint
doc_lint.rs header, three checks, both sides quoted, advisory into the scribe path; wired at memory_hygiene.rs:1053
Cross-project wiki
wiki.rs header; write path memory_hygiene.rs:911-963; read path wiki::read_wiki_notes at bootstrap (lib.rs:11569, timeboxed by BOOTSTRAP_RECALL_TIMEOUT)
Failure mining
memory_hygiene.rs:731-812, 943-962; done_loop::failure_fingerprint; fingerprint sentinel 0 ignored
Zero-token transcript search
transcript.rs header; ripgrep plus JSON parse, MAX_SCAN, redact_secrets, rg_available:false distinct from zero hits
Handoff digest
handoff.rs header; rides --append-system-prompt-file; deterministic, secret-stripped, MAX_DIGEST_BYTES, fail-open
Needs-you ledger
backlog.rs header; ledger id {card_id}@{registered_at}; explicitly not an approval channel
Outcomes log
outcomes.rs header; append-only JSONL, event list, done retired, never blocks a transition
Claims 40-51
40
A timer inside the app classifies statuses, hashes each worker's screen to detect a stall, drives the verification loops, and routes escalations. No model is involved in any of it.
41
Every risky condition it finds becomes a message for a human, with a cooldown so a persistent condition alerts once instead of every beat. There are a handful of narrow autonomous stops, each individually gated, and the two recovery paths both commit the worker's work before stopping it.
42
A sampler walks each worker's process tree and reports sustained CPU or resident-memory breaches. A test asserts the kill count is zero.
43
Admission control checks free memory, free disk, and CPU before launching, and queues the worker as Queued until there is headroom, draining oldest-first. It never evicts or pauses anything already running, and it fails open: before the first real sample, or with the guard off, everything launches as before.
44
Three conditions must all hold: its stop hook fired, its output has been quiet past a dwell, and nothing is in flight for it. Then Fleet checks the worktree for fresh commits and file changes. Fresh or unknown means not frozen, and the timer resets. Only a genuinely dead worker is checkpointed, stopped, and re-dispatched once.
45
A separate narrow reaper stops a worker only when its deliverable is independently verified as landed. Any ambiguity, any failed probe, and it leaves the worker exactly as it found it.
46
A public status page fetch on the existing supervisor beat, keyed on component status rather than on whether an incident exists, because incidents routinely list components that are still operational. One warning per incident, then auto-resume on recovery. A failed or unparseable fetch is never treated as an outage.
47
Claude Code fires a different hook when a turn ends in failure. Rate limits and overloads become a rate-limited state that inherits the auto-resume above. Everything else becomes idle with a plain reason, never a terminal error, and a settled worker is never overwritten.
48
Recent Claude Code versions report a session parked on a dialog. Fleet polls that and prefers it over its own heuristics, correlating by process ancestry rather than working directory, because two workers in one directory would otherwise credit each other's state.
49
Pasting a task into a busy terminal can leave it staged as "[Pasted text #1]", unsent, until a watchdog kills the worker for doing nothing. Fleet waits for the terminal to visibly reflect the paste, sends Enter, then checks the fresh output and sends Enter again if it did not submit. A hard failure becomes a typed event, not silence.
50
Stale sandbox directories, crash-orphaned worktrees, per-worker codex homes, orphaned pipe processes, inert database rows, staged clipboard images. It never touches a live session or a protected worker, enforces path containment twice, re-validates a process id immediately before signaling it, and any failed check produces an empty plan rather than a guess. It also reclaims stray worktrees elsewhere on disk (13 GB on one machine, 142 GB on another), and git worktree lock is a permanent opt-out.
51
One misread beat should not announce that a wave finished. Quiescence requires consecutive idle beats spanning a minimum wall-clock span with no recent dispatch.
What proves claims 40-51
Supervisor beat, never auto-kills
supervisor.rs header; policy.rs header plus the "never kills" assertions at policy.rs:327, 393
Resource sampler never kills
supervisor.rs:1085; policy::evaluate_resources; lib.rs:20491 asserts kill count zero
Admission control
admission.rs header, design invariants; prefs.rs:320-331 guard defaults ON; drain test lib.rs:20450
Freeze detection
freeze.rs header, three layers, settle_state, artifacts_fresh fail-open, respawn-once latch
Post-completion reaper
reaper.rs header; verify_landed; leaves the worker untouched on any ambiguity
Service-status monitor
status.rs header; component status not incident presence; fail-safe on a bad fetch; auto-resume sends only "continue"
`StopFailure` routing
settings.rs registration; socket.rs routing; turn.rs latch; .claude-docs/hooks-inbox.md StopFailure section
Native needs-input probe
agents_probe.rs header, live-verified JSON shape on CLI 2.1.214, PID-ancestry correlation, fails to Unknown
Submit gate
submit_gate.rs header; paste-settle then Enter-verify with bounded retry; forensics in shots/task-not-received-*.txt
Autonomous gc
gc.rs header (six cruft kinds); prefs.rs:210 auto_gc_enabled default true; stray-worktree reclaim and the git worktree lock opt-out per CLAUDE.md and PR #176
Quiescence dwell
quiescence.rs header; consecutive beats plus minimum span plus dispatch hold
Claims 52-57
52
Fleet drives real interactive Claude Code sessions over a pseudo-terminal. It never uses claude -p, the Agent SDK, or streaming JSON output, which moved to metered API billing in June 2026. Structured events come from Claude Code's own hooks, which cost no tokens. The spawn argument list is short enough to read, and there is no -p in it.
53
The supervisor, the resource sampler, transcript search, the handoff digest, the status monitor, the doc lint, the deterministic slop linter, and the status-line usage feed are all local subprocesses, file reads, or plain HTTPS GETs. Zero model tokens.
54
Both ride the worker's process environment at spawn (defaults 20 and 30, scaled by the task's effort tier), because the CLI reads its own launch environment. At the cap the CLI degrades politely, telling the model to finish with its own tools. The orchestrator is deliberately uncapped.
55
If a session reports the chosen model is unavailable, the spawn path retries down a fixed chain and tells you which model actually started. It never walks up mid-session, and a re-attached orchestrator realigns onto your choice when it is available again. A corrupt or unknown stored preference falls back to the current default rather than launching something unknown.
56
Timezone and DST-aware next-run, advance-before-fire so a crash cannot double-fire, catch-up after the Mac sleeps, a concurrency cap so 9am does not launch a dozen sessions, exponential backoff, and auto-disable. A prompt-injection scan can block a fire. Results can be delivered to Telegram through a direct API call rather than hoping the orchestrator is idle enough to relay it.
57
Saving a successful worker's brief creates a provisional skill. It is promoted to active only when a worker spawned from it reaches Done with a passing proof. A stale, never-reused skill can be quarantined, which is reversible. Nothing is ever deleted.
What proves claims 52-57
Interactive substrate, zero-token mechanics
pty.rs:36-59 claude_argv ("No -p, no --output-format stream-json, no SDK") plus its comment; .claude-docs/billing-substrate.md; the zero-token notes in transcript.rs, status.rs, agents_probe.rs, handoff.rs, resources.rs, supervisor.rs
Per-worker budgets
settings.rs worker_budget_process_env, DEFAULT_MAX_SUBAGENTS/DEFAULT_MAX_WEB_SEARCHES; prefs.rs:360-367; CLI floor 2.1.212
Model selector and fallback
model.rs header; FALLBACK_CHAIN; sanitize_model fail-closes to MODEL_OPUS_5; schedule_model_realign
Scheduling and Telegram
schedule.rs header; MAX_CONCURRENT_SCHEDULED; injection scan; telegram.rs header (the direct send path and the bug it replaced)
Skills promote-on-success
skills.rs:23-42 lifecycle; lib.rs:1618-1634 promote_on_success; test lib.rs:24809
Claims 58-61
58
Clicks and keystrokes are delivered as native events to the embedded web view, so the page sees isTrusted === true. Elements are addressed by an opaque reference from the last snapshot, never by a selector the model invented, because a selector gets re-queried at action time and can match a different node.
59
wait fails on timeout rather than continuing, and every action reports what it actually did. Filling a field types real keys rather than assigning to .value, and results report a character count, never the text.
60
Identity providers block embedded web views on purpose. Fleet decides before it commits to the navigation, so the pane never goes blank, explains what happened, and offers one button that imports just that site's cookies from your browser. That button is deliberately unreachable from the control socket, so nothing automated can trigger your Keychain prompt.
61
A curated filter (not a dump of everything) picks the seeable deliverables a finished worker made and shows them in the Files tab. Binary files are staged into the app's own directory so they can actually render, and text files are never copied or deleted, only referenced.
What proves claims 58-61
Browser acting verbs
browser_act.rs header (contract taken, CDP rejected, trusted NSEvents, snapshot refs not selectors, wait fails on timeout, fill never assigns .value); CLAUDE.md's six measured traps
Sign-in deflect and session import
browser_session.rs header; browser::IDP_EXTERNAL_HOSTS; browser_resume_signin GUI-only, recorded in docs/ctl-parity-audit.md
Proactive file surfacing
surfaced.rs header (curated, not a dump); artifacts.rs validate_path containment; text originals never unlinked per CLAUDE.md's unshow entry
Working notes
Things in the codebase that are real but did not earn a place on the list above, and the reason each one was left off.
license.rs).PaywallMode::Test is the default, so the gate is bypassed entirely. Not a shipped behavior.task_type.rs).socket.rs:4480 notes the verdict is "byte-for-byte unchanged". Describing it as a gate would be an overclaim.hooks/hot-zone-guard/).spec/TELEMETRY.md, telemetry.rs, telemetry_send.rs).transcript.rs says keyword tier only, not the semantic tier..claude-docs/architecture.md, not a shipped path.multi_account.rs).scout.rs).prefs.rs's own module header is stale.AutonomyLevel enum and the router contract instead, not from that comment.Fleet is a macOS app. Download it if you want the behavior above on your own machine, or read the levels of AI-assisted engineering for the map this sits at the top of.