Resumable, agent-agnostic ralph-loop driver: takes a Linear ticket from worktree creation through merge as a sequence of single-shot agent subprocesses.

A single long-lived agent context bloats and degrades. Splitting into phases — research / plan / implement / review — with fresh subprocesses keeps each phase lean and lets you resume after any crash.

git clone <this-repo>
cd autopilot_sh
./install.sh   # symlinks bin/autopilot into ~/.local/bin

Host tools: bash 3.2+ (macOS default works), jq, envsubst (from gettext), git with worktree support, and a coding-agent CLI on PATH (default: Claude Code's claude). Some phases also need agent-side MCPs/skills (Linear, browser) and optional binaries (codex, gh) — see Requirements for the full per-phase list.

A child process can't change the parent shell's directory, so autopilot can't cd you into the worktree directly. Add this shell function to your ~/.zshrc or ~/.bashrc to wrap the call and cd after success:

autopilot() {
  command autopilot "$@"
  local rc=$?
  local marker="${XDG_STATE_HOME:-$HOME/.local/state}/autopilot/last-wt"
  if [[ $rc -eq 0 && -f "$marker" ]]; then
    cd "$(cat "$marker")" || return
  fi
  return $rc
}

Now autopilot <linear-url> leaves you inside the worktree when it finishes. The marker file ($XDG_STATE_HOME/autopilot/last-wt, default ~/.local/state/autopilot/last-wt) is written as soon as the ticket ID is parsed, so even after a mid-run Ctrl-C you can cd "$(cat ~/.local/state/autopilot/last-wt)" to jump into the worktree to inspect logs / state.

Autopilot itself is just bash + jq; the heavier capabilities live in the agent it drives — autopilot doesn't install those, so your agent CLI must already have them.

Features of the agent CLI, not autopilot. Most are Claude Code specific and degrade gracefully on other agents.

Copy the boilerplate and edit it for the repo:

cp /path/to/autopilot_sh/.autopilotrc.example .autopilotrc

Full variable reference: Configuration. Secrets like LINEAR_API_KEY go in .autopilotrc (git-ignored) or your shell env — never commit them.

cd /path/to/your/repo
cp /path/to/autopilot_sh/.autopilotrc.example .autopilotrc
# edit .autopilotrc — set symlinks, setup, verify commands

# Default: interactive — pauses at plan TLDR and post-review checkpoint.
autopilot https://linear.app/<team>/issue/TEAM-123/some-slug

# Full autopilot: no human in the loop.
autopilot --full https://linear.app/<team>/issue/TEAM-123/some-slug

# Plan-file mode: run an existing plan, no Linear ticket.
autopilot docs/plans/2026-06-04-shared-app-sidebar.md

Re-run the same command to resume from the last completed phase. See Resuming after interruption below for details.

Pass a plan file (an argument ending in .md, or any existing file) instead of a Linear URL to run a plan you already wrote — useful when you've planned by hand, or in a repo without Linear. Autopilot skips the Linear fetch, research, and plan phases: it creates a worktree (<base>/<project>/<slug>, branch feature/<slug>, slug derived from the filename minus any leading YYYY-MM-DD-), copies the plan to .autopilot/plan.md, and resumes at the implement phase. The plan is treated as pre-approved, so the plan checkpoint is skipped; the post-review checkpoint still applies. Everything downstream — implement, the reviewer/adversary/codex cycle, and merge/PR — runs exactly as in ticket mode.

Set via --full / --interactive CLI flag (overrides AUTOPILOT_MODE env).

See .autopilotrc.example. Per-project config lives in .autopilotrc in each repo you want to drive.

AUTOPILOT_AGENT=codex runs the pipeline with the built-in balanced preset by default. Autopilot invokes codex exec --json directly—without shell eval—and selects the model, reasoning effort, and subagent policy for each phase. The resolved matrix is frozen in <worktree>/.autopilot/run-config.json; managed invocation settings are persisted in state.json, so a child verb cannot silently lose --verify or resource limits. CLI model/config flags outrank ~/.codex/config.toml, but Autopilot does not pass --ignore-user-config or disable MCP/plugin entries: existing Linear, logs, browser, Storybook, and other Codex integrations remain enabled.

Managed Codex also enforces one live step per worktree with a PID/start-token lease. If a long command-tool call yields, a retry receives {"error":"step already running",…} instead of starting a second reviewer/fixer against the same files. Launcher interruption stops only that recorded process tree. Worker prompts and inherited runner hints cap broad local validation at AUTOPILOT_TEST_CONCURRENCY (default 2) so Turbo/Jest/Vitest do not fan out across the laptop unchecked.

The sandbox defaults to danger-full-access, matching the claude path's --permission-mode bypassPermissions (also unrestricted): the stricter workspace-write has no network, which breaks browser-verify (can't reach localhost or drive agent-browser), implement (can't install a dependency), and research (can't fetch docs). Set AUTOPILOT_CODEX_SANDBOX=workspace-write to opt into the sandbox and accept those limits.

Balanced model matrix:

Balanced Codex is pure Codex: AUTOPILOT_CODEX_CMD defaults empty, so no Claude cross-review is launched. Set an explicit cross command only when you deliberately want one. Setting any legacy Codex model/agent command selects the custom path automatically; pin AUTOPILOT_CODEX_PRESET=balanced to force the matrix.

Capability matrix — what changes under AUTOPILOT_AGENT=codex:

Minimal pure-codex .autopilotrc:

: "${AUTOPILOT_AGENT:=codex}"
# balanced is automatic; optional tier overrides:
# : "${AUTOPILOT_CODEX_SOL_MODEL:=gpt-5.6-sol}"
# : "${AUTOPILOT_CODEX_TERRA_MODEL:=gpt-5.6-terra}"
# : "${AUTOPILOT_CODEX_LUNA_MODEL:=gpt-5.6-luna}"
# : "${AUTOPILOT_CODEX_PRICE_IN:=1.25}"
# : "${AUTOPILOT_CODEX_PRICE_OUT:=10}"

Set AUTOPILOT_AGENT_CMD to any CLI that reads a prompt on stdin and exits non-zero on failure. Examples:

# Codex CLI
export AUTOPILOT_AGENT_CMD="codex -p"

# Aider
export AUTOPILOT_AGENT_CMD="aider --message-file /dev/stdin"

Whichever agent you choose, it must have a Linear MCP server installed and authenticated. The Linear-fetch prompt explicitly refuses to fall back to direct HTTP — single auth path, intentional.

worktree → research → plan → [checkpoint] → implement → [per-commit review] → review (×AUTOPILOT_REVIEW_CYCLES, default 2) → visual-verify → [checkpoint] → [--verify: test-plan → local-main merge (+verify-cmd gate in full) → env-verify] → merge|pr|preview|hold

--managed: [worktree] → master(status→step→report)* → merged|exit 3

With AUTOPILOT_COMMIT_REVIEW=on, a per-commit review runs first (after implement, before the cycle): each new commit is reviewed individually on the cheaper review model, flagging only issues still present at HEAD; findings feed the same fixer. It's opt-in (N extra calls, capped at 20) and advisory.

The reviewer/adversary/codex checklists cover correctness, tests, architecture, perf, security, style, plus code-health — duplication, complexity, and dead-code.

Each review cycle runs a finder pass — reviewer → adversary → codex cross-review (if codex is on PATH) — then the fixer. By default there are up to two rounds (AUTOPILOT_REVIEW_CYCLES=2), so cycle 2's finder pass re-reviews the fixer's output — otherwise fixes (especially risky migration/data changes) can ship unreviewed. Early-exit keeps it cheap: if a finder pass leaves no open findings the fixer is skipped and the loop stops, so cycle 2 usually converges after just re-reviewing the fixes. Set AUTOPILOT_REVIEW_CYCLES=1 for the leanest run, 3 for migration-heavy changes. Codex is part of the finder pass, so it must also come up empty before the loop exits. Review phases run on the cheaper AUTOPILOT_MODEL_REVIEW.

Inline review (AUTOPILOT_REVIEW_MODE, default agent): for small tasks, four fresh review sessions re-reading the codebase is waste. In agent mode the implement agent judges per task — it records {mode: inline|phased, reason} in state.json (criteria: small + self-contained + lean context + low risk → inline; concurrency/schema/auth/cross-cutting or any doubt → phased). Inline replaces a cycle's four phases with one 05i phase that resumes the implement session (warm context, no re-read) and runs codex as the independent finder: findings land in feedback.json verbatim before triage, fixes are committed, dismissals need reasons, and a dismiss-heavy or still-dirty result escalates to the phased pipeline for the same cycle. Any inline hiccup (no codex, unrecoverable session, phase failure) falls back to phased automatically — same cycle markers, same resume semantics. inline/phased values pin the path; review_mode_used in state.json records what actually ran. Independence is preserved because findings always originate from the second model reading the diff cold; the warm session only triages and fixes.

Plan-file mode enters the pipeline at implement, skipping worktree's Linear fetch plus the research, plan, and plan-[checkpoint] steps.

Local-only repos (no origin remote) work too: the worktree branches from the local default branch (main/master/current), review diffs against it, and the final merge/pr/preview is skipped — the work is left committed on its branch for you to push or merge manually once a remote exists.

Each phase writes a marker to <worktree>/.autopilot/state.json. Re-running the entry script skips completed phases.

After review converges, the visual-verify phase checks UI work against the ticket's acceptance criteria in a real browser (AUTOPILOT_VISUAL=auto|on|off):

• Gate: in auto it runs but exits early when the diff has no user-facing UI; on always runs; off skips the phase.
• Baseline: design mockups/screenshots attached to the Linear ticket (uploads.linear.app images + image attachments) are downloaded during the fetch into .autopilot/criteria/ and used as the comparison reference. Figma links are noted but not rendered.
• Run: it inspects the diff and launches the smallest meaningful UI runtime from the worktree — normally client-only, adding a backend only when the acceptance flow requires one. It binds unused loopback ports, drives the flow with the agent's browser tooling, saves screenshots, and tears down only what it started. AUTOPILOT_APP_CMD is an optional preferred command.
• Findings: unmet criteria become open items (source:"visual") the fixer addresses, then it re-verifies (bounded to 2 passes). A .autopilot/visual-report.md and the screenshots are surfaced at the review checkpoint.

Requires the worktree agent to have browser tooling (the webapp-testing/dev-browser skill or a Playwright MCP) and a launchable app. It's advisory — a phase error warns and continues rather than aborting the run.

--verify adds a single-machine verification stage between the review checkpoint and the configured delivery action (works with --interactive or --full):

1. Test plan + runtime decision — compose a manual plan from the ticket and diff and classify the minimum useful topology (command-only, client-only, server-only, client+server, or full-stack). Light uses this focused one-pass plan; full has codex challenge coverage and unnecessary services, then runs a refinement pass. Steps are tagged [browser], [api], or [command].
2. Light runtime (bare --verify) — run the ticket branch directly from its worktree. In classic mode the verifier owns discovery/startup; in managed mode the top-level master discovers the commands, provisions required services with runtime-port/runtime-start, passes their URLs down, and stops them after verification. Both paths bind unused loopback ports, start only required processes, and require no app/health configuration. They do not checkout, merge, push, use the source checkout, or depend on the shared Docker environment. UI-only work can use a client/static/story harness; server-only work can use a focused command or API process; client+server/full-stack is selected only when the acceptance behavior needs it.
3. Full integration runtime (--verify=full) — guarded merge into the source checkout's local main, run AUTOPILOT_VERIFY_CMD when explicitly pinned, then health-check and test the configured attached /dev-setup environment at AUTOPILOT_APP_URL. Merge conflicts or a failing pinned verify gate roll local main back; nothing is pushed. Optional remediation uses AUTOPILOT_ENV_RESTART_CMD and the restart broadcast.
4. Delivery — continue to the normal merge / pr / preview / hold decision. Verification itself never changes the remote.

The runtime/browser result is advisory and is written to .autopilot/test-results.md; startup failures and unavailable browser tooling are recorded as failures instead of silently claiming coverage. Light runs are naturally isolated across Autopilot instances. Full runs serialize only the local-main merge using .git/autopilot-verify.lock; attached-env restarts use the protocol in docs/restart-protocol.md.

--managed creates the worktree, then hands the run to one headless master agent session (prompts/00-master.md) that drives the same ralph loop through step-level verbs: status → step <next> → classify the report → repeat. The master owns runtime understanding and provisioning: before visual/test-plan/runtime phases it calls runtime-context, reads the relevant package scripts/docs, decides the minimum credible topology, obtains unused ports, and starts the discovered project commands through the managed runtime lifecycle. Child phases attach to those URLs; the master stops services afterward, with the launcher EXIT trap as a crash backstop. No AUTOPILOT_APP_CMD, AUTOPILOT_APP_URL, or health command is needed for managed light verification. Composes with --full / --verify.

Degradation guarantee: kill the master at any time — the launcher terminates the exact PID/start-token process tree recorded by the worktree's step lease and preserves the last completed phase. Resume with either driver:

autopilot --managed <ticket>   # a new master reconstructs from reports.jsonl + state.json
autopilot <ticket>             # the classic loop picks up from the same phase marker

autopilot status --ticket X reports .in_flight while a step supervisor or its child is alive. A duplicate step is refused; dead leases are reclaimed on the next step. This is process-identity scoped—Autopilot never kills every codex, node, or test process by name.

Exit codes: 0 only when the run reached phase merged. 3 when the master session ended short of it (escalated, stalled, out of turns) — the decision trail is <worktree>/.autopilot/reports.jsonl, and the master's final message in <worktree>/.autopilot/logs/00-master.log is its diagnosis. Any other nonzero is the master session itself failing (the process rc propagates).

Run it headless with --full. Managed + interactive needs a live tty: the 03/07 checkpoints talk to you on the terminal while the master blocks on the step. The launcher warns about the combination, and a checkpoint without a usable tty fails fast instead of hanging.

The master may decide runtime topology/provisioning, failure classification, retries (at most 2 re-steps per phase, counted across master restarts via reports.jsonl), notes, and escalation. It may inspect the diff and relevant manifests/config read-only and start discovered commands only through the lifecycle verbs below. It may not skip a quality gate, edit code, run git mutations, or launch untracked background processes directly.

With autopilot-pipeline installed (or available as the sibling source repo), Autopilot exposes a durable multi-ticket supervisor:

autopilot factory start \
  https://linear.app/trayo/project/self-serve-to-do-august-2026-ce7ee947cd5b/issues \
  --max-workers 2 \
  --test-workers 1 \
  --verify light \
  --delivery pr

The factory fetches the whole project with pagination, stores its jobs and explicit Linear blocker DAG in SQLite, and launches dependency-ready tickets as independent --managed --full --verify Codex runs. Each worker gets its own branch/worktree/leases and a shared project brief. Parallelism is bounded at both levels: --max-workers tickets globally, --test-workers validation workers per ticket, and one research helper per ticket by default. MCP and the project's normal Codex user configuration remain enabled.

PR delivery is dependency-safe: an issue blocked by another project issue is not released merely because the blocker opened a PR; the supervisor waits for gh to report that PR merged. Full verification is deliberately rejected for parallel factories because it mutates shared local-main/runtime state; use the isolated light verifier.

autopilot factory status <project-url>
autopilot factory pause <project-url>
autopilot factory resume <project-url>
autopilot factory retry <project-url> TRA-1234
autopilot factory stop <project-url>

Factory commands print a short operator summary by default; add --json for the complete machine-readable jobs and dependency state.

Set AUTOPILOT_FACTORY_BIN=/path/to/factory.sh when the factory executable is not installed as autopilot-factory and the repositories are not siblings.

The master's control surface — equally usable by hand to drive or inspect any run:

Contract:

• Outcomes classify by payload shape, never by rc alone: {"error": …} is a gate refusal (rc 3 — phase already done, prerequisite missing, verify disabled, or step already running; no new work ran), {"phase": …} is a step report whose .rc is the step's outcome.
• One in-flight step per worktree: enforced by an atomic lease containing supervisor and child PID/start-token identities. Wait while status .in_flight is non-null; never infer death from a missing report.
• stdout carries only the answer: the JSON (or phase name) — progress and logs go to stderr, so verbs pipe cleanly into jq.

Phase names are the ones autopilot next and the usage text print (01-worktree … 06-merged), with 05-review-cycles as a single aggregate phase — one step runs the whole remaining review loop. --ticket X resolves the worktree from anywhere; without it, run from inside a worktree.

Re-run the exact same command and autopilot continues from the last completed phase:

cd /path/to/your/repo
autopilot https://linear.app/<team>/issue/TEAM-123/some-slug

State lives in <worktree>/.autopilot/state.json — that file is the resume protocol. The script reads .phase and skips every phase already done.

WT=~/wt/<project>/<ticket>
jq -r '"phase=\(.phase)  cost=$\(.total_cost_usd // 0)"' "$WT/.autopilot/state.json"
ls "$WT/.autopilot/logs/"

If you want to redo a specific phase (e.g. regenerate the plan with a fresh context), back the phase pointer up to before the marker you want re-run:

WT=~/wt/<project>/<ticket>
# To regenerate the plan: rewind to research_done
jq '.phase = "research_done"' "$WT/.autopilot/state.json" \
  > "$WT/.autopilot/state.json.tmp" && mv "$WT/.autopilot/state.json"{.tmp,}
autopilot <linear-url>

Valid phase markers (in order): none, worktree_done, research_done, plan_done, plan_approved, implement_done, review_cycle_1_done, review_cycle_2_done, review_cycle_3_done, review_approved, merged.

WT=~/wt/<project>/<ticket>
BRANCH=$(jq -r .branch "$WT/.autopilot/state.json")
rm -rf "$WT"
git -C /path/to/source/repo worktree prune
git -C /path/to/source/repo branch -D "$BRANCH"
autopilot <linear-url>

State is per-worktree, so different tickets resume independently. autopilot URL-A and autopilot URL-B write to different .autopilot/state.json files under different worktree directories — you can have one ticket paused at a checkpoint and start another in a fresh terminal without conflict.

Every run appends one JSON line to AUTOPILOT_METRICS_FILE (default ~/.local/state/autopilot/runs.jsonl) — cost, cycles, final action, per-phase cost/turns, and findings grouped by source × status. It's emitted on any exit (success, failure, interrupt), so partial runs are captured too. Disable with AUTOPILOT_METRICS=off; export elsewhere by setting AUTOPILOT_METRICS_SINK to a command the record is piped to (e.g. a curl poster to PostHog/Langfuse).

This makes tuning evidence-based rather than guesswork. Examples (F=~/.local/state/autopilot/runs.jsonl):

# Is the codex cross-review earning its cost? (findings it surfaced that got fixed)
jq '[.findings_by_source.codex.fixed // 0] | add' "$F" | jq -s add
# Average cost per run, and cost share of each phase
jq -s 'map(.cost_usd) | add/length' "$F"
jq -s 'map(.per_phase|to_entries[]) | group_by(.key) | map({phase:.[0].key, cost:(map(.value.cost)|add)})' "$F"
# How often review converged in one round (early-exit) vs needed cycles
jq -s 'group_by(.cycles) | map({cycles:.[0].cycles, runs:length})' "$F"
# Severity/noise: adversary drops vs. real catches
jq -s 'map(.findings_by_source.adversary // {}) | {dropped:(map(.dropped_by_adversary//0)|add), fixed:(map(.fixed//0)|add)}' "$F"

bin/autopilot       Entry script
lib/                Sourced bash modules
prompts/            Per-phase prompt templates ({{VAR}} substitution)
templates/          Initial state.json, feedback.json, plan template
tests/              bats-core unit tests

make test    # bats tests
make lint    # shellcheck

The pipeline (state machine, phases, checkpoints, review cycle) is agent-agnostic, but a few pieces still assume Claude Code. Cleanup ideas for anyone who wants to send a PR:

Add AUTOPILOT_AGENT=claude|codex|aider that picks the right defaults so users don't hand-craft every flag.

The agent-profile seam (lib/agent.sh::agent_cmd_for / agent_filter_for) already dispatches command + output filter by profile name (primary, cross). Extending it to a full AUTOPILOT_AGENT=claude|codex|aider selector for the primary agent is the natural next step.

• Pretty filter (lib/agent.sh::agent_pretty) — currently parses Claude's stream-json schema ({"type":"assistant","message":{"content":[...]}}). Non-JSON lines already pass through verbatim, so dropping --output-format=stream-json from AUTOPILOT_AGENT_CMD gives you the agent's native streaming UI for free. A proper fix is per-agent filters dispatched by the new env var.
• Permission flag — --permission-mode bypassPermissions is Claude-Code syntax. Codex uses --full-auto; aider auto-approves by default.

prompts/02-research.md references Claude Code's codebase-* subagents by name. Other agents don't have those. Either:

• Make subagent invocation conditional on agent type, or
• Rewrite the research prompt to be agent-neutral (just "explore the codebase via Read/Grep/Glob and produce research.md").

lib/linear.sh::linear_fetch prefers the Linear REST API (linear_fetch_via_api) when LINEAR_API_KEY is set — workspace-portable, headless, and no agent/MCP dependency for the cheapest phase. Set it (a lin_api_... personal key) for --full/CI runs; otherwise the fetch falls back to the agent's Linear MCP, which needs interactive OAuth and won't work headless. The REST path also captures the ticket's reference images (see Visual verification).

Default worktree base is $HOME/wt/<project>/<ticket>/. Repos with their own worktree tooling (e.g., trayoai's scripts/worktree-new puts them in .worktrees/ with port-offset Docker stacks) won't get that integration. A hook (AUTOPILOT_WORKTREE_CMD=./scripts/worktree-new) would let autopilot delegate creation to the repo's own script.

agent_cmd_for dispatches four profiles: primary (implement), review (the 05x loop), research (02-research + 03-plan), and master. Each has its own model and effort knob; only implement still runs on AUTOPILOT_MODEL by default. Finer-grained splits (AUTOPILOT_MODEL_ADVERSARY, etc.) are a natural extension of the same dispatcher.

The bash pipeline is the right spine — portable across agent CLIs, resumable across crashes/checkpoints, transparent on-disk state — and the top-level flow (implement → review → merge) is inherently sequential, so it should stay as-is. The leverage is inside phases that are naturally multi-perspective or parallel. research already fans out (three ap-* subagents pinned to cheap models via --agents); review is the next candidate. Two ways to add it, both Claude-only, so they'd be gated behind a config with the current serial review as the fallback:

• (a) Prompt-level fan-out (recommended first): the reviewer prompt spawns N parallel dimension-subagents (correctness / security / perf / tests), dedups, then adversarially verifies each survivor. Improves coverage and wall-clock (parallel), and is more independent (each dimension a fresh agent, no shared blind spot). No new substrate — it runs inside the existing claude -p review phase and degrades to a normal review on non-Claude agents. Fan-out is "what runs inside a review cycle," so it composes with the early-exit loop.
• (b) Workflow-backed phase: back a phase (e.g. 05a) with a deterministic Workflow script (parallel/pipeline primitives, schema'd output, its own journal) by swapping that phase's agent command. More orchestration power, but couples to the Claude Code/Workflow runtime — so it must be opt-in (like the codex tier) with the bash path preserved.

Whole-pipeline rewrites into a single workflow/subagent session are not recommended: they trade away agent-agnosticism, cross-session resumability, and human-checkpointing for parallelism the sequential spine can't exploit.

make test covers config/linear/phases/state/agent_pretty. Not covered: phase01.sh (worktree creation), phase06.sh (merge/pr/preview/hold), review.sh (cycle driver), checkpoint.sh (interactive read loop). These need fixture-based or pty-driven tests.

• Setup command output (pnpm install, prisma generate) is unfiltered raw stdout — fine but loud. Could be silenced behind a "show on failure" toggle.
• No way to skip phases ad-hoc (e.g., "I already have a plan, jump to implement"). A --from <phase> flag would help.
• No dry-run of what each phase will do before kicking it off.

MIT