Installing Gantry
Grab the tarball for your platform from the download page, then verify, extract,
and put gantry on your PATH. Pick your platform:
Linux x86-64
sha256sum -c SHA256SUMS tar -xzf gantry-x86_64-unknown-linux-musl.tar.gz install -m 0755 gantry-x86_64-unknown-linux-musl/gantry ~/.local/bin/gantry gantry doctor
Linux ARM64
sha256sum -c SHA256SUMS tar -xzf gantry-aarch64-unknown-linux-musl.tar.gz install -m 0755 gantry-aarch64-unknown-linux-musl/gantry ~/.local/bin/gantry gantry doctor
macOS
A native macOS build is on the way. In the meantime, if you want to experiment, run the generic Linux binary — inside WSL2, a Linux VM, or a container.
gantry doctor is the first thing to run on a fresh box: it checks the tools Gantry needs (git,
the optional sandbox, your harness CLIs) and tells you what's still missing.
Building a plan
Running Gantry is simple: point it at a plan and go.
gantry plan.md
That's it. The same command takes a few launch modifiers, and Gantry can drive a handful of different job types:
Launch modifiers
| command | what it does |
|---|---|
| gantry plan.md --headless | plain line output (cron / remote / piped) |
| gantry plan.md --detach | launch in a session that outlives your shell |
| gantry plan.md --clean | wipe a botched run, then build fresh |
Job types
| command | what it builds |
|---|---|
| gantry plan.md | milestone build — the default |
| gantry --map spec.toml | fan-out map job, one unit per item |
| gantry --loop goal.md | build campaigns until a frozen acceptance check passes |
| gantry --goal goal.md | permanent alias for gantry --loop goal.md |
| gantry --ralph prompt.md | guarded Ralph Loop iterations over one standing prompt |
Goal and loop modes
gantry --loop goal.md builds campaigns until a frozen acceptance check passes.
gantry --goal goal.md is a permanent alias for the same driver. Gantry snapshots the goal command
before agents can edit the repo, verifies it starts amber, then keeps planning and building from
the same goal output until it turns green.
gantry --ralph prompt.md runs the guarded Ralph Loop: repeated fresh agents over one standing
prompt, grounded by tests Gantry runs itself. The canonical form includes goal: front matter;
Gantry snapshots that command before agents can edit it, verifies it starts amber, then loops
until the goal turns green.
test: is the invariant and must stay green. A red iteration gets one repair attempt, then is
reverted and recorded in the audit ledger if it is still red; repeated reverted reds stop as
systemic. Without goal:, loop mode is the open-ended fallback: two verified LOOP_DONE
sentinels or configured quiescence can finish the run.
Successful goal and goal-backed loop completion still requires a read-only run-level review with a usable clean verdict before final merge. Review concerns or review launch/outcome failures stop before merge. Loop runs resume from the next unfinished iteration, replay with amber and iteration progress intact, and support partial merge of committed green iterations.
Managing runs
| command | args | what it does |
|---|---|---|
| gantry list | — | every run: name, state, progress (alias ls) |
| gantry enter | [<name>] | open a shell in a run's worktree |
| gantry status | <name> | title, state, paths, branch, and ledger |
| gantry logs | <name> [-f] | tail the activity journal (-f follows) |
| gantry resume | <name> | resume a run without re-passing its plan path |
| gantry merge | <name> | merge a run's done work to main, leaving it resumable |
| gantry remove | <name> | tear down a run (alias rm) |
Harnesses
Gantry runs any of four coding agents to execute tasks:
gantry --harness-build opencode --harness-review codex plan.md
| id | status | default bin |
|---|---|---|
| claude | default | claude |
| codex | supported | codex |
| opencode | supported | opencode |
| gemini | supported | gemini |
Files Gantry keeps
Gantry keeps a set of files during runs, under .loom/<plan>/ — git-tracked, one directory per
plan, so a run is auditable and resumable:
NN-slug.md— one file per sprint, holding the brief the agent builds.PROGRESS.md— the ledger of what's done; a resumed run reads it to skip finished work.bin/gate— the pass/fail test script Gantry runs itself after every step.logs/,reports/,about.md— per-stage logs, diagnoses, and the project name shown atop the monitor.
Environment settings
| variable | default | meaning |
|---|---|---|
| GANTRY_EFFORT | medium | agent reasoning effort |
| GANTRY_PLAN_EFFORT | high | planning agents' effort |
| GANTRY_NO_PROGRESS_SECS | 1800 | stall window — reap an execute agent that makes no progress for this long; 0 disables |
| GANTRY_TIMEOUT | 14400 | absolute runaway backstop (4h) |
| GANTRY_PLAN_TIMEOUT | 3600 | ceiling for planning stages |
| GANTRY_RETRY_DELAYS | 0,600,3600 | backoff seconds between retries on a transient failure; empty disables |
| GANTRY_USAGE_RESET_MAX_RETRIES | 3 | usage-limit reset-waits to honour before giving up |
| GANTRY_SANDBOX GANTRY_SANDBOX_CMD |
auto / — | agent sandbox mode and custom wrapper |
| GANTRY_WINDOW_TITLE | auto | terminal window-title progress line |
| GANTRY_CONFIG | — | config-directory override |
Troubleshooting
When something goes wrong in a run, drop into its worktree to look around and fix it by hand:
gantry enter <name>
From there you or your agent of choice can inspect the code, run the tests, and resolve the
problem — commonly gantry enter <name> then claude or codex to investigate — then
gantry resume <name> to carry on. In the live TUI, the build-run Gantry Agent is available in the
assistant pane: focus it with Tab, control it from the divider, and hand halted-run blockers to
it without leaving the run.