shiploop

A self-improving multi-agent harness for Interactive Coding Agents. It grinds a ticket backlog across every repo in your product: a fresh headless agent per ticket, guarded auto-merge on green CI, and a durable lesson written into your tracked CLAUDE.md after every resolved ticket.

Built to spend fewer tokens

One goal: the fewest tokens per shipped ticket. This section lists only the levers that move that number by multiples. Dozens of smaller economies exist in the code — cached lookups, retired validations, cleanup of abandoned resources — and they're real, but they're rounding errors next to these five.

• Model orchestration. The dominant cost variable is which model runs a ticket, and the spread is wide: on this maintainer's backlog a resolved ticket costs roughly $0.59 on haiku, $2.22 on sonnet, $8.94 on opus. So the harness does not try to predict the right tier — it bets cheap and pays for the expensive model only when the cheap one has already demonstrably failed. Every ticket starts at a floor (GOVERN_WORKER_MODEL, default sonnet) and a classified failure escalates it once to a ceiling (GOVERN_WORKER_ESCALATION_MODEL, default opus), never further. That asymmetry is the whole trade: failed attempts die early and cheap (they average a fifth of the tokens of a successful one), so a wrong cheap guess costs far less than a right expensive one. Escalation is also classified rather than reflexive — an infrastructure or CI failure retries at the same tier with the log attached, running out of budget raises the tier, and only a genuine judgment failure buys both a bigger model and more thinking.

  This replaced an earlier design where a cheap scout pass scored each ticket into a tier. It was removed because it was measured and didn't work: 4 of the 5 verdicts it ever produced were opus/high, and 3 tickets it sized opus then succeeded at sonnet on the first attempt. It was a rubber stamp, not arbitrage. The scout still runs — it just surveys now, and doesn't size.

• A lane that spends no model at all. The largest arbitrage available isn't opus→sonnet, it's model→no model, which is unbounded rather than a 4–15× ratio. A real share of any backlog is mechanical: flip a default, add a key, bump a version, delete a stale line, apply a known rename. The scout already runs and already reads real code, so it emits a candidate patch as one extra field on a call that was happening anyway — never a second model invocation. deterministic-apply.sh then applies that patch, verifies it, and opens the PR with zero model turns spent on the fix. Every doubt falls through to an ordinary worker: kill switch off, empty patch, a path outside the scout's verified list, a patch spanning two sub-repos, a dirty tree, git apply --check failing, no verify command configured, or the verify command failing. Falling through costs exactly one normal worker — the status quo — while a wrong patch costs a bad PR, a CI cycle, and your attention, so the guards are deliberately over-strict. Off by default (GOVERN_DETERMINISTIC).

• Tool schemas get trimmed, and that compounds every turn. Measured on a real spawn, tool definitions were 51.7% of the entire request — larger than the conversation itself. Most of it was unusable by a headless worker: the Workflow schema alone was 13.1% of the request. Passing an explicit tool list cuts tool bytes by 66.7% and the whole request by −34.5% (164,795 → 107,985 bytes; full methodology in PROOF.md §5). This matters more than the raw percentage suggests, because a worker session runs ~218 turns and that overhead is re-sent on every one of them. On by default now, capability-probed so an older CLI just skips it.

• Work that can't succeed never starts. Before spawning anything: is this repo's CI already red, is this ticket waiting on another that isn't done, is the disk nearly full, is this a check whose setup isn't wired yet? Any yes and it skips. And if your workspace runs the harness on itself, a separate gate asks whether the hub is already ahead of you on the files the ticket names — if another fleet pushed the identical fix up, you get told to pull it down instead of a worker re-deriving it from scratch. All of this is file and git reads: no model call, no network. A session you never start is the cheapest one there is, and skipping one avoids the entire ticket cost rather than shaving a percentage off it.

• A retry resumes instead of restarting. Exploration is most of what a ticket costs, and before this a failed attempt bought you literally nothing. Now the worktree is preserved, so attempt two doesn't re-clone or re-explore, and it inherits the previous attempt's work: a scratchpad of which files turned out to matter and what was already ruled out, plus a structured handoff block (ruled out / stopped at / would try next) injected as "start here". Both are capped and both are handed over explicitly marked as untrusted evidence, not instructions — a wrong conclusion from attempt one shouldn't become gospel for attempt two. They live in the worktree, git-ignored, and never reach a PR.

• Batching, with a caveat. One worker can take several tickets whose scout-measured file paths actually overlap, so it explores that area once instead of once per ticket. Default is 2 (GOVERN_BATCH_MAX). Be honest about this one: the mechanism is sound and exploration really is where the money goes, but no production A/B measurement exists. A 5-ticket batch is nowhere near 5× cheaper than 5 workers. The cap was raised off 1 only after batching was re-keyed onto measured file overlap rather than a topic guess.

Three things worth knowing up front. The driver itself is free — the bash that picks tickets, tracks state, and merges PRs never calls a model, so tokens burn only inside the workers it spawns. Running four workers at once is the default (GOVERN_PARALLEL_DEFAULT), which gets more done per hour but costs four times as much at once and makes no single ticket cheaper. And several protections above only apply when the governor pulls from your backlog itself: name specific ticket numbers and you get neither batching nor the give-up-after-repeated-failures brake.

The scaffolding around all this

Two layers get built for you: a workspace once, and a fresh worker per ticket.

The workspace. /shiploop:setup wraps your existing repo rather than absorbing it — your code moves into a subfolder and stays its own git repo with its full history, and the workspace scaffolds around it. The path you cd into doesn't change. Everything that appears next to it is plain text you can read and edit:

your-project/
  <your-repo>/              # your code, untouched, still its own git repo
  queue/tickets.md          # the backlog, one `## #N` per ticket
  governor/                 # doctrine, escalations, improvements
  scripts/                  # bash: status / dev / doctor / worktrees / govern
  scripts/lib/workspace.sh  # the ONE config file; every knob lives here
  CLAUDE.md                 # git-tracked memory; every resolved ticket adds a lesson

The scripts are the harness, and they're all bash. run-loop.sh is the driver: it owns state and control flow deterministically and never calls a model. spawn-worker.sh builds a worker's prompt and launches it. config-check.sh validates your entire config with zero tokens and no Claude auth. Because the orchestration layer is deterministic bash rather than an agent, the parts that decide what to do cost nothing; only the parts that do the work spend anything.

The worktree is what makes parallelism safe. One ticket gets one git worktree, cut fresh from an up-to-date main with a branch named for the ticket in each sub-repo actually in scope; sub-repos out of scope get a read-only detached checkout so a worker can read them but not touch them. Workers can't collide, no run inherits the last one's bad state, and context stays flat instead of accumulating across tickets. On failure the worktree is kept for the retry to resume from; it's only removed once the work lands, and never while it holds commits you haven't pushed.

The worker is a fresh headless claude -p session inside that worktree. It gets a fixed prompt skeleton, your operator doctrine from governor/preferences.md, the ticket text, the scout's verified file paths as a warm start, and — on a retry — the previous attempt's handoff. It's also deliberately denied things: no MCP servers, no slash commands, no personal user-settings layer, and a trimmed tool list. That's not just thrift. A single-purpose headless worker has no use for scheduling, notification, or orchestration tools, and every schema it can't use is dead weight re-sent on all ~218 of its turns. It works, opens a PR, and writes a structured report the bash driver reads to decide what happens next.

Autonomy is bounded by the trust ladder below, not by the scaffolding — workers run with permissions bypassed by design, scoped to a throwaway worktree and the branch it pushes.

Install

# In Claude Code:
/plugin marketplace add anshss/shiploop
/plugin install shiploop@shiploop

This installs the plugin once, globally: commands appear as /shiploop:setup, /shiploop:flows, etc. in every session — the ticket loop itself isn't a command, it's natural language ("work through the queue") onto scripts/govern/run-loop.sh (see Quickstart). Each project you want shiploop on then gets its own one-time setup (next section). Prefer a clone? git clone https://github.com/anshss/shiploop.git ~/.claude/skills/shiploop && bash ~/.claude/skills/shiploop/install.sh. Same commands, same layout.

Quickstart

1. Set it up on your project: one command, one round of questions

Open Claude Code in the project you want shiploop to work on, and run setup:

cd ~/code/your-project && claude

/shiploop:setup

Setup detects what the folder is and adapts:

• An existing repo → wrap-in-place. Your repo moves into a subfolder and the workspace scaffolds around it. The path you cd into stays the same, full history travels as one unit verified byte-identical, and a generated .wrap-undo.sh reverses everything until it all verifies.
• A folder of repos (or an empty one) → fresh scaffold. Each subfolder with its own .git becomes a sub-repo. One repo is a fine workspace. Add more later.
• An existing workspace → upgrade, component by component, without touching your config.

It detects everything first (sub-repos, ports, dev commands, package manager), asks its questions in one batched round, then runs to completion. You end up with the workspace laid out in The scaffolding above.

Nothing you own gets clobbered on an upgrade: your README.md, CLAUDE.md, scripts/lib/workspace.sh, and the governor's operator files (preferences.md, decisions-log.md, escalations.md, improvements.md) are either never overwritten or refuse to be without an explicit --yes; .gitignore is append-only. A wrap-in-place writes a .wrap-undo.sh before it moves anything, verifies your repo's HEAD, branch, working-tree status, and submodule state are identical after the move, and rolls back on any mismatch.

2. See your product's risk map: 10 minutes, nothing deploys

/shiploop:flows extract   # inventory every user-facing path that might break
/shiploop:flows list      # your risk map: proven / untested / stale / failed

Extract fans out one agent per surface, and the inventory is staged for your approval: it opens no PRs, merges nothing, rents no compute. On a fresh extract everything is UNTESTED: that list is exactly the map of what you don't yet know works. Proving a path (/shiploop:flows file <id>) can deploy, so it's dry by default: nothing files until --yes, --max-deploys N caps a batch, and --all-stale/--all-untested refuse unless the orphan-sweep (GOVERN_DEPLOY_SWEEP_CMD) is wired.

3. File one ticket, watch it ship

From the workspace root:

scripts/govern/file-ticket.sh "Fix empty-state copy on /settings"   # into queue/tickets.md
bash scripts/govern/config-check.sh   # free smoke test, no tokens, no Claude auth

Then just say "work on that ticket" (or "work through the queue" for the whole backlog) — Claude
maps it straight onto scripts/govern/run-loop.sh: fresh worker → edits → PR → waits for CI.

New workspaces start on the pr-only rung: workers open PRs, the governor never merges. You click merge. When you've read enough of a repo's PRs to trust the pattern, add it to GOVERN_MERGE_REPOS and its green-CI PRs auto-merge, guarded (Trust).

How it works

The governor is a pure-bash driver (scripts/govern/run-loop.sh): it owns state and control flow deterministically and spends near-zero Claude context. Model tokens burn only inside the fresh headless workers it spawns.

• One ticket = one fresh headless session in its own git worktree. Context stays flat, workers ship in parallel without collisions, no run inherits the last one's bad state.
• Cheap floor, escalate once. Every ticket dispatches at GOVERN_WORKER_MODEL (default sonnet); a classified failure escalates it exactly once to GOVERN_WORKER_ESCALATION_MODEL (default opus). No per-ticket prediction, because prediction was tried and measured as a rubber stamp. A cheap scout pass (haiku) still runs before dispatch, but it now only surveys — verified file paths, whether tests cover the area, whether history holds a precedent commit — which the worker gets as a warm start, the batching layer keys on, and the zero-model lane uses as its patch source. Its result is cached per run, so a retry never re-scouts.
• A periodic supervisor (another cheap fresh session) audits the run and can halt it. Hard-stops land in governor/escalations.md for you.
• It gets better over time. Every resolved ticket promotes its durable lesson into the right CLAUDE.md before the entry is deleted: memory you can read, diff, and edit. Harness improvements accrete in governor/improvements.md (observe → propose → triage; never auto-applied to safety rails), and the hub channel (/shiploop:update / /shiploop:push) moves mechanism fixes between your workspace and the template repo. Always via human-reviewed PR.

Trust

Autonomy is a ladder, not a switch. One knob, GOVERN_AUTONOMY in scripts/lib/workspace.sh, controls it:

What makes the top rung safe to reach for:

• Three-factor merge guard. A PR auto-merges only if its author is the governor's own worker identity, its branch matches the governor's naming, and its head is not from a fork. Any factor missing → stays open for a human.
• Hard-stops. Destructive git, prod data, destructive schema, secrets: the doctrine in governor/preferences.md makes a worker park + escalate instead of acting.
• Bounded blast radius. Workers run claude -p --permission-mode bypassPermissions by design, scoped to a throwaway worktree plus the branch it pushes; .githooks/pre-push rejects any harness-repo push except a sanctioned governor run.
• Fail-closed evidence gates on the self-improvement and sync ports: bash -n, a forbidden-identity-strings gate, and a scaffold-test baseline diff. Any failure escalates instead of merging.

Cost, observed: $3.03 median / $4.49 mean per resolved ticket ($1.34-$12.00 range, N=32 tracked tickets), from Claude Code's own reported cost, not an estimate. See PROOF.md for the full distribution and methodology. That sample predates the current cheap-floor default and skews opus-heavy on self-referential harness tickets, so treat it as an upper bound rather than an average — a sonnet floor observed ~$2.22/ticket. config-check.sh is the only truly free smoke ($0, no auth); scripts/govern/run-loop.sh --dry-run (say "dry-run the queue") runs a real worker in plan mode. Zero side effects, but it costs tokens. For your first run: keep the allowlist empty, watch one ticket end-to-end, and set a spend cap in your Anthropic dashboard.

Commands

bash scripts/doctor.sh warns when your workspace lags the hub by N releases.

Configuration

Everything lives in one file: scripts/lib/workspace.sh. Advanced lanes ship off so a fresh install is inert until you opt in:

Permissions

Hard bounds — how a run is guaranteed to end

CI, retries, and cadence

Binaries

Knobs not listed here (GOVERN_TICKETS_FILE, GOVERN_QUEUE_DIR, GOVERN_LOG_ROOT, GOVERN_LOCK*, GOVERN_TEMPLATE_DIR, and similar path overrides) exist for test and scaffold plumbing. They are overridable but are not tuning surface — treat them as internal.

Requirements

• Claude Code CLI: Act 1 (setup + extract) needs only this, git, and jq
• jq: hard-required; the scaffolder and governor fail closed without it
• gh CLI, authenticated, for the governor (opens PRs, reads CI); not needed for the risk map
• git ≥ 2.20, bash ≥ 4 (macOS's 3.2 also works, templates are guarded for both)

How it compares

Devin, Cursor, Copilot, and Claude Code all do one task you hand them well. shiploop is the layer above: it runs a backlog across a fleet (a manager, not another IC). If your bottleneck is one hard task, use those. If it's a growing queue of small-to-medium changes across N repos, and you'd rather do the spec work than the shipping, use this.

Proof

281 tickets auto-found and resolved on the maintainer's production multi-repo product, of 290 governor-authored PRs merged (0 confirmed reverts). The harness audits, fixes, and releases itself through the same loop. Every governor edge case found in the field ports back into these templates with a regression test, and the hermetic suite goes RED in CI before a breaking change can merge. See PROOF.md for the full sanitized evidence artifact: auto-merge/human-merge split, revert rate, cost-per-ticket distribution, and the exact re-runnable queries behind every number.

Contributing

See CONTRIBUTING.md. Everything the scaffolder installs lives under templates/; the slash commands under commands/; hermetic governor tests under templates/govern/test/ (hub-only — the suite is not installed into a workspace).

License

Apache License 2.0. Includes an express patent grant and a
trademark reservation; redistributions must carry the NOTICE file
and state any changes made. Releases up to and including v1.15.1 were
published under the MIT license and remain available under those terms.