LoopRail

Summary

A skill is a file of instructions an agent tries to follow. On a long task the model picks the order and the checks, and can quietly skip one. looprail puts that structure in a file a program runs.

The file decides the order: what runs first, which command must pass, how many times a fix may loop, and when to ask a person. Agents do the judgment: writing the code, reviewing it, and deciding what a finding means.

One file runs four ways: in a terminal, in a browser, from a program over JSON lines, or from an agent through MCP tools. A run records what finished, so an interrupted run continues where it stopped.

The file spec is human and agent readable. You don't need a PHD to understand what is happening.

Install

This page covers getting the looprail binary and wiring it into a harness so an agent can run looprails. Its commands are in Command line.

The binary stands alone: a machine that only runs looprails needs no systemd-nspawn, btrfs or Slack.

Get the binary

How

CI builds x86_64-linux. The other two platforms are the release assets.

Latest release

Install LoopRail in ~/.local/bin on Linux or Apple silicon macOS. The installer verifies the download. Add that directory to your PATH to run looprail by name.

curl -fsSL https://looprails.skyg.ca/install.sh | sh

Download LoopRail for your platform below. We plan to open source LoopRail. For now, prebuilt binaries are available here.

SystemBinary
Linux x86_64looprail
Linux arm64looprail
macOS arm64looprail-darwin
ChecksumsSHA256SUMS

Check the download with sha256sum -c --ignore-missing SHA256SUMS, then chmod +x it.

Put it on PATH, with whatever your shell steps run and the harnesses your looprails name: the built-in claude, codex, grok, goose, pi, or one the file adds under [harnesses].

Check it

looprail version   # YYYY.MM.DD-HHMMSS-<short commit> (spec <spec version>)
looprail doctor    # which of claude, codex, grok, goose and pi are installed, and the models they offer
looprail spec      # the index of the looprail file format; looprail spec <page> for one page

Let an agent run looprails

looprail install            # this project
looprail install --global   # your home directory

install:

  • registers the MCP server.
  • writes the looprail skill for each harness below.
  • for Claude Code, also adds a progress hook and a status line (below).

Restart the harness session afterwards. --dir path installs into another project, and --json prints what was written.

HarnessProject configGlobal configSkills folder
Claude Code.mcp.json~/.claude.json.claude/skills/
Codex.codex/config.toml$CODEX_HOME/config.toml.agents/skills/
Grok.grok/config.toml$GROK_HOME/config.toml.claude/skills/
goosenone~/.config/goose/config.yaml.agents/skills/
pi.pi/mcp.json<agent-dir>/mcp.json.agents/skills/
  • Defaults. $CODEX_HOME is ~/.codex and $GROK_HOME is ~/.grok when unset. pi's <agent-dir> is $PI_CODING_AGENT_DIR, or ~/.pi/agent.
  • Grok's entry is a [mcp_servers.looprail] table, as Codex's is.
  • Finding Grok. install writes for Grok only when it finds grok on PATH or its folder ($GROK_HOME or ~/.grok/). Otherwise it says Grok not found, skipped (the skipped list in --json). pi is found the same way (below).
  • Project scope runs looprail from PATH, so start the harness from the project root.
  • From your home directory, a project config can also be the global one: Codex's ~/.codex/config.toml, Grok's ~/.grok/config.toml. install leaves it to install --global, and says so.
  • Global scope runs the binary you installed with. Run install --global again after you move or upgrade it.
  • Existing files are merged. Other servers, keys and comments stay.
  • goose's enabled and timeout stay on an existing looprail entry. A new entry gets true and 300.
  • The CRLF line ends of a Codex, Grok or goose file stay.
  • A file that changes during install, as ~/.claude.json does under a running Claude Code session, is merged again, up to three times. Then install reports it failed.

Claude Code

install also writes .claude/settings.json in the project, or ~/.claude/settings.json with --global, so you see a run's progress without the model reporting it:

A PostToolUse hook runs looprail hook post-tool-use.

  • Its matcher is mcp__looprail__(start_looprail|get_looprail_status|provide_looprail_input).
  • After each of those calls it shows the run's state and one line per step: status, name, elapsed time, model.
  • When the call named no run, it shows a line per active run.
  • It is merged into hooks.PostToolUse beside your own hooks. Every other key stays.

A status line, {"type": "command", "command": "looprail statusline"}, shows the active runs under the prompt.

  • One run: ⚙ single-ticket 3/9 · review (claude-agent-acp sonnet) 2m10s · 160.0k tok · +1231 -123, 42 files read.
  • Several: ⚙ 2 runs: single-ticket 3/9, docs-sync 1/3.
  • None active: nothing.
  • It is set only when the file sets none. In a project, ~/.claude/settings.json must also set none, or looprail's own, because the project's line would hide your global one.

Both run the same looprail as the MCP registration: the bare name in a project, the installed binary's path with --global.

If you already have a status line, install leaves it alone and prints a note. To show both, have your script pass its stdin to looprail statusline too:

#!/bin/sh
input=$(cat)
mine=$(printf '%s' "$input" | ~/.claude/my-statusline.sh)
runs=$(printf '%s' "$input" | looprail statusline)
echo "$mine${runs:+  $runs}"

looprail statusline and looprail hook post-tool-use read Claude Code's JSON on stdin and the run folders, and never call the MCP server. The hook prints {"systemMessage": ...}. On any error they print nothing and exit 0, so they never break Claude Code's prompt or a tool call.

pi

  • Finding pi. install writes for pi only when it finds pi on PATH or its agent folder ($PI_CODING_AGENT_DIR or ~/.pi/agent/). Otherwise it says pi not found, skipped (the skipped list in --json).
  • Exposure. pi's entry gets "exposure": "direct", so the model sees the tools without codemode. An entry that already sets an exposure keeps it.
  • install also writes the looprail pi extension into .pi/extensions/looprail/ (project) or <agent-dir>/extensions/looprail/ (global).
  • Its source is looprail/internal/install/pi/.
  • To load it from a checkout, run pi -e looprail/internal/install/pi.

In pi, the extension:

  • registers the looprail mcp server for the session, unless an mcp.json entry of that name exists
  • shows active runs and their steps above the editor, in at most 16 lines, and counts them in the footer, as in lr: 1 running · 1 needs input
  • follows the runs the looprail tools report, and unfinished runs in the runs folder (LOOPRAIL_RUN_DIR, by default .tmp/agents/looprail/runs) that changed in the last 15 minutes
  • draws start_looprail, resume_looprail and get_looprail_status calls as step tables, and cancel_looprail and provide_looprail_input as one line each
  • tells the model when a run it started or resumed in this session ends, so it need not long-poll get_looprail_status
  • tells you and the model when a run asks a question. The model asks you in the chat, then answers with provide_looprail_input
CommandWhat it does
/looprailLists the project's runs (looprail runs --json), to pick one and act on it.
/looprail start [looprail]Picks a looprail and asks for its inputs.
/looprail answer [run]Opens a dialog to answer a question. No dialog opens by itself.
/looprail resume <run>Resumes a run.
/looprail cancel <run>Cancels a run.
/looprail details <run>Opens the step table and the end of the running step's log: its stderr, result and output records.
  • A pi command can't call an MCP tool. So /looprail start, resume, cancel and the answer dialog ask the model to make the call.
  • The MCP server is pi's child process. When pi exits, the server stops its runs.
  • Each run keeps its checkpoint, its record of what finished. /looprail resume <run> in a new pi session continues it.
  • The server's tools are in the MCP reference.

How a looprail runs

A complete looprail is one TOML file. This one formats a folder, then has an agent check the result. The agent's prompt is its brief, briefs/check.md, which asks for a verdict of clean or dirty.

[metadata]
spec_version = "0.1.0"
name = "tidy"
description = "Formats a folder, then has an agent check the result."

[inputs.static]
target = { type = "string", description = "The folder to tidy.", min_length = 1 }

[[step.format]]
kind = "shell"
description = "Runs the formatter over the folder."
run = ["gofmt -w {{ inputs.target }}"]

[[step.check]]
kind = "agent-gate"
description = "An agent reads the change and accepts it when it is clean."
needs = ["format"]
agent = { command = ["claude-agent-acp"], model = "sonnet" }
brief = "briefs/check.md"
accept = "clean"
  • The file lists its inputs, each with a type. A run asks for any that are missing and checks them all before anything runs.
  • Each step has a kind. needs names the steps it waits for, and that sets the order, not the position in the file.
  • A step can declare outputs. Later steps read them in templates, in when, and in for_each, which runs a step once per list item.
  • A gate passes or rejects. A rejected gate can send the run back to an earlier step with on_fail, up to max_loops times.
TermMeans
GateA step that passes or rejects the work.
HarnessThe agent program looprail starts, such as Claude Code or Codex.
ACPAgent Client Protocol, how looprail talks to a harness.
MCPModel Context Protocol, how an agent calls outside tools.
CheckpointA run's record of what finished.

Ways to run one

Every mode runs the same file through the same code. The difference is who answers its questions.

ModeCommandWho answersUse it for
Terminallooprail run tidy.tomlYou, under a live list of steps.Running a looprail by hand and watching it.
Browserlooprail run --web tidy.tomlYou, on the page it opens.Running by hand with the graph in view, or with no terminal.
Programlooprail run --std tidy.tomlThe program, in JSON lines.A program that drives runs.
Agentlooprail mcpThe agent, through the MCP tools.An agent that starts, watches, answers, cancels and resumes runs.
  • With --std, events are JSON lines on stdout and replies are JSON lines on stdin. PROTOCOL.md lists them.
  • With looprail mcp, the agent calls the tools in MCP.md. A run it started stops on its own soon after the server dies.
  • To find errors before a run, use [validate](cli.md#validate) or [doctor](cli.md#doctor). No step runs.

In a terminal

run without --std, --web or --web2 is the terminal UI. It needs a terminal on stdin and stdout, and a looprail file, and exits 2 otherwise.

  • It first asks for each static input that is missing or wrong.
  • If the run folder holds a checkpoint and you passed neither --continue nor --fresh, it asks whether to continue.
  • During the run you see the step list, a pane following the running step, and any question at the bottom.
  • The title line shows tokens and what the agents changed and read, as in changes: +12 -3, 4 files read. The counts come from their tool calls, not git.
  • Ctrl-C stops the run. If a checkpoint was kept, it prints the command that continues it.

In a browser

run --web runs the looprail from a page in your browser. It takes run's flags and arguments and needs no terminal. --web with --std is exit 2.

  • It serves on a free port of 127.0.0.1, and prints the address on stderr.
  • --addr picks another port or address, for this machine only: 8080, :8080, localhost:8080 or [::1]:8080.
  • An address other machines could reach, such as 0.0.0.0:8080 or a LAN address, is exit 2.
  • It opens the page as [render](cli.md#render) does. If nothing opens it, it says so and keeps serving.
  • The address holds a random token, and the server refuses a post from another site. So only a page on this machine that knows the address can answer.
  • Commands' output goes to stderr, as with --std.
On the pageWhat it is
QuestionsAt the top of every view: missing inputs, questions from steps, and whether to continue from a checkpoint. Several can be open at once.
GraphThe opening view, with Follow live on: the steps, a searchable list, and each step's output from its log records, files, tokens and attempts.
OverviewOpen questions first, then the work grouped by top looprail step and by state.
Failure modalThe error, the summary, and a button per choice. Click a failed box, or Answer the failure, to open it.
KeysOn desktop: the arrow keys or j and k move between steps, Esc goes back to the graph, and / filters.
  • A step keeps its first attempt and its latest four.
  • A step's Files lists stop at 200 entries and say how many they left out.
  • A link such as #step-w.ci opens a step.
  • A reloaded page gets the whole state, then live changes. That holds the run's last 10 log records, and each new one comes as a record event.
  • Every record the server sends, in the state, a record event or a search page, is the log record's keys plus id, a string. One record has the same id on every route, and no two records of a run share one, those of nested run folders included. The log files hold no id.
  • GET <address>search gives a page of the run's log records, read from the run folder's logs/. It takes:
ParameterMeaning
qText found in the record's text, whatever its case.
stepThe step, or anything inside it.
item, loopA number: the records whose item or loop is it.
source, kindOne value or several split by commas. A leading ! makes it every record but these, as kind=!step,stderr.
limit1 to 1000, 100 by default.
before, after, aroundAt most one, a record id: the matches older than it, the limit matches just newer than it, or the matches around it, about half each side, the record among them when it matches.
count1 asks for the count of matches.
  • The answer is {"records": [...], "before": "...", "after": "..."}, with "count" and "capped" when asked. The records are newest first.
  • before is the id of the page's oldest record and after that of its newest, each "" when no match lies beyond. Passing them back walks the matches both ways with no gap and no repeat.
  • count is how many records match in the whole run, whatever the page. The server stops counting at 10000 and then says capped: true.
  • Two of before, after and around, a value that is no record id, or an item, loop or count that is not a number is status 400 with {"error": "..."}.
  • GET <address>search/events takes q, step, item, loop, source and kind the same way, and sends each new record it matches as a record event.
  • When the run ends, looprail waits up to five seconds for open pages to get the last event. Then it exits with the run's exit code.
  • Ctrl-C stops the run and keeps its checkpoint.

run --web2 takes what --web takes and works as it does, on a page in the new design. [render --v2](cli.md#render) describes that design. --web2 with --web or --std is exit 2.

On the --web2 pageWhat it is
QuestionsAt the top of both views: the inputs form, a step's question, and whether to continue from a checkpoint.
LineThe opening view: each stop's state, the stop the run is at, its runs, and a for_each step's rows, as Line, live says.
TrailA panel beside the Line with the run's log records grouped by step run, each group under a header, nested as the Line nests. A quiet group folds and a running, asking or failed one stays open, by the Line's own rules. A for_each folds its quiet items into one line, and a send-back is a divider before the next run. It follows the run live until you scroll up, and a pill counts what is new. A jump bar reaches each failure and send-back, and a crumb scopes it to a node. Clicking a row or a header opens its node on the Line. Its search looks through every record of the run, not only those the page holds, within the scope, and says which hit of how many it shows. A flat toggle shows the plain chronological table instead, with the time, type, step.kind, step.name, step.id, inputs and text, all seven at 640 px or wider. Drag its edge to resize it on a desktop; on a phone it is a bottom sheet.
Trail keysOn the Line, outside a field: / searches, Enter confirms, n and N walk the hits, and Esc clears the search, then the selection. j and k move the selection, gg and G go to the top and the bottom, and G follows the run again. o or Enter opens the selected row's node, [ and ] move between groups, za folds or opens one, and t collapses or opens the panel. A desktop lists them at the panel's foot.
GraphEach step's state on its shape, a box per for_each item, and the step list.
Step detailA step's output from its log records, outputs, tokens, files and attempts.
Failure modalThe error, the summary, and a button per choice.
ThemeThe light and dark switch, as on render --v2's page.

From an agent

looprail mcp is the MCP server. Installing looprail registers it with a harness.

  • start_looprail answers with a run id at once, without waiting for the run.
  • Each looprail is also its own tool, [looprail_<name>](../looprail/MCP.md#looprail-tools).
  • A client that declares them gets two optional layers: runs as tasks, and two HTML apps.

Answering a failure

When a step fails and neither on_fail nor failover = "agent" handles it, the run asks a person. The rules are in Failure. This section is how each front end shows the question and takes the answer.

  • The question appears as question on --std, as the page's request, and in get_looprail_status.
  • It holds the error, the end of a failed command's output, the path of the failed step run's log folder (see the logs), a summary and your choices.
AnswerSendIn the terminal or on the page
retry{"action": "retry", "text": "<feedback>"}Retry Step. They send no text.
skip{"action": "skip"}Its button.
stop{"action": "stop"}, or the plain text stopIts button.
feedback{"action": "feedback", "text": "<what to tell it>"}feedback: <text> in the terminal.
ask{"action": "ask", "text": "<question>"}ask: <text> in the terminal.
  • The page's buttons each post {"id", "action"}.
  • The agent's answer to an ask comes back in the next question's reply.
  • If a fix, an ask or a feedback fails or times out, session_error says so and you are asked again. The step does not run again.
  • A fix's prompt and reply go in fix-<n>/, and an upstream agent's summary prompt and reply in summary-<n>/.

Changing a step for one run

--set changes a step for one run without editing the file. Repeat the flag as needed.

FormChanges
--set <step> model=<model>,command=<command>,idle_limit=<limit>An agent step's harness, model or [idle_limit](spec/kinds/agent.md)
--set <step> env.NAME=valueOne variable of the step's env
--set @<agent> model=<model>,provider=<provider>,command=<command>,llm=<index>,config.<option>=<value>Pins a named agent for the whole run

Examples: --set code idle_limit=10m, --set '*' idle_limit=unlimited, --set @coder llm=1.

  • * is every agent step. A step named on its own wins over *.
  • A command with a space in an argument is a JSON array: command=["my agent","--flag"].
  • env.NAME comes last in its --set, because the value may contain a comma. Each variable takes its own flag.
  • PATH, PWD and names starting with LOOPRAIL_ are refused.
  • A step that names a named agent takes no model or command of its own.
  • looprail validate --set ... checks the sets without running anything.
  • The checkpoint does not record the --sets, so a continue may pass different ones.
  • looprail writes no env.* value into the run folder.

Limits across runs

All runs in your home share a limit per step kind, whoever started them. A looprail's own [[limits]](spec/limits.md), or --limit, also cap its run.

KindsAt once
agent, agent-gate30
shell, shell-gate10 per CPU
mcp50
api, decision-model50
  • A step whose kind is full waits for a slot and says so on stderr.
  • No run is refused for the number of runs.
  • --kind-limit kind=N, repeatable, sets a kind's limit, for run and mcp.
  • Slots are lock files under ~/.looprail/slots/<kind>/, so a run that dies gives its slots back.

Agent steps during a run

How an agent step is written is in Agents. This section is what looprail does around the harness while it runs.

  • If the harness does not offer agent.model, the step asks a person which model to use.
  • looprail allows every tool call the harness asks about.
  • The harness gets looprail's environment, with the step's env merged over it, then LOOPRAIL_CURRENT_RUN_DIR.
  • Shell steps' output goes to the run folder and, with --std, --web or --web2, to stderr. It never goes to stdout.
  • A looprail step's steps are named <looprail step>[<item>]/<step> on stdout. Answer such a question by that name or by its id.

Usage limits

A usage or rate limit fails the step with the outcome limited. on_fail does not loop on it, and the step goes to its failover. A turn is limited when:

  • the harness's error has the errorKind rate_limit, overloaded, billing_error or account_on_hold, or
  • its message starts with API Error: 429 or API Error: 529, or
  • its last line starts like a limit notice, such as You've hit your limit.

The last case applies to an error with no errorKind, and to a turn with any stop reason except refusal, end_turn included. claude-agent-acp sends a 529 with the kind server_error. An error that only mentions a 429, a quota or a rate limit further in is still a crash.

Background tasks

What a step does while a background task runs is in [agent steps](spec/kinds/agent.md#background-tasks). On the wire:

  • looprail declares the AIR asyncTasks capability, as _meta.jetbrains.air in the client capabilities.
  • A harness that advertises it back, as claude-agent-acp does, reports what it runs in the background.
  • While the step waits, the step event's waiting says why.
  • The step's idle_limit is 1h by default, and may be unlimited.
  • looprail does not declare backgroundSubagents. So a background subagent still holds session/prompt open until it settles.

Limiting agents from outside

Two variables in looprail's own environment limit agent steps. A step's env can't set them. A program that starts runs can.

VariableHolds
LOOPRAIL_MODELSA comma-separated list of the only models agent steps may use. Unset, every model is allowed.
LOOPRAIL_MCP_SERVERSA JSON array of stdio MCP servers every agent session gets, each {"name", "command", "args", "env"}.
  • A step on a model that is not listed fails before its harness starts.
  • A step that names no model gets the first on the list.
  • A model a person picks must be on the list too.
  • A server's env names variables of looprail's environment to pass on, so their values stay out of the array.

The runs folder

LOOPRAIL_RUN_DIR names the folder that holds every run's folder.

  • Unset or empty, it is .tmp/agents/looprail/runs.
  • A relative value is relative to the working directory.
  • Each run gets <LOOPRAIL_RUN_DIR>/<looprail file name>-<hash>. The hash also covers the working directory.
  • A looprail step's looprail gets its own run folder.
  • run, runs, runs resume, status by run id, statusline, hook post-tool-use, mcp and the pi extension all look for runs there.

Set it to an absolute path and every project shares the folder.

  • runs and statusline then show all their runs.
  • runs resume, status --web and status --web2 find a run's project from its state.json.
  • An mcp server lists only its own project's interrupted runs. A global one, with --global, lists them all.

What a run folder holds

PathHolds
state.jsonThe looprail, the folder it started in, its hash, the inputs, and every step's status. Replaced after every change.
logs/Every log of the run, as JSONL records. The logs say how it is laid out.
steps/<step>/<loop>/That run of the step: its outputs, and the run folder of a looprail step.
checkpoint.jsonWhat finished, for --continue.
previous/<started>/The record of an earlier run in the same folder.

Each run of an agent step writes these into its steps/<step>/<loop>/:

FileHolds
prompt.md, reply.mdWhat the agent was sent and what it answered.
usage.jsonThe tokens it spent.
failure-summary.mdThe summary of a failure, when one was written.

The logs

Everything a run says while it works is a record in logs/: a line of JSON in a numbered file. No other file holds a log.

logs/
  0001/                        a session: a start of the run
    looprail/000001.jsonl      the run itself: step events, questions, answers
    code~0/000001.jsonl        a step run: <step>~<loop>
    review~1~3/000001.jsonl    a for_each item: <step>~<loop>~<item>
  0002/                        the next session, from --continue
  • A step's retries and its failover write to the log of the same step run. A summary or fix session's records go to the log of the agent step whose session answers.
  • A looprail step's run has its own logs/, in its own run folder. The readers show its records with the parent's, with the step names prefixed, as in checks[1]/probe.
  • A file closes at 100,000 lines or 10 MiB, and the producer goes on in the next number.
  • seq orders the records of a run folder, across sessions, producers and files.

Every record has these twelve keys. An empty value is "", 0 or null; no key is left out.

KeyHolds
vThe format version, 1.
seqThe record's place in the run folder, rising.
atWhen it was written, in UTC.
sessionWhich start of the run wrote it: 1, 2, …
sourceWho it comes from: looprail, agent, harness, shell, api, mcp or human.
kindWhat it is, from the next table.
stepThe step's name, "" for the run itself.
loopWhich loop of the step.
itemThe for_each item, or null.
blockTies together the records of one thought, message, call or failed output.
textThe readable line: what a front end shows and search matches.
dataThe kind's extra fields, or null.
KindIs
stepA step event from looprail: its status, tokens and changes.
question, answerWhat looprail asked, and what a human answered.
thought, messageA piece of an agent's thinking or message.
call, resultA call starting, and ending: an agent's tool, a shell command, an api request or an mcp tool.
outputA piece of the output of a failed call.
fileA path an agent read or edited.
taskAn agent's background task update.
stderrA line of the harness's own output.
  • A shell step writes a call record before each command and a result record after it. The output of a call is kept only when the call failed, as output records sharing one block. A call that passed leaves its call and result records.
  • A secret is hidden in every record, as in every other output: the value of a variable a step or session is given shows as [env.<NAME>].
  • A failed step's error ends with the path of the step run's log folder, such as logs/0001/code~0 in the run folder.

Checkpoints

A checkpoint is the run's record of what finished. An interrupted run continues from it, and a run that passes removes it. checkpoint.json records:

  • the looprail's hash and spec_version,
  • the hashes and spec versions of the files it runs,
  • the hashes of the briefs it reads,
  • the static inputs,
  • what finished in each step.
Flag of runWhat it does
--continueSkips what the checkpoint marks finished. A step that was still running runs again from where it stopped. An agent step starts a new session, and the logs a new session folder.
--force, with --continueContinues even when the looprail, a brief or the inputs differ, and prints what differed.
--redo <step>, with --continueRuns that step, and every step that needs it, again.
--freshStarts from the first step and moves the old record, logs/ included, into previous/.
  • Without --force, a difference is exit 2, before any step.
  • When a file moved to another spec version, --continue names both: the looprail changed from spec 0.1.0 to 0.2.0 since the checkpoint.
  • --continue and --fresh cannot be passed together.

Listing and resuming runs

runs lists the run folders in the runs folder, newest first. runs resume continues one that has a checkpoint.

  • Name the run or a prefix of it. With no name, at a terminal, runs resume asks you to pick.
  • At a terminal, runs opens a list titled with how many runs it shows, such as Runs (7 of 42) · state: failed · sort: started ↓.
  • Each input takes one line of the table, its value cut to 100 characters. A run's page shows it in full.
  • A search looks in each run's id, looprail, file, state and full input values. It ignores case unless it has an uppercase letter.
  • runs resume's run picker searches the same way.
KeyDoes
/, ?Search forward or back as you type. Enter keeps the match, Esc goes back.
n, NRepeat the search, wrapping around the list.
fCycles the state filter: all, unfinished, passed, failed, resumable.
s, SCycles the sort (started, looprail, state, run), or flips its direction.
uRereads the runs, keeping the search, filter and sort.

Watching a run

status reads a run's folder, so it needs no running process and never answers a question. Name the run by its folder, with --dir, or by its id, as looprail runs lists it.

CallDoes
statusPrints the step list from state.json.
status --jsonPrints the record and the checkpoint.
status --watchFollows the run from any terminal, for a harness such as Zed that shows no progress. It prints the log records too.
status --webServes the browser page for a run started elsewhere, such as through looprail mcp.
status --web2Serves run --web2's page, in the new design, the same way.
  • --watch updates about once a second. At a terminal it shows the run's last 10 log records under the steps, one line each: time, step, source and kind, and the first line of the text. Away from a terminal it prints one line per change.
  • --watch exits 0 when the run passed, 1 when it failed, and 2 for a wrong invocation or a folder it cannot read. --web and --web2 exit the same way.
  • Ctrl-C stops watching, with exit 130, and never stops the run.
  • --web and --web2 read the run folders and their logs/ about once a second, without the run's lock. So the page shows every step change and every record, the records as its trail and as live lines of their steps, for a run that goes on or one that finished. Its search reads the older records from logs/.
  • On --web and --web2, a for_each step's rows have no item names, and an item is timed only from when the page read its records.
  • --web and --web2 take --addr as run --web does. Either with the other, --json or --watch is exit 2.
  • Answer a question where the run was started.

Runs whose process died

  • looprail run holds run.lock while it writes the record.
  • looprail mcp holds mcp.lock while a run's child process lives.
  • A record with no exit code and neither lock held belongs to a process that died.
  • status --watch then says so, prints the command that continues the run, and exits 1.
  • looprail mcp lists the run as interrupted.

Commands

looprail run [--std | --web | --web2 [--addr address]] [--continue [--force] [--redo step]... | --fresh] [--limit key=N]... [--kind-limit kind=N]... [--set step|*|@agent key=V,...]... [--dir path] [looprail] [inputs-json]
looprail doctor [--json] [--set step|*|@agent key=V,...]... [looprail]
looprail validate [--json] [--set step|@agent key=V,...]... looprail
looprail render [--v2] [--raw | --out file] [looprail|folder]
looprail list [--json] [--dir path] [--global]
looprail status [--json | --watch | --web | --web2 [--addr address]] [--project path] [--dir] <run folder | run id>
looprail runs [--json] [--dir path]
looprail runs resume [--std] [--force] [--redo step]... [--dir path] [run]
looprail mcp [--dir path] [--global] [--kind-limit kind=N]...
looprail install [--json] [--dir path] [--global]
looprail statusline
looprail hook post-tool-use
looprail spec [<page> | --all | --json]
looprail version

looprail help <command>, or --help, lists a command's flags.

CommandDescribed in
run, mcpRunning a looprail
runs, runs resume, statusThe run folder
install, statusline, hook post-tool-useInstalling looprail
the restthis page

Arguments of run

Flags and the two arguments can come in any order.

  • An argument that starts with { is the inputs, and the looprail is read from stdin. - also means stdin.
  • A looprail read from stdin uses up stdin, so in --std mode nothing can answer a question.
  • looprail run checks runs a looprail by name. It looks for that file name or name in the project's .agents/looprails and in the home's.
  • A name is an argument with no folder, no .toml or .json ending, and no such file in the working directory.
  • If both folders have the name, run asks which, and --std fails at once.

Exit codes

Exitrunvalidatedoctor
0Every step passed or was skipped.The file and every file it runs are valid.Every harness and model checked out.
1A step failed and the file sent it nowhere else.A harness or model failed.
2The invocation or the file was wrong, or the run could not start.The file or a file it runs is not valid.The invocation or the file was wrong.
Exitmcpinstallspec
0Stdin ended.Every file was written or already right.Printed.
1The session failed.A file could not be merged.It could not print.
2The invocation was wrong.The invocation was wrong.No such page, or the invocation was wrong.

Any other command exits 0 when done, and 2 when the invocation was wrong or a folder that exists could not be read. render and status have their own rules, below and in The run folder.

validate

validate <looprail> loads the file and every file its looprail steps run, and lists every error by field. Nothing runs.

  • --set, for steps and @agent, is checked against the file, and its errors are listed too.
  • --json prints each error with field, message and the rule it breaks. The rules are in the spec.
  • A valid file that sets a deprecated field gets a warning line and still exits 0. An example: warning: step.x.foo is deprecated since 0.3.0 (LRP-0007); use bar.
  • A warning for a file a looprail step runs starts with that file's path.
  • With --json the warnings go to stderr.

list

list shows the looprails in <dir>/.agents/looprails and in ~/.agents/looprails.

  • --global shows only the global ones.
  • A file that does not load is listed with its errors. The command still exits 0.
  • A name more than one file has is marked as a clash.
  • --json gives each input in the shape of a --std inputs field.

doctor

doctor checks that the harnesses and models a looprail names can start. It runs no step, and exits 1 when a line fails.

  • With a looprail, it validates the file and applies any --set. Then it starts each harness and model the file names, and checks the model is offered.
  • With none, it checks the five built-in providers: claude-agent-acp, codex-acp, grok agent stdio, goose acp and pi-acp.
  • A harness that is not installed is not a failure. One that is installed and does not start is.
  • It says whether nix and nix-shell are on PATH. A missing tool never fails doctor. They are the tools of [enable_nix](spec/file.md#the-nix-dev-shell).
  • It warns of deprecated fields as validate does. With no looprail, it reads the project's .agents/looprails. A warning never fails doctor.

--json prints the same checks as one object, including the models a step could switch to.

  • harnesses lists the built-in providers, then each harness the file names.
  • nix has one entry per tool, with tool, found and, when found, path.
  • Fields may be added later. None is renamed or removed.
  • An empty array is [], never null.
  • The warnings go to stderr.

render

render draws a looprail, and every looprail it runs, as one HTML page that needs no network. Use it to read a looprail without running it.

FlagsWhat it does
noneWrites looprail-<name>-*.html to the temp dir, prints its path and opens it.
--rawPrints the page to stdout. Writes and opens nothing.
--out <file>Writes the page to the file. Opens nothing.
--v2Draws the new design, described below. It works with --raw, --out, a file or a folder. Without it the page is the one above, which run --web also serves. run --web2 serves this design live.
  • The page opens with $BROWSER, else xdg-open (Linux, with a display) or open (macOS). If none opens it, render serves it on http://127.0.0.1:<port>/ until Ctrl-C.
  • The page has an Overview and a Graph. Without JavaScript it shows every step's card.
  • Picking a step shows what it reads and writes, its needs, when, for_each and on_fail, and its brief with {{ }} references as written.
  • The address names the step, so you can link to it.
  • --raw and --out together are exit 2.
  • A file that does not load prints validate's errors on stderr and exits 2, before anything is written.

Given a folder, render draws its .toml and .json files on one page, with an index and a picker (--v2: a chooser).

  • Subfolders are left out. The page is named after the folder.
  • A file that does not load is listed with its errors, which also go to stderr.
  • It exits 0 when at least one looprail rendered. It exits 2 when none did, or the folder holds no looprail file.
  • With no argument, it draws the current directory's .agents/looprails, and exits 2 when there is none.

render --v2 draws the same looprails in an autumn palette, with a Line and a Graph view.

  • Shapes. Each kind of step has a look of its own: an agent is a box with a cap and an eye, a shell-gate is a shield, an agent-gate wears a shield badge, and the inputs are a door. Clicking the door opens it to list the inputs' names, and the graph makes room for it.
  • Line. A looprail opens on its Line view (#<looprail>~line), drawn top to bottom as a rail.
  • Steps that each need only one step, and that the next step joins again, run as lanes side by side. A step with an on_fail path stays on the main line, so its path has the gutter.
  • on_fail paths run in a gutter on the left, one lane each, the shortest innermost, so nested paths never cross.
  • A looprail step opens in place, or is gone into, with crumbs back up. An agent's brief opens in a sheet.
  • A for_each step is tagged "repeats per item".
  • Line, live. On run --web2 and status --web2 the Line also shows the run.
  • A for_each stop opens downward into a row per item, once the run reported the step's list. Before that it shows no count and no rows, and a count has a total only once the list is known.
  • A plain step's row is the item's label, state, time and last line. Clicking it opens the item's stream.
  • A looprail step's row is the item's label and a small track of its run's steps, each the small shape of its kind in its state, with the step that runs named. A nested for_each shows its count of items passed. A stop on the track opens that step's detail, and the label opens the item's own line in place, to any depth.
  • A list of more than 8 items folds what passed and what waits, and puts what asks, failed or runs first. More than 12 get a filter. A stop that is done with nothing amiss folds its rows.
  • Every stop and row has an In and out button: a stop's inputs and outputs, an item's each value and outputs, a looprail item's run inputs and what it gave back.
  • A gate that sent the run back says once why and where to, and how often against its max_loops. Its on_fail path is drawn solid and marked taken, and a path never used is faint.
  • A stop that ran again has a switch of its runs, each by the engine's number for it. An earlier run shows its items, rows and log as they ended. The server keeps a stop's first run and its latest five, and the switch says how many it dropped. A run a send-back cut short while it ran is not kept, and the stop says so. A run that never started, as one that waited for a slot or was skipped, is not shown.
  • A loop back inside an item's run shows on its track as an arc with a count, and on the row and the stop above it, naming the item.
  • Margin notes show each stop, row, nested stop and open mini-stop's newest one to three log records beside it: a call and its result on one line, a thought as its growing last line, a failure's output as its first line in red. A parent rolls up the newest line from inside it, with a short path such as …/zone b/probe, and a fold rolls up the rows it hides. A settled node shows one summary line, such as 14 items · 25 calls · ✗1 on try 1, then ✓ · 19s. Clicking a note line opens that node's stream, failed output or files.
  • The notes sit in the margin right of the Line column, which narrows to 600-720 px for them, while the Line pane is at least 900 px wide. On a narrower pane, as when the trail is dragged wide or on a phone, they drop under their nodes. While they show, an item row's own last line is hidden.
  • The Notes button in the Line's header turns the notes off and on, and the browser remembers the choice in localStorage, as looprail-notes. Whether they show or not, a node's shape pulses once for each new record in it.
  • The notes and the trail point at each other. Clicking a note line also selects its record in the trail, fetching it and opening its episode when they are not on the page, and the line stays marked. On a phone the tap opens the node's details and sets the sheet's peek bar to that episode, and leaves the sheet as it was. With a mouse, hovering an episode or a row rings its node on the Line, or the nearest node drawn above it, and lights its note, and hovering a node, a note or a note line lights its episode and row. Each note, even a node's with no records yet, has a ⟩ that scopes the trail to that node.
  • Chooser. On a folder's page, the looprail's name in the header opens a list of every looprail, with a search box. Names that match come first, then descriptions, then what the steps and their briefs say.
  • Theme. The sun or moon button switches between light and dark. The page starts from the device's theme and remembers the choice in the browser's localStorage, as looprail-theme.

spec

spec prints the looprail file format. The MCP tool get_looprail_file_spec serves the same pages.

CallPrints
specThe index, which says what a looprail is and names every page.
spec <page>That page, such as kinds/api.
spec --allEvery page as one document.
spec --jsonThe format as a JSON Schema.

The error for a page that does not exist names the pages.

version

looprail version prints the version and the spec version the binary reads, as 2026.11.18-211747-f971f89 (spec 0.1.0).

  • The version is YYYY.MM.DD-HHMMSS-<short commit>, from the commit's UTC time.
  • A Nix build of a tree with uncommitted changes ends in -dirty.
  • A plain go build prints dev in place of the version.
  • Static and live HTML pages show the version at the top right.

The format

A looprail is a file that looprail runs, in TOML or JSON.

  • It holds named steps: a shell command, a gate, an agent, a decision model, a question for a person, an HTTP request, an MCP tool call or another looprail.
  • Steps run in the order their needs give.
  • Each passes typed outputs to later steps.

This is spec 0.1.0, which looprail version prints. A binary loads files of its own major with a spec_version no higher than its own: see Versions.

About these pages

These pages are generated from the code:

  • Field tables come from the structs a file decodes into.
  • Kinds and types come from the code's own lists.
  • Every example was loaded by the real loader.
  • Every loader check is a load rule, with an example that breaks it.

The JSON Schema

  • looprail spec --json prints the format as a JSON Schema, for editors and validators.
  • It is committed as [looprail.schema.json](../../looprail/looprail.schema.json).
  • Its $id is looprail-<major>.schema.json, now looprail-0.schema.json. The spec's major picks it, not the file's name.
  • A file the schema accepts can still fail to load: see What the schema can't check.

Changing the format

  1. Write the proposal.
  2. Change the code.
  3. Change the descriptions, page templates and examples in internal/docgen/specdoc.
  4. Run go run ./cmd/looprail-gen from looprail/.
  • Never edit a page by hand. The generator writes every page and removes those it no longer writes. Tests fail on a page that differs.
  • A new load check needs a rule and an example that breaks it: see Load rules.

A first looprail

The smallest looprail: one shell step. (smallest) Loads.

[metadata]
spec_version = "0.1.0"
name = "hello"

[[step.hello]]
kind = "shell"
description = "Prints a greeting."
run = ["echo hello"]

Inputs, a derived input, an agent, a review gate that sends its findings ahead, and a person at the end. (change) Loads.

[metadata]
spec_version = "0.1.0"
name = "change"
description = "One change, coded, reviewed and fixed."

[inputs.static]
issue = { type = "int", description = "The issue.", min = 1 }
slug = { type = "string", description = "The slug.", min_length = 1, max_length = 40 }

[inputs.derived]
branch = "feature/{{ inputs.issue }}/{{ inputs.slug }}"

[limits.agent.claude-agent-acp]
max_parallel = 2

[[step.branch]]
kind = "shell"
description = "Makes the branch for the change."
run = ["git switch -c {{ inputs.branch }}"]

[[step.code]]
kind = "agent"
description = "An agent fixes the issue on the branch."
needs = ["branch"]
agent = { command = ["claude-agent-acp"], model = "opus" }
brief = "briefs/code.md"
failover = "agent"

[step.code.outputs]
summary = { type = "string", description = "What the agent changed, in a sentence or two.", min_length = 1 }

[[step.review]]
kind = "agent-gate"
description = "An agent reviews the change, and accepts it when nothing needs fixing."
needs = ["code"]
agent = { command = ["claude-agent-acp"], model = "sonnet" }
brief = "briefs/review.md"
accept = "accept"
on_fail = "fix"
max_loops = 3

[step.review.outputs]
findings = { type = "list", description = "What needs fixing, one item per problem.", items = { title = { type = "string" }, body = { type = "string" } } }

[[step.fix]]
kind = "agent"
description = "An agent fixes one finding."
needs = ["review"]
for_each = "{{ steps.review.outputs.findings }}"
agent = { command = ["claude-agent-acp"], model = "opus" }
brief = "briefs/fix.md"

[[step.merge]]
kind = "human"
description = "Asks a person whether to merge."
needs = ["fix"]
when = "{{ steps.review.accepted }}"
ask = "Merge {{ inputs.branch }}? {{ steps.code.outputs.summary }}"

briefs/code.md:

Fix issue {{ inputs.issue }} on the branch {{ inputs.branch }}.

briefs/fix.md:

Fix this finding: {{ each.title }}

{{ each.body }}

briefs/review.md:

Review the change for issue {{ inputs.issue }}: {{ steps.code.outputs.summary }}

Proposals and migrations

  • Proposals. Every format change is a numbered proposal, an LRP. Proposals lists them with their status.
  • Migration guides. Each breaking version will have one, listed in Migration guides. 0.1.0 is the first version, so none has one yet.
  • The 0.1.0 record. LRP-0002 to LRP-0023 record 0.1.0, one part each. Every field and kind links its LRP, and every page ends with the LRPs behind it.
  • Changelog. The Changelog lists the LRPs each spec version implemented.
  • Printing. looprail spec proposals/0001 prints a proposal, looprail spec migrations/<version> a guide.

Pages

To readCommandOver MCP
This indexlooprail specget_looprail_file_spec, or the resource looprail://spec
One pagelooprail spec <page>, as looprail spec kinds/apiget_looprail_file_spec with page, or the resource in the page's row
All pages as one documentlooprail spec --all
PagepageResourceWhat it holds
The filefilelooprail://spec/fileThe top level of a looprail file, its [metadata] table and spec versions, its [config] table, its JSON form, and how errors name fields.
Inputsinputslooprail://spec/inputsThe static inputs a caller passes, and the derived inputs worked out from them.
Typestypeslooprail://spec/typesThe types of inputs, outputs and list items, their bounds and their descriptions.
Stepsstepslooprail://spec/stepsThe fields every step shares, needs, and the kinds at a glance.
[agent steps](#agent-steps)kinds/agentlooprail://spec/kinds/agentStarts agent, sends the brief as the prompt, and takes its outputs from the JSON object the last message ends with.
[shell steps](#shell-steps)kinds/shelllooprail://spec/kinds/shellRuns run, each command through sh -c.
[agent-gate steps](#agent-gate-steps)kinds/agent-gatelooprail://spec/kinds/agent-gateAn agent that judges and changes nothing.
[shell-gate steps](#shell-gate-steps)kinds/shell-gatelooprail://spec/kinds/shell-gateRuns run like a shell step, and passes, with accepted set, when every command exits with a code in accept_exit.
[decision-model steps](#decision-model-steps)kinds/decision-modellooprail://spec/kinds/decision-modelAsks the decision model that decision-model names the questions about state.
[human steps](#human-steps)kinds/humanlooprail://spec/kinds/humanAsks a person ask, offering choices when it has them.
[api steps](#api-steps)kinds/apilooprail://spec/kinds/apiSends one HTTP request to url, with method, headers and body.
[mcp steps](#mcp-steps)kinds/mcplooprail://spec/kinds/mcpCalls tool on an MCP server, reached at url or started with command, with arguments.
[looprail steps](#looprail-steps)kinds/loopraillooprail://spec/kinds/looprailRuns the looprail file looprail as one node of this one, once, or once per item with for_each, and passes when every run of it passes.
Agentsagentslooprail://spec/agentsInline agents, named agents, llm rows and harnesses.
Briefsbriefslooprail://spec/briefsThe file an agent step's prompt comes from, and how a changed brief stops a run from continuing.
Outputsoutputslooprail://spec/outputsWhat a step sets for later steps to read, and how each kind sets it.
Referencesreferenceslooprail://spec/referencesReferences in templates, when and for_each.
Shell quotingshell-quotinglooprail://spec/shell-quotingHow a reference becomes one word of a shell command, and the forms that fail.
Failurefailurelooprail://spec/failureWhat happens when a step fails: on_fail, failover, retries, and gates that send a rejection ahead.
Limitslimitslooprail://spec/limitsHow many steps of each sort run at once.
Load rulesruleslooprail://spec/rulesEvery load rule, the file most of their examples build on, and what the schema can't check.
Rules for the filerules/filelooprail://spec/rules/fileReading and decoding the file: TOML and JSON, the top level, unknown fields and whole numbers.
Rules for inputsrules/inputslooprail://spec/rules/inputsDerived inputs, and the defaults of static ones.
Rules for typesrules/typeslooprail://spec/rules/typesThe declarations of inputs, outputs and item fields: their types, bounds and defaults.
Rules for stepsrules/stepslooprail://spec/rules/stepsA step's name, kind and description, and the fields each kind needs, may set and may not.
Rules for named agentsrules/agentslooprail://spec/rules/agentsNamed agents, their llm rows, harnesses, and the agent a step names.
Rules for decision modelsrules/decision-modelslooprail://spec/rules/decision-modelsDecision models, their llm rows, and the decision model a step names.
Rules for needs and loopsrules/loopslooprail://spec/rules/loopsneeds, on_fail, max_loops and max_retries.
Rules for templatesrules/templateslooprail://spec/rules/templatesThe form of a {{ }} template and the expression it holds.
Rules for referencesrules/referenceslooprail://spec/rules/referencesWhat a reference may name, and where it may appear.
[Rules for when](#rules-for-when)rules/whenlooprail://spec/rules/whenThe expression of when and the types it compares.
[Rules for for_each](#rules-for-for_each)rules/for-eachlooprail://spec/rules/for-eachfor_each, each and the fields of an item.
Rules for shell quotingrules/shelllooprail://spec/rules/shellWhere a reference may sit in a shell command.
Rules for looprail stepsrules/looprail-stepslooprail://spec/rules/looprail-stepsLooprail steps, the files they run, and their overrides.
Rules for limitsrules/limitslooprail://spec/rules/limitsThe [limits] table.
Rules for briefsrules/briefslooprail://spec/rules/briefsReading a step's brief.
Proposalsproposalslooprail://spec/proposalsEvery proposal to change the format, an LRP, with its status, and the migration guides of the breaking versions.
LRP-0000: Spec proposalsproposals/0000looprail://spec/proposals/0000An implemented clarification proposal, since 0.1.0.
LRP-0001: Spec versioningproposals/0001looprail://spec/proposals/0001An implemented feature proposal, since 0.1.0.
LRP-0002: The file formatproposals/0002looprail://spec/proposals/0002An implemented feature proposal, since 0.1.0.
LRP-0003: Configproposals/0003looprail://spec/proposals/0003An implemented feature proposal, since 0.1.0.
LRP-0004: Inputsproposals/0004looprail://spec/proposals/0004An implemented feature proposal, since 0.1.0.
LRP-0005: Typesproposals/0005looprail://spec/proposals/0005An implemented feature proposal, since 0.1.0.
LRP-0006: Stepsproposals/0006looprail://spec/proposals/0006An implemented feature proposal, since 0.1.0.
LRP-0007: Agent stepsproposals/0007looprail://spec/proposals/0007An implemented feature proposal, since 0.1.0.
LRP-0008: Shell stepsproposals/0008looprail://spec/proposals/0008An implemented feature proposal, since 0.1.0.
LRP-0009: Agent-gate stepsproposals/0009looprail://spec/proposals/0009An implemented feature proposal, since 0.1.0.
LRP-0010: Shell-gate stepsproposals/0010looprail://spec/proposals/0010An implemented feature proposal, since 0.1.0.
LRP-0011: Decision-model stepsproposals/0011looprail://spec/proposals/0011An implemented feature proposal, since 0.1.0.
LRP-0012: Human stepsproposals/0012looprail://spec/proposals/0012An implemented feature proposal, since 0.1.0.
LRP-0013: API stepsproposals/0013looprail://spec/proposals/0013An implemented feature proposal, since 0.1.0.
LRP-0014: MCP stepsproposals/0014looprail://spec/proposals/0014An implemented feature proposal, since 0.1.0.
LRP-0015: Looprail stepsproposals/0015looprail://spec/proposals/0015An implemented feature proposal, since 0.1.0.
LRP-0016: Agentsproposals/0016looprail://spec/proposals/0016An implemented feature proposal, since 0.1.0.
LRP-0017: Outputsproposals/0017looprail://spec/proposals/0017An implemented feature proposal, since 0.1.0.
LRP-0018: Templates and referencesproposals/0018looprail://spec/proposals/0018An implemented feature proposal, since 0.1.0.
LRP-0019: Conditional stepsproposals/0019looprail://spec/proposals/0019An implemented feature proposal, since 0.1.0.
LRP-0020: For eachproposals/0020looprail://spec/proposals/0020An implemented feature proposal, since 0.1.0.
LRP-0021: Shell quotingproposals/0021looprail://spec/proposals/0021An implemented feature proposal, since 0.1.0.
LRP-0022: Failureproposals/0022looprail://spec/proposals/0022An implemented feature proposal, since 0.1.0.
LRP-0023: Limitsproposals/0023looprail://spec/proposals/0023An implemented feature proposal, since 0.1.0.
Changelogchangeloglooprail://spec/changelogThe LRPs each version of the spec implemented, the newest first.

The file

A looprail is TOML. It is JSON when the file is named .json, or when stdin starts with {.

  • Checked first. The file, its briefs and every looprail it runs are checked before anything is asked or run.
  • Errors. An invalid file exits 2, and each error names its field.
  • Whole numbers. A whole-number field also takes a float such as 2.0, which a JSON Schema counts as an integer. 2.5 fails, naming the field.

Top level fields

A looprail file, as TOML decodes it or as JSON writes it.

FieldTypeRequiredSinceDescription
metadatametadatayes0.1.0The file's spec version, name and description. See Metadata.
inputsinputs0.1.0The inputs the looprail takes.
agentstable of <name> to named agent0.1.0Named agents, by name, which agent and agent-gate steps use with agent = { name = "<name>" }. A step of a looprail this one runs may name them too. Every named agent must be named by a step, here or in a looprail this one runs. See Named agents. A name must not be empty or hold ", { or }.
harnessestable of <name> to harness0.1.0Extra ACP harnesses, by name, which an inline agent's or an llm row's provider may name, besides the built-in ones. One named like a built-in provider replaces its command in this file. A name must not be empty or hold ", { or }.
decision-modelstable of <name> to decision model0.1.0Decision models, by name, which decision-model steps use with decision-model = { name = "<name>" }. A step of a looprail this one runs may name them too. Every decision model must be named by a step, here or in a looprail this one runs, and none may share its name with a named agent. See Decision models. A name must not be empty or hold ", { or }.
steptable of <name> to stepyes0.1.0The steps, by name. In TOML a step is [[step.<name>]], an array of tables that holds exactly one element; in JSON, step.<name> is an object, or a list holding one object. The order in the file is only the order of the list: needs gives the run order. Must not be empty. A name must not be empty or hold ", { or }.
limitslimits0.1.0How many steps of each sort run at once. A key nobody sets has no cap. See Limits.
configconfig0.1.0Settings for the whole file. See Config.

Metadata

[metadata] holds the file's spec version, name and description.

  • Required, with spec_version and name set.
  • A top-level name or description is an unknown field.

Metadata fields

Written as [metadata]. What the file is: the spec version it is written to, its name and its description.

FieldTypeRequiredSinceDescription
spec_versionstringyes0.1.0The version of the spec the file is written to, as MAJOR.MINOR.PATCH. A looprail loads a file of its own major whose version is no higher than its own. See Versions. MAJOR.MINOR.PATCH with major 0, no higher than 0.1.0: no leading v, no pre-release and no part left out.
namestringyes0.1.0The looprail's name. A looprail read from stdin names its run folder with it. Must not be blank.
descriptionstring0.1.0One sentence on what the looprail does. looprail list shows it.

A file that says which spec it is written to. (metadata) Loads.

[metadata]
spec_version = "0.1.0"
name = "hello"
description = "Prints a greeting."

[[step.hello]]
kind = "shell"
description = "Prints a greeting."
run = ["echo hello"]

Versions

spec_version is MAJOR.MINOR.PATCH: no leading v, no pre-release, no part left out. As in semantic versioning:

  • Patch. A fix to the spec's text or a check that changes no valid file.
  • Minor. Something new, such as a field or a kind, that a file of an older minor never uses. Every file of an older minor of the same major loads unchanged.
  • Major. A change that makes some valid file fail, or mean something else.

What loads. This looprail reads spec 0.1.0.

  • It loads files of the same major, no higher than its own version. A looprail at 1.2.3 loads 1.0.1 and 1.2.0, and fails on 1.2.4, 0.3.5 and 2.0.1.
  • A higher version or a newer major needs a newer looprail.
  • An older major needs migrating first, with the migration guides.
  • Each looprail a looprail step runs is checked against its own spec_version.

Since. Every field and kind has the version it entered the format in.

  • The field tables show it as Since, linked to its proposal.
  • A file may use only what exists at its spec_version. Anything newer fails with [spec-since](#spec-since), naming the field and both versions.
  • A file without spec_version is not checked.

Deprecation. A field or kind may be deprecated within a major, and removed only in the next.

  • The field tables mark it with the version and proposal that deprecated it, and what to use instead.
  • A file that sets one still loads. looprail validate and looprail doctor print a warning, and exit as they would without it.

Config

[config] holds settings for the whole file.

  • Without it, every setting is off.
  • An unknown key fails, naming it.

Config fields

Written as [config].

FieldTypeRequiredSinceDescription
enable_nixtrue or false0.1.0Runs the whole of looprail run inside the Nix dev shell of the directory it was started in, from its flake.nix or else its shell.nix. Off when unset. A run already inside a Nix shell carries on as it is. Outside one, the looprail must come from a file, not stdin.

Turning a setting on. (config) Loads.

[metadata]
spec_version = "0.1.0"
name = "config"

[config]
enable_nix = true

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

The Nix dev shell

With enable_nix on, the whole run happens inside the Nix dev shell of the directory it started in. Every step, agent and child run has that shell's tools.

  • When it enters.
  • looprail run enters before any step, when no Nix shell is active.
  • So do the runs that runs resume and the MCP server start, since both go through run. runs resume works from the run's project directory.
  • Only the file given to run counts. enable_nix in a looprail step's file has no effect.
  • Which shell.
  • run looks for flake.nix, then shell.nix, only in the directory it was invoked from.
  • Not in parent directories, the looprail file's folder or --dir.
  • flake.nix: nix develop <dir> -c.
  • shell.nix: nix-shell <dir>/shell.nix --run.
  • A directory with a flake.nix needs nix, even with nix-shell installed and a shell.nix beside it.
  • No nesting.
  • With IN_NIX_SHELL set to any value, the run stays where it is, and looks for neither shell files nor tools.
  • The entered shell sets it, so the run enters only once.
  • Cost.
  • run replaces itself with the same command inside the shell. Its process, streams and exit code stay the run's.
  • Nix evaluates the shell once before the first step, building it if needed.

When the shell cannot be entered, run prints one of these on stderr and exits 2 before any step. <dir> is the directory's absolute path.

MessageCause
Missing Nix installation but enable_nix is onThe needed tool is not on PATH: nix for a flake.nix, nix-shell for a shell.nix.
enable_nix is on but <dir> has neither a flake.nix nor a shell.nixNo shell file.
enable_nix is on but <dir> could not be checked for a Nix shell: <reason>Looking for a shell file failed, as on a symlink loop.
looprail: enable_nix is on and the looprail cannot be read again inside the Nix shell; pass a regular file, or start the run inside the shellThe looprail came from stdin or a pipe, and entering the shell runs the command again.
looprail: entering the Nix shell: <reason>The shell's command could not start.

looprail doctor shows whether nix and nix-shell are on PATH, and never fails over it.

JSON

A JSON looprail holds the same fields.

  • step is an object of step name to step.
  • A step may also be a list holding one object, as TOML decodes [[step.<name>]]. So the JSON of a decoded TOML file loads:
{"metadata": {"spec_version": "0.1.0", "name": "hello"}, "step": {"hello": {"kind": "shell", "run": ["echo hello"]}}}
  • JSON becomes the same TOML document before decoding, so both give the same errors and field names.
  • null is not allowed anywhere.

Errors

  • Every load error names its field by its path: step.code.outputs.message.max_length, inputs.static.issue.min, step.fix.run[0], step.code.override[1].agent.
  • The loader lists every error, not just the first.

A field the format does not have fails, naming it. (unknown-field) Fails to load, breaking [unknown-field](#unknown-field):

[metadata]
spec_version = "0.1.0"
name = "typo"

[[step.hello]]
kind = "shell"
description = "Runs hello."
run = ["echo hello"]
nedes = ["other"]
step.hello.nedes: unknown field

A name that is not a plain name is quoted in errors and references. (quoted-name) Fails to load, breaking [run-empty](#run-empty):

[metadata]
spec_version = "0.1.0"
name = "quoted"

[[step."needs work"]]
kind = "shell"
description = "Runs needs work."
run = []
step."needs work".run: is empty; a shell step needs at least one command

The load rules are in Rules for the file.

What this page sets out was brought in by LRP-0002, LRP-0001 and LRP-0003.

Inputs

A step reads an input as {{ inputs.<name> }}: see References.

Static inputs come from the caller:

  • run's inputs JSON,
  • the inputs event in --std mode,
  • the terminal UI's questions, or
  • the --web form.

Each is checked against its declaration.

  • A missing input takes its default.
  • With no default, it is required.
  • An undeclared input is an error.

Derived inputs are worked out from the static ones before any step runs.

Inputs fields

Written as [inputs].

FieldTypeRequiredSinceDescription
statictable of <name> to static input0.1.0The inputs a caller passes, in the order the file writes them, which is the order a person is asked for them.
derivedtable of <name> to string0.1.0Inputs worked out from the static ones before any step runs: a template that may reference only static inputs, rendered as plain text. A derived input is a string, and may not share a name with a static one.

Static input fields

Written as inputs.static.<name>.

FieldTypeRequiredSinceDescription
typestringyes0.1.0The input's type. See Types. Must be one of string, enum, bool, int or float.
descriptionstringyes0.1.0One sentence on what the input means. looprail list, the terminal UI's input form, the --web page's form and the inputs event of --std show it. Must not be blank.
defaultstring, number, or true or false0.1.0The value used when the caller gives none. It must check out against the declaration. An input without one is required.
valueslist of strings0.1.0An enum's values. An enum needs them, and only an enum has them. Must not be empty.
min_lengthwhole number0.1.0A string's least length, in characters. At least 0.
max_lengthwhole number0.1.0A string's greatest length, in characters. Not below min_length.
minnumber0.1.0A number's lower bound. An int's bounds are whole numbers.
maxnumber0.1.0A number's upper bound. Not below min.
items-not allowed0.1.0Inputs cannot be lists, so they have no items. Setting it fails with only a list has items.

Each input type, with its bounds. An input with a default is optional. (input-types) Loads.

[metadata]
spec_version = "0.1.0"
name = "inputs"

[inputs.static]
title = { type = "string", description = "The pull request's title.", min_length = 1, max_length = 80 }
label = { type = "enum", description = "The label the pull request gets.", values = ["bug", "chore"], default = "bug" }
draft = { type = "bool", description = "Whether the pull request opens as a draft.", default = false }
issue = { type = "int", description = "The number of the issue it fixes.", min = 1 }
ratio = { type = "float", description = "How much of the work to sample.", min = 0, max = 1, default = 0.5 }

[inputs.derived]
branch = "{{ inputs.label }}/{{ inputs.issue }}"

[[step.show]]
kind = "shell"
description = "Runs show."
run = ["echo {{ inputs.title }} {{ inputs.branch }} {{ inputs.draft }} {{ inputs.ratio }}"]

An input cannot be a list. (input-list) Fails to load, breaking [type](#type):

[metadata]
spec_version = "0.1.0"
name = "inputs"

[inputs.static]
issues = { type = "list", description = "The issues." }

[[step.show]]
kind = "shell"
description = "Runs show."
run = ["echo {{ inputs.issues }}"]
inputs.static.issues.type: "list" is not a type; use one of string, enum, bool, int, float

A default must check out against its declaration. (bad-default) Fails to load, breaking [default](#default):

[metadata]
spec_version = "0.1.0"
name = "inputs"

[inputs.static]
slug = { type = "string", description = "The slug.", max_length = 4, default = "too long" }

[[step.show]]
kind = "shell"
description = "Runs show."
run = ["echo {{ inputs.slug }}"]
inputs.static.slug.default: "too long" is 8 characters, above max_length 4

A derived input may reference only static inputs. (derived-from-step) Fails to load, breaking [derived-ref](#derived-ref):

[metadata]
spec_version = "0.1.0"
name = "inputs"

[inputs.derived]
when = "{{ steps.a.status }}"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]
inputs.derived.when: {{ steps.a.status }}: a derived input may only reference a static input

The load rules are in Rules for inputs and Rules for types.

What this page sets out was brought in by LRP-0004.

Types

Inputs, outputs and the fields of a list's items declare a type. Inputs have the types string, enum, bool, int and float; outputs and item fields also have list.

TypeInputOutput or item fieldFields besides typeHolds
stringyesyesmin_length and max_lengthText. min_length and max_length count characters.
enumyesyesvaluesOne of values.
boolyesyesnonetrue or false.
intyesyesmin and maxA whole number, within min and max.
floatyesyesmin and maxA number, within min and max.
listnoyesitemsA JSON list. With items, each item is an object holding those fields.

Descriptions

  • Every static input, step and declared output needs a description.
  • One sentence on what it means, does or holds, for someone who did not write the looprail.
  • Missing or blank, it fails at load, naming the field: inputs.static.slug.description, step.code.description or step.code.outputs.message.description.
  • Optional on an item field.

Bounds

  • A bound applies to its own type only. min_length on an int fails, naming the field.
  • min may not exceed max, nor min_length max_length.
  • An int's bounds are whole numbers.
  • An empty values or items fails.

The fields of a declaration are in the static input fields, output fields and item field fields tables.

The load rules are in Rules for types.

What this page sets out was brought in by LRP-0005.

Steps

A step is a table in the array step.<name>.

  • Writing. [[step.<name>]], then its sub-tables: [step.<name>.outputs] and [step.<name>.questions.<question>].
  • Names. A second [[step.<name>]] fails with "two steps share the name".
  • When. A step runs once every step in its needs has passed or been skipped.
  • In parallel. Ready steps run at the same time, up to the limits.
  • File order is only the order steps are listed in.

Step fields

Written as [[step.<name>]]. One step. Which fields it needs and may set depends on its kind.

FieldTypeRequiredSinceDescription
kindstringyes0.1.0What the step does. See Kinds. Must be one of agent, shell, agent-gate, shell-gate, decision-model, human, api, mcp or looprail.
descriptionstringyes0.1.0One sentence on what the step does. looprail list and looprail doctor --json show it. Must not be blank.
needslist of strings0.1.0The steps that must settle before this one starts. A step may reference only the steps it needs, directly or through others. Each name must exist, appear once, not be the step itself, and the needs may not form a cycle.
whenstring0.1.0Not for [looprail](#looprail-steps). One {{ }} holding a true or false expression. The step is skipped when it is false. On a for_each step it is evaluated per item. See when.
cwdstring0.1.0Not for [looprail](#looprail-steps). The directory the step's commands or agent run in: a template, rendered as plain text. Unset, it is the directory looprail was started in, and a relative path is relative to that.
failoverstring0.1.0Not for [looprail](#looprail-steps). What happens when the step fails and on_fail does not apply. human, the default, asks a person to continue or stop. agent hands the brief and the failure to a new session of the same agent, and only an agent or agent-gate step may set it. See Failure. Must be one of human or agent. Empty is the same as unset.
on_failstring0.1.0Not for [looprail](#looprail-steps). The step a failure sends the run back to: this step, or one upstream of it through needs. A gate without for_each may instead name a step downstream of it, to send its rejection ahead. See Failure.
max_loopswhole number0.1.0Not for [looprail](#looprail-steps). How many times on_fail may send the run back. Needs on_fail. Unset, the loop has no cap, except on a gate that sends its rejection ahead, which must set it. At least 1.
max_retrieswhole number0.1.0Not for [looprail](#looprail-steps). How many times a person may answer the step's failure with retry, counted afresh each time on_fail runs the step again. Unset, it is 3; 0 offers only skip and stop. These retries count toward neither loops nor max_loops. retry and feedback each spend one retry, and ask spends none. See Failure. At least 0.
for_eachstring0.1.0One reference to a list: a list output, or another for_each step's steps.<name>.outputs. The step runs once per item, the items at the same time, and {{ each }} is the item. See for_each.
runlist of strings0.1.0Only for [shell](#shell-steps), [shell-gate](#shell-gate-steps). Shell commands, each run through sh -c in order, with stdin closed. The step stops at the first that fails. Each is a template under the shell quoting rules. Must not be empty.
accept_exitlist of whole numbers0.1.0Only for [shell-gate](#shell-gate-steps). The exit codes that pass the gate. A command that exits with another code rejects it. Must not be empty.
agentagent0.1.0Only for [agent](#agent-steps), [agent-gate](#agent-gate-steps). The agent the step prompts: a named agent, or an ACP harness written inline, which the step starts with the model it applies.
envtable of <name> to string0.1.0Only for [agent](#agent-steps), [agent-gate](#agent-gate-steps), [mcp](#mcp-steps). Environment variables for the harness of an agent or agent-gate step, or for the server an mcp step starts with command, merged over the environment looprail runs in: a variable set here replaces the one of the same name, and the others are passed on. Each value is taken as written, with no {{ }} references, and may be empty. A shell step's commands do not get them. A name is letters, digits and _, not starting with a digit. The names looprail uses itself are reserved, and fail at load: PATH, PWD and LOOPRAIL_* (looprail finds agent.command[0] on its own PATH, starts the harness in the step's cwd, and sets $LOOPRAIL_CURRENT_RUN_DIR for it). A value must not hold a NUL character.
briefstring0.1.0Only for [agent](#agent-steps), [agent-gate](#agent-gate-steps). The path of the brief, relative to the looprail file. It is read at load, its references are checked, and its text, rendered as plain text, is the prompt. Its hash is part of the checkpoint: see Briefs.
acceptstring0.1.0Only for [agent-gate](#agent-gate-steps). The verdict that passes the gate. The agent's JSON holds verdict, and any other value rejects the gate.
idle_limitstring0.1.0Only for [agent](#agent-steps), [agent-gate](#agent-gate-steps). How long an agent or agent-gate step may wait for its background tasks with no update from the harness before it fails: a duration such as 30m or 2h, or unlimited. Unset, it is 1h. The wait starts when the agent's turn ends while a background task or an autonomous turn is live (see Kinds), and each update the harness sends starts the time again. A step that hits it fails with an error naming the tasks it waited for, and goes to its failover as any failure does. --set <step> idle_limit=10m changes it for a run. A duration is a number and a unit, ns, us, ms, s, m or h, or several, as 1h30m, and more than zero. Empty is the same as unset.
decision-modelstep decision model0.1.0Only for [decision-model](#decision-model-steps). The decision model that answers the questions: a [decision-models.<name>] of this file or of a looprail that runs it.
statestring0.1.0Only for [decision-model](#decision-model-steps). What the decision model judges: a template, rendered as plain text.
questionstable of <question> to question0.1.0Only for [decision-model](#decision-model-steps). The questions, written [step.<name>.questions.<question>]. Each sets an output of the step of the same name, and a choice or a score sets more. See Questions. Must not be empty.
askstring0.1.0Only for [human](#human-steps). What a person is asked: a template, rendered as plain text. The reply is the step's output answer, and stop ends the run.
choiceslist of strings0.1.0Only for [human](#human-steps). The answers a human step offers, which the question event carries as choices so a front end can show them as buttons. An answer that names one with action sets answer to it. A person may still answer with text, and stop still ends the run. Must not be empty. A choice must not be blank or listed twice.
methodstring0.1.0Only for [api](#api-steps). The HTTP method of an api step. Unset, it is GET. Must be one of GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS. Empty is the same as unset.
urlstring0.1.0Only for [api](#api-steps), [mcp](#mcp-steps). The address an api step requests, or that of the MCP server an mcp step calls over streamable HTTP: a template, rendered as plain text, that may reference env. Neither kind follows a redirect from it. An mcp step sets url or command, not both.
headerstable of <name> to string0.1.0Only for [api](#api-steps), [mcp](#mcp-steps). HTTP headers for an api step's request, or for every request an mcp step sends to the server at its url. Redirects are never followed, so neither the headers nor the body reach another address. Each value is a template, rendered as plain text, that may reference env, as in Authorization = "Bearer {{ env.API_TOKEN }}".
bodystring, or any value sent as JSON0.1.0Only for [api](#api-steps). What an api step sends. A string is a template, rendered as plain text and sent as written. Any other value, most often a table, is sent as JSON, with Content-Type: application/json unless headers sets one: each string in it is a template, and a string that is one reference alone takes the referenced value with its type, so a list stays a list. Either may reference env.
commandlist of strings0.1.0Only for [mcp](#mcp-steps). The MCP server an mcp step starts and calls over stdio: the program, found on PATH, and its arguments, each a template rendered as plain text that may reference env. It runs in the step's cwd, with the environment looprail runs in and the step's env merged over it. Must not be empty. Each entry: must not be empty.
toolstring0.1.0Only for [mcp](#mcp-steps). The tool an mcp step calls, by the name the server lists it under.
argumentstable of <argument> to any value0.1.0Only for [mcp](#mcp-steps). The arguments of an mcp step's tool call, sent as a JSON object. Each string in them is a template, and a string that is one reference alone takes the referenced value with its type, as in body. They may reference env.
outputstable of <output> to output0.1.0Only for [agent](#agent-steps), [shell](#shell-steps), [agent-gate](#agent-gate-steps), [shell-gate](#shell-gate-steps), [api](#api-steps), [mcp](#mcp-steps). The outputs the step sets, written [step.<name>.outputs] after [[step.<name>]]. Later steps read them as {{ steps.<name>.outputs.<output> }}. Only agent, agent-gate, shell, shell-gate, api and mcp steps declare outputs. See Outputs.
looprailstring0.1.0Only for [looprail](#looprail-steps). The looprail a looprail step runs: a path relative to the directory looprail was started in, not to this file. It, and every file it runs, is loaded and validated before anything runs, and a file may not run itself, directly or through others. See Looprail steps.
overridelist of override0.1.0Only for [looprail](#looprail-steps). Agents that replace the agent of every agent and agent-gate step of the looprail a looprail step runs, for the for_each items they match, written [[step.<name>.override]] after [[step.<name>]]. Overrides need for_each: without it there is no item, and an override never applies. An override has only match and agent: anything else fails with "an override can only replace an agent; it cannot add, remove or reorder a step".
provider-not allowed0.1.0A step has no provider: it belongs on an llm row of a decision model. Setting it fails with a step has no provider; list it under [decision-models.<name>] and set decision-model = { name = "..." }.

Kinds

Each kind has a page with its fields, the outputs it sets and its examples.

KindFields it needsIts optional fieldsMay declare outputsFails over to an agentWhat it does
[agent](#agent-steps)agent and briefenv and idle_limityesyesStarts agent, sends the brief as the prompt, and takes its outputs from the JSON object the last message ends with.
[shell](#shell-steps)runnoneyesnoRuns run, each command through sh -c.
[agent-gate](#agent-gate-steps)agent, brief and acceptenv and idle_limityesyesAn agent that judges and changes nothing.
[shell-gate](#shell-gate-steps)run and accept_exitnoneyesnoRuns run like a shell step, and passes, with accepted set, when every command exits with a code in accept_exit.
[decision-model](#decision-model-steps)decision-model, state and questionsnonenonoAsks the decision model that decision-model names the questions about state.
[human](#human-steps)askchoicesnonoAsks a person ask, offering choices when it has them.
[api](#api-steps)urlmethod, headers and bodyyesnoSends one HTTP request to url, with method, headers and body.
[mcp](#mcp-steps)toolurl, headers, command, env and argumentsyesnoCalls tool on an MCP server, reached at url or started with command, with arguments.
[looprail](#looprail-steps)looprailoverridenonoRuns the looprail file looprail as one node of this one, once, or once per item with for_each, and passes when every run of it passes.
  • Every kind must set description.
  • Every kind may set needs, when, cwd, failover, on_fail, max_loops, max_retries and for_each, except looprail, which may not set when, cwd, failover, on_fail, max_loops or max_retries.
  • A field the kind does not have fails, naming it. So does a missing field the kind needs.
  • These may not be empty: run, accept_exit, agent.command, questions, an enum's values and a list's items.

A step may not set another kind's fields. (wrong-kind-field) Fails to load, breaking [kind-has-no](#kind-has-no):

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]
ask = "Go on?"
step.a.ask: a shell step has no ask

A step must set its kind's fields. (missing-kind-field) Fails to load, breaking [kind-needs](#kind-needs):

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.a]]
kind = "shell-gate"
description = "Runs a."
run = ["test -f done"]
step.a.accept_exit: a shell-gate step needs accept_exit

The load rules are in Rules for steps and Rules for needs and loops.

What this page sets out was brought in by LRP-0006.

agent steps

Starts agent, sends the brief as the prompt, and takes its outputs from the JSON object the last message ends with. When that message has none, its JSON does not parse or it does not match the outputs, the step asks the agent for it again in the same session, with the reason, up to 2 times before it fails.

  • Needs: kind, description, agent and brief.
  • May set: env and idle_limit, and of the fields every kind shares, needs, for_each, when, cwd, failover, on_fail, max_loops and max_retries.
  • May not set: no common field, nor any field of another kind.
  • Declares outputs: yes, in [step.<name>.outputs].
  • Sets outputs itself: none.
  • Fails over to an agent: yes, with failover = "agent".

The step fields table describes each field.

An agent step prompts an agent and reads its outputs from the reply.

  • Agent. Inline or named: see Agents.
  • Prompt. The brief with its references filled in, then a note listing the fields the final JSON must hold. A failover adds the failure.
  • Reply. The last message of an agent or agent-gate step must end with a JSON object holding its outputs.
  • Cut short. A turn that ends for any reason but the end of the turn fails the step.

Background tasks

Some harnesses, such as claude-agent-acp, report background tasks through the AIR asyncTasks extension.

  • The harness can end its turn while a background command or monitor still runs, and carry on in a new turn once it ends.
  • The step goes on until no task and no such turn is live. The last message is the last one the agent wrote.
  • Meanwhile the step's waiting says what for, as in "2 background tasks: looprail-dev test affected, sleep 60".
  • Each task update is a task record in the step run's log.
  • A wait of idle_limit with no update fails the step, naming the tasks.
  • A last message without the JSON, with nothing live, fails the step. If the harness reports no background tasks, the error says so.

An agent step's env is merged over the environment the harness gets. (agent-env) Loads.

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.code]]
kind = "agent"
description = "Runs code."
agent = { command = ["claude-agent-acp"], model = "opus" }
brief = "code.md"
env = { ANTHROPIC_BASE_URL = "http://localhost:1985", ANTHROPIC_API_KEY = "" }

code.md:

Fix it.

An agent step that may wait on its background tasks for up to 3 hours with no update, and a review that may wait without limit. (agent-idle-limit) Loads.

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.code]]
kind = "agent"
description = "Runs code."
agent = { command = ["claude-agent-acp"] }
brief = "code.md"
idle_limit = "3h"

[[step.review]]
kind = "agent-gate"
description = "Reviews the code."
needs = ["code"]
agent = { command = ["claude-agent-acp"] }
brief = "code.md"
accept = "pass"
idle_limit = "unlimited"

code.md:

Fix it.

idle_limit is a duration with its unit, or unlimited. (idle-limit) Fails to load, breaking [idle-limit](#idle-limit):

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.code]]
kind = "agent"
description = "Runs code."
agent = { command = ["claude-agent-acp"] }
brief = "code.md"
idle_limit = "90"

code.md:

Fix it.
step.code.idle_limit: "90" is not a duration such as 30m or 2h, or unlimited

A step's env may not set a variable looprail uses itself. (env-reserved) Fails to load, breaking [env-reserved](#env-reserved):

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.code]]
kind = "agent"
description = "Runs code."
agent = { command = ["claude-agent-acp"] }
brief = "code.md"
env = { PATH = "/opt/bin" }

code.md:

Fix it.
step.code.env.PATH: PATH is reserved; a step's env may not set PATH, PWD, or a variable starting with LOOPRAIL_, which looprail uses itself

What this page sets out was brought in by LRP-0007.

shell steps

Runs run, each command through sh -c. It fails at the first command that exits non-zero. Its outputs are what the commands write to $LOOPRAIL_OUTPUTS.

  • Needs: kind, description and run.
  • May set: none of its own, and of the fields every kind shares, needs, for_each, when, cwd, failover, on_fail, max_loops and max_retries.
  • May not set: no common field, nor any field of another kind.
  • Declares outputs: yes, in [step.<name>.outputs].
  • Sets outputs itself: none.
  • Fails over to an agent: no.

The step fields table describes each field.

A shell step runs commands.

  • Running. Each entry of run goes through sh -c in the step's cwd, in order, with stdin closed.
  • References follow the shell quoting rules.
  • Log. Each command's line and exit go to the step run's log folder in the run folder, and the whole output of a command that fails goes there too.
  • Outputs. Written to the file named by $LOOPRAIL_OUTPUTS, as KEY=value lines or one JSON object: see Outputs.
  • Run folder. $LOOPRAIL_CURRENT_RUN_DIR holds its path.

Only agent and agent-gate steps have env. (env-shell) Fails to load, breaking [kind-has-no](#kind-has-no):

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]
env = { DEBUG = "1" }
step.a.env: a shell step has no env

What this page sets out was brought in by LRP-0008.

agent-gate steps

An agent that judges and changes nothing. Its prompt tells it to change no file; nothing enforces it for now, so it may make any tool call. Its JSON also holds verdict, its own output, and it passes, with accepted set, when the verdict equals the step's accept. Any other verdict rejects it.

  • Needs: kind, description, agent, brief and accept.
  • May set: env and idle_limit, and of the fields every kind shares, needs, for_each, when, cwd, failover, on_fail, max_loops and max_retries.
  • May not set: no common field, nor any field of another kind.
  • Declares outputs: yes, in [step.<name>.outputs].
  • Sets outputs itself: verdict, a string, besides those it declares.
  • Fails over to an agent: yes, with failover = "agent".

The step fields table describes each field.

An agent-gate asks an agent to accept or reject.

  • It prompts its agent, and waits on background tasks, as an [agent](#agent-steps) step does.
  • It sets {{ steps.<name>.accepted }}.
  • It is asked to change nothing. looprail does not enforce this yet, and allows its tool calls as an agent step's.
  • A gate that rejects fails like any step.
  • Unless its on_fail names a downstream step: then it sends its rejection ahead.

A gate that reviews the change of the step before it, and sends a rejection back to it up to three times. (agent-gate-review) Loads.

[metadata]
spec_version = "0.1.0"
name = "review"

[[step.code]]
kind = "agent"
description = "Makes the change."
agent = { command = ["claude-agent-acp"] }
brief = "code.md"

[[step.review]]
kind = "agent-gate"
description = "Reviews the change."
needs = ["code"]
agent = { command = ["claude-agent-acp"] }
brief = "review.md"
accept = "accept"
on_fail = "code"
max_loops = 3

code.md:

Fix it.

review.md:

Review the change, and accept it or reject it.

What this page sets out was brought in by LRP-0009.

shell-gate steps

Runs run like a shell step, and passes, with accepted set, when every command exits with a code in accept_exit. Another code rejects it.

  • Needs: kind, description, run and accept_exit.
  • May set: none of its own, and of the fields every kind shares, needs, for_each, when, cwd, failover, on_fail, max_loops and max_retries.
  • May not set: no common field, nor any field of another kind.
  • Declares outputs: yes, in [step.<name>.outputs].
  • Sets outputs itself: none.
  • Fails over to an agent: no.

The step fields table describes each field.

A shell-gate accepts or rejects by its commands' exit codes.

  • It runs its commands as a [shell](#shell-steps) step does.
  • It sets {{ steps.<name>.accepted }}.
  • A gate that rejects fails like any step.
  • Unless its on_fail names a downstream step: then it sends its rejection ahead.

An empty list is rejected where the step could never work with one. (empty-accept-exit) Fails to load, breaking [accept-exit-empty](#accept-exit-empty):

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.a]]
kind = "shell-gate"
description = "Runs a."
run = ["test -f done"]
accept_exit = []
step.a.accept_exit: is empty; a gate that accepts no exit code can never pass

What this page sets out was brought in by LRP-0010.

decision-model steps

Asks the decision model that decision-model names the questions about state. Each question sets an output of the same name, and a choice or a score sets more. No provider is built yet, so the step always fails when it runs.

  • Needs: kind, description, decision-model, state and questions.
  • May set: none of its own, and of the fields every kind shares, needs, for_each, when, cwd, failover, on_fail, max_loops and max_retries.
  • May not set: no common field, nor any field of another kind.
  • Declares outputs: no.
  • Sets outputs itself: one per question, of the same name; <question>_confidence for a choice or a score; and <question>_probabilities for one with probabilities = true.
  • Fails over to an agent: no.

The step fields table describes each field.

A decision-model step names a decision model, decision-model = { name = "<name>" }, and asks it its questions about state.

Decision models

A decision model is a [decision-models.<name>] table with one field, llm.

  • llm lists the models it may call, in order, each [[decision-models.<name>.llm]].
  • The [decision-models.<name>] header may be left out above its rows.
  • A row names a provider and a model, jev-latest by default.

The providers are:

  • jev: Not built yet: a step that reaches it fails with "not implemented".
  • A step of a looprail this one runs may name the decision model too.
  • A looprail that defines the name again must give it the same rows.
  • It may not share its name with a named agent.
  • A step of the file, or of a looprail it runs, must name it.
  • A looprail step's override replaces agents, not decision models.

Step decision model fields

Written as decision-model = { ... }, on a decision-model step. The decision model the step asks, by name. Its provider and model are on the decision model's llm rows.

FieldTypeRequiredSinceDescription
namestringyes0.1.0The decision model, a [decision-models.<name>] of this file or of a looprail that runs it. It is the only field: provider and model go on [[decision-models.<name>.llm]]. Must not be empty.

Decision model fields

Written as [decision-models.<name>].

FieldTypeRequiredSinceDescription
llmlist of decision model llmyes0.1.0The models the decision model may call, in order. Must not be empty.

Decision model LLM fields

Written as [[decision-models.<name>.llm]].

FieldTypeRequiredSinceDescription
providerstringyes0.1.0Who runs the model. Must be jev.
modelstring0.1.0The model, as the provider names it. Unset, it is jev-latest.

Questions

Each question is written [step.<name>.questions.<question>]. Its outputs depend on its type:

TypeOutputs
yes-no<question>, a float from 0 to 1
choice<question>, an enum of its criteria keys, and <question>_confidence, a float from 0 to 1
score<question>, a float from 0 to the index of its last level, and <question>_confidence, a float from 0 to 1

With probabilities = true, a choice or score also sets <question>_probabilities, a list with one item per answer.

  • A choice's items are {value, probability}.
  • A score's items are {level, probability}, with level an int.

A question may not be named like an output another question sets.

Question fields

Written as [step.<name>.questions.<question>].

FieldTypeRequiredSinceDescription
typestringyes0.1.0choice picks one of its criteria keys, yes-no is a number from 0 to 1, and score a number from 0 to the index of its last level. Must be one of choice, yes-no or score.
instructionsstring0.1.0What the decision model is told about the question.
criteriatable of <value> to string0.1.0A choice's values, each with what it means. A choice needs criteria, and only a choice has them. Must not be empty.
levelslist of strings0.1.0A score's levels, lowest first. A score needs them, and only a score has them. At most 10 entries. At least 2 entries.
probabilitiestrue or false0.1.0Also sets <question>_probabilities, how likely each answer is. Only a choice or a score may set it, to true or to false.

A decision-model step that gives each open issue a category, for an agent to report on. (decision-model) Loads.

[metadata]
spec_version = "0.1.0"
name = "issue-report"
description = "Fetches open issues, categorises each, and writes a report."

[[decision-models.triage.llm]]
provider = "jev"
model = "jev-1.14.0"

[limits.decision-model.jev]
max_parallel = 20

[[step.fetch]]
kind = "shell"
description = "Lists the open issues."
run = ["gh issue list --state open --limit 200 --json number,title,body | jq '{issues: .}' > $LOOPRAIL_OUTPUTS"]

[step.fetch.outputs]
issues = { type = "list", description = "The open issues.", items = { number = { type = "int" }, title = { type = "string" }, body = { type = "string" } } }

[[step.categorise]]
kind = "decision-model"
description = "Gives one issue a category."
needs = ["fetch"]
for_each = "{{ steps.fetch.outputs.issues }}"
decision-model = { name = "triage" }
state = "{{ each }}"

[step.categorise.questions.category]
type = "choice"
instructions = "Which category fits the issue in `title` and `body` best?"
criteria = { bug = "Something that worked is broken.", feature = "A new capability.", docs = "Documentation only.", chore = "Upkeep with no behaviour change.", other = "None of the others." }

[[step.report]]
kind = "agent"
description = "An agent writes the report from the categorised issues."
needs = ["categorise"]
agent = { command = ["claude-agent-acp"], model = "sonnet" }
brief = "briefs/report.md"

[step.report.outputs]
report = { type = "string", description = "The report, as Markdown.", min_length = 1 }

briefs/report.md:

{{ steps.categorise.outputs }}

The load rules are in Rules for decision models and Rules for steps.

What this page sets out was brought in by LRP-0011.

human steps

Asks a person ask, offering choices when it has them. The reply is the output answer, and stop, in any case, ends the run.

  • Needs: kind, description and ask.
  • May set: choices, and of the fields every kind shares, needs, for_each, when, cwd, failover, on_fail, max_loops and max_retries.
  • May not set: no common field, nor any field of another kind.
  • Declares outputs: no.
  • Sets outputs itself: answer, a string: the reply.
  • Fails over to an agent: no.

The step fields table describes each field.

A human step asks a person a question.

  • Asked by the terminal UI, the --web page, a question event in --std mode or an MCP client.
  • Choices. A front end shows choices as buttons. An answer naming one with action sets answer to it. Text answers still work.
  • Stop. The reply stop, in any letter case, ends the run at once, with no failover.

A human step that offers two answers, and a step that runs only on one of them. (human) Loads.

[metadata]
spec_version = "0.1.0"
name = "ship"

[[step.approve]]
kind = "human"
description = "Asks whether to ship."
ask = "Ship the release?"
choices = ["ship", "hold"]

[[step.ship]]
kind = "shell"
description = "Ships the release."
needs = ["approve"]
when = "{{ steps.approve.outputs.answer == 'ship' }}"
run = ["echo shipping"]

What this page sets out was brought in by LRP-0012.

api steps

Sends one HTTP request to url, with method, headers and body. A redirect is not followed: it is the answer, and like any status outside 2xx it fails the step. Its outputs are status_code and body, plus those it declares, picked by name from the JSON object the response holds.

  • Needs: kind, description and url.
  • May set: method, headers and body, and of the fields every kind shares, needs, for_each, when, cwd, failover, on_fail, max_loops and max_retries.
  • May not set: no common field, nor any field of another kind.
  • Declares outputs: yes, in [step.<name>.outputs].
  • Sets outputs itself: body (a string) and status_code (an int), besides those it declares.
  • Fails over to an agent: no.

The step fields table describes each field.

An api step sends one HTTP request. It needs no agent, so a scheduled looprail can post to Slack or call a service by itself.

  • Request. url with method (GET when unset), headers and body.
  • Body. A string is sent as written. A table, or any other value, is sent as JSON.
  • Templates in body. Each string is a template. A string that is one reference alone keeps the value's type, so ids = "{{ steps.find.outputs.ids }}" sends a list.
  • Failure. A status outside 2xx fails the step. The error holds the start of the answer.
  • Outputs. status_code, an int, and body, the answer as text. Declared outputs are picked by name from the answer's JSON object, and its other fields are left out.
  • Log. The request, as <METHOD> <url>, and its status are call and result records in the step run's log. The body of the answer is kept, as an output record, only when the status is outside 2xx, and the failure names the log's folder.

Secrets

A secret, such as a token, is never written in the file. Reference an environment variable instead: {{ env.<NAME> }}.

  • Where. Only in the request fields of an api or [mcp](#mcp-steps) step: url, headers, body, command and arguments.
  • Elsewhere it fails at load, because other fields end up in a prompt, a question or a shell command.
  • Unset. The step fails before it sends anything, naming the variable.
  • Shell steps read the variable as $NAME.

The value is hidden from everything the step writes:

  • Its log records, live lines, error and outputs, and so the checkpoint, the --std events and looprail status.
  • Each copy becomes [env.<NAME>], whether plain, JSON-escaped or URL-escaped.
  • An answer that echoes the token holds [env.<NAME>] in its place.

An api step posts JSON with a token from looprail's environment, and reads an output from the JSON answer. (api) Loads.

[metadata]
spec_version = "0.1.0"
name = "notify"

[inputs.static]
title = { type = "string", description = "The title of the note." }

[[step.post]]
kind = "api"
description = "Creates the note."
method = "POST"
url = "https://notes.example.com/api/notes"
headers = { Authorization = "Bearer {{ env.NOTES_TOKEN }}" }
body = { title = "{{ inputs.title }}", pinned = true }

[step.post.outputs]
id = { type = "string", description = "The new note's id." }

[[step.show]]
kind = "shell"
description = "Prints the new note's id and the status."
needs = ["post"]
run = ["echo {{ steps.post.outputs.id }} {{ steps.post.outputs.status_code }}"]

env may not be referenced outside an api or mcp step's request; a shell command reads the variable as $NAME. (env-ref-place) Fails to load, breaking [env-ref-place](#env-ref-place):

[metadata]
spec_version = "0.1.0"
name = "leak"

[[step.show]]
kind = "shell"
description = "Prints the token."
run = ["echo {{ env.NOTES_TOKEN }}"]
step.show.run[0]: {{ env.NOTES_TOKEN }}: env may only be referenced in the url, headers, body, command or arguments of an api or mcp step, where its value is hidden from what the step writes

What this page sets out was brought in by LRP-0013.

mcp steps

Calls tool on an MCP server, reached at url or started with command, with arguments. A redirect from url is not followed, and fails the step. A result marked as an error fails it. Its output is text, the result's text, plus those it declares, picked by name from the structured content, or from the text when it is a JSON object.

  • Needs: kind, description and tool.
  • May set: url, headers, command, env and arguments, and of the fields every kind shares, needs, for_each, when, cwd, failover, on_fail, max_loops and max_retries.
  • May not set: no common field, nor any field of another kind.
  • Declares outputs: yes, in [step.<name>.outputs].
  • Sets outputs itself: text (a string), besides those it declares.
  • Fails over to an agent: no.

The step fields table describes each field.

An mcp step calls one tool on an MCP server. It needs no agent, so a scheduled looprail can call a service by itself.

  • Server. One of:
  • url: streamable HTTP, with headers on every request.
  • command: started by the step and spoken to over stdio, with env merged over its environment.
  • Call. tool with arguments, a table sent as a JSON object.
  • Templates in arguments. Each string is a template. A string that is one reference alone keeps the value's type, as in an [api](#api-steps) step's body.
  • Failure. A result marked as an error fails the step.
  • Outputs. text, the result's text content. Declared outputs are picked by name from the result's structured content, or from text when there is none and text is a JSON object.
  • Log. The call, as <tool> on <server>, and whether it was an error are call and result records in the step run's log, and each line a started server writes to stderr is a stderr record. The result, or the error, is kept, as an output record, only when the call failed, and the failure names the log's folder.
  • Secrets. Request fields may hold {{ env.<NAME> }}, hidden from everything the step writes: see Secrets.

Two mcp steps: one calls a server over HTTP with a token, the other starts a server over stdio. (mcp) Loads.

[metadata]
spec_version = "0.1.0"
name = "post"

[[step.post]]
kind = "mcp"
description = "Posts the summary to Slack through a team's tools."
url = "http://127.0.0.1:1985/mcp"
headers = { Authorization = "Bearer {{ env.MCP_TOKEN }}" }
tool = "slack_post"
arguments = { channel = "C0123", text = "The nightly run passed." }

[step.post.outputs]
ts = { type = "string", description = "The message's timestamp." }

[[step.list]]
kind = "mcp"
description = "Lists the open issues with a server started for the step."
command = ["github-mcp-server", "stdio"]
env = { GITHUB_TOOLSETS = "issues" }
tool = "list_issues"
arguments = { owner = "SkyG-Org", repo = "LoopRail", state = "OPEN" }

An mcp step reaches its server at url or starts it with command, never both. (mcp-server) Fails to load, breaking [mcp-server](#mcp-server):

[metadata]
spec_version = "0.1.0"
name = "post"

[[step.post]]
kind = "mcp"
description = "Posts the summary."
url = "http://127.0.0.1:1985/mcp"
command = ["slack-mcp"]
tool = "slack_post"
step.post: an mcp step sets both url and command; set one

What this page sets out was brought in by LRP-0014.

looprail steps

Runs the looprail file looprail as one node of this one, once, or once per item with for_each, and passes when every run of it passes. Its steps show as <step>/<its step>, or <step>[<item>]/<its step> with for_each. See Looprail steps.

  • Needs: kind, description and looprail.
  • May set: override, and of the fields every kind shares, needs and for_each.
  • May not set: when, cwd, failover, on_fail, max_loops or max_retries, nor any field of another kind.
  • Declares outputs: no.
  • Sets outputs itself: none.
  • Fails over to an agent: no.

The step fields table describes each field.

A looprail step runs another looprail file.

  • Name. needs and references use it like any step's.
  • Its steps show as <step>/<its step>, or <step>[<item>]/<its step> with for_each.
  • Paths. looprail is relative to the directory looprail was started in, not to the file that names it. The looprail's briefs are relative to the looprail itself.
  • Failure. A looprail that fails fails its item.
  • Limits. The step takes no slot of the limits. The looprail's steps share this run's slots.
  • Not allowed: when, cwd, failover, on_fail, max_loops or max_retries, and outputs.

Inputs of the looprail

  • Without for_each, it gets this run's inputs of the same names.
  • With for_each, it runs once per item, all at the same time.
  • Item fields named like the looprail's static inputs are its inputs.
  • Other fields are left out. So an item may carry fields, such as hard below, that only an override's match reads.
  • An item that is not an object is the field item.
  • Inputs are checked like the caller's. A missing or wrong one fails that item.

Overrides

An override swaps the agent for some for_each items. Write it as [[step.<name>.override]] after the step.

  • match reads the current item's fields. They come from the list for_each goes over in this file, never from the looprail it runs.
  • Matching. Each key must equal the item's field of that name: numbers by value, strings and booleans exactly.
  • No match for an item missing the field, or one that is not an object.
  • Without for_each there is no item, so no override applies.
  • Effect. Its agent replaces the agent of every agent and agent-gate step of the looprail, for that item. A --set on one of those steps still applies over it.
  • Several matches. The last wins.
  • No agent step in the looprail fails at load.

Override fields

Written as [[step.<name>.override]], after its [[step.<name>]].

FieldTypeRequiredSinceDescription
matchtable of <field> to any valueyes0.1.0The fields of the for_each item the override applies to: every key must equal the item's field of that name, numbers by value and strings and booleans exactly. The item comes from the list for_each goes over in this file, not from the looprail the step runs, so a field may be one only match reads. An item missing the field, or that is not an object, does not match. Must not be empty. Each value is a string, a number, or true or false.
agentagentyes0.1.0The agent that replaces the agent of every agent and agent-gate step of the looprail, for the items match holds for. When several overrides match an item, the last one wins.

A looprail step runs another looprail once per item, and an override swaps the agent for the items it matches. hard is a field of the plan's items that only match reads, not an input of change.toml, so issue 1 runs with the override's agent and issue 2 with change.toml's own. (looprail-step) Loads.

[metadata]
spec_version = "0.1.0"
name = "batch"

[[step.plan]]
kind = "shell"
description = "Runs plan."
run = ["echo '{\"changes\": [{\"issue\": 1, \"slug\": \"a\", \"hard\": true}, {\"issue\": 2, \"slug\": \"b\", \"hard\": false}]}' > $LOOPRAIL_OUTPUTS"]

[step.plan.outputs]
changes = { type = "list", description = "The changes.", items = { issue = { type = "int" }, slug = { type = "string" }, hard = { type = "bool" } } }

[[step.changes]]
kind = "looprail"
description = "Runs the change looprail on each change."
looprail = "looprails/change.toml"
for_each = "{{ steps.plan.outputs.changes }}"
needs = ["plan"]

[[step.changes.override]]
match = { hard = true }
agent = { command = ["claude-agent-acp"], model = "opus" }

[[step.report]]
kind = "shell"
description = "Runs report."
needs = ["changes"]
run = ["echo {{ steps.changes.status }}"]

looprails/change.toml:

[metadata]
spec_version = "0.1.0"
name = "change"

[inputs.static]
issue = { type = "int", description = "The issue." }
slug = { type = "string", description = "The slug." }

[[step.code]]
kind = "agent"
description = "Runs code."
agent = { command = ["claude-agent-acp"], model = "sonnet" }
brief = "code.md"

looprails/code.md:

Fix issue {{ inputs.issue }}, {{ inputs.slug }}.

An override can only replace an agent. The step has no for_each, so its match could never hold anyway; the error is about kind. (looprail-override-step) Fails to load, breaking [override-step](#override-step):

[metadata]
spec_version = "0.1.0"
name = "batch"

[[step.change]]
kind = "looprail"
description = "Runs the change looprail."
looprail = "change.toml"

[[step.change.override]]
match = { hard = true }
kind = "shell"

change.toml:

[metadata]
spec_version = "0.1.0"
name = "change"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]
step.change.override.kind: an override can only replace an agent; it cannot add, remove or reorder a step

A looprail may not run itself. (looprail-self) Fails to load, breaking [looprail-self](#looprail-self):

[metadata]
spec_version = "0.1.0"
name = "loop"

[[step.again]]
kind = "looprail"
description = "Runs this looprail again."
looprail = "looprail.toml"
step.again.looprail: looprail.toml runs itself

A looprail step has none of the fields of the other kinds, and no when, cwd, failover, on_fail or max_loops. (looprail-has-no) Fails to load, breaking [kind-has-no](#kind-has-no):

[metadata]
spec_version = "0.1.0"
name = "batch"

[[step.change]]
kind = "looprail"
description = "Runs the change looprail."
looprail = "change.toml"
when = "{{ inputs.go }}"

[inputs.static]
go = { type = "bool", description = "Whether to run it." }

change.toml:

[metadata]
spec_version = "0.1.0"
name = "change"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]
step.change.when: a looprail step has no when

The load rules are in Rules for looprail steps.

What this page sets out was brought in by LRP-0015.

Agents

An [agent](#agent-steps) or [agent-gate](#agent-gate-steps) step prompts an agent:

  • Inline: written on the step. A new session per prompt.
  • Named: an [agents.<name>] table. Its session can span steps.

Inline agents

Set agent.provider, agent.command or both.

  • Provider. Resolved to a command at load: the file's [harnesses.<provider>] first, then the built-in harness. Neither fails the load.
  • Command. Wins over provider.
  • Limit. agent.<command[0]>.
  • Running. The command starts in the step's cwd and speaks ACP over stdin and stdout.
  • Model. A name the harness offers, not an API model id. claude-agent-acp offers default, opus, fable, sonnet and haiku.
  • Wrong model. One the harness does not offer or apply fails the step, naming it.
  • Check. looprail doctor <looprail> tries each harness and model a file names.

See Named agents for [harnesses.<name>].

Agent fields

Written as agent = { ... }, on a step or an override. An agent sets name, for a named agent, or an inline harness by provider, command or both.

FieldTypeRequiredSinceDescription
namestring0.1.0The named agent, an [agents.<name>] of this file or of a looprail that runs it. Set name, or provider and command, not both. Must not be empty.
providerstring0.1.0An inline harness by name: one of the file's [harnesses], or a built-in one: claude (claude-agent-acp), codex (codex-acp), grok (grok agent stdio), goose (goose acp), pi (pi-acp). Loading fills in command from it, so command[0] of that argv names the agent limit: provider = "grok" counts against agent.grok. A command set as well wins.
commandlist of strings0.1.0An inline harness and its arguments, started afresh for every prompt. command[0] is found on PATH, and names the agent limit. Needed when neither name nor provider is set. Must not be empty. Each entry: must not be empty.
modelstring0.1.0The model of an inline harness, as the harness names it in its session's model option: claude-agent-acp offers default, opus, fable, sonnet and haiku, so an API model id such as claude-opus-5-5 fails. The step fails when the harness does not offer the model or does not apply it. Unset, the harness's default applies. looprail doctor shows what a harness offers. Only with provider or command: a named agent's model is in its llm.
lifetime-not allowed0.1.0A step's agent has no lifetime: it belongs to the named agent. Setting it fails with lifetime belongs on [agents.<name>], not on a step's agent.

Named agents

Name one with agent = { name = "<name>" }.

  • [agents.<name>] needs both fields:
  • lifetime: how long its session lives.
  • llm: its models, in order, each [[agents.<name>.llm]].
  • The step sets no provider, command, model or lifetime.
  • A step of a looprail this one runs may name it too.
  • A looprail that defines the name again must define it the same.
lifetimeOne session for
stepone step, and the on_fail retries that send the run back to it
itemevery step that names it in one for_each item, nested looprails included
runevery step that names it in the run

LLM rows

A row sets provider, command or both.

  • A provider is:
  • an ACP harness looprail knows,
  • a [harnesses.<name>] of the file, or
  • a backend looprail calls itself, over HTTP or on local weights.
  • command replaces the provider's own harness and arguments.

Sessions

  • Start. The first llm row that starts, in order.
  • Config. Right after session/new, the row's config options are set through session/set_config_option.
  • Next row. A model or option the harness does not offer moves on to the next row.
  • Reuse. The session lasts the agent's lifetime and takes every later prompt, on_fail and human retries included. So each prompt names its own step's fields.
  • Failover. failover = "agent" closes the session and starts a new one, which stays.
  • Inline. An inline agent's session closes when its step ends.
  • Failures. The live session writes a failure's summary and fix, and answers a person's feedback and ask on a failed gate: see Failure. An inline session is gone by then.

Pinning an agent for a run

  • --set @<name> model=<model>,provider=<provider>,command=<command>,llm=<index>,config.<option>=<value> pins a named agent.
  • llm=<index> starts only that row.
  • --set <step> model=... fails on a step that names an agent.

HTTP providers

With no command, these are called through their chat completions API:

ProviderDefault endpointDefault key variable
ollamahttp://127.0.0.1:11434/v1none
openaihttps://api.openai.com/v1OPENAI_API_KEY
openrouterhttps://openrouter.ai/api/v1OPENROUTER_API_KEY
commandcodehttps://api.commandcode.ai/providerCOMMAND_CODE_API_KEY
openai-compatiblenone: set endpointnone
  • endpoint and auth_env replace the defaults.
  • The key is sent as a bearer token. An unset key fails the session's start, naming the variable.
  • No tools and no config.
  • looprail holds the conversation. Closing the session drops it.
  • The reply must end with the step's JSON object.

Local models

goinfer, with no command, loads the GGUF file its model names into looprail's own process.

  • No harness and no network.
  • The conversation lives in memory and unloads with the session.
  • Each reply is held to the JSON object of the step's outputs.
  • One config option: max_tokens, the most tokens in a reply. Default 2048.

Named agent fields

Written as [agents.<name>].

FieldTypeRequiredSinceDescription
lifetimestringyes0.1.0How long the agent's session lives: step, for one step and its on_fail retries; item, for every step that names it in one for_each item, nested looprails included; run, for the whole run. There is no default. Must be one of step, item or run.
llmlist of llmyes0.1.0The models the agent may run on, in order: a session starts on the first that starts, and stays on it. --set @<name> llm=<index> pins one for a run. Must not be empty.

LLM fields

Written as [[agents.<name>.llm]].

FieldTypeRequiredSinceDescription
providerstring0.1.0Who runs the model: an ACP harness (claude, codex, grok, goose or pi, or a [harnesses.<name>] of the file), or a backend looprail calls itself (openrouter, openai, openai-compatible, ollama, goinfer or commandcode). With command, any name is a label. Set provider, command or both.
modelstring0.1.0The model, as the provider names it; for goinfer, the path to a .gguf file, absolute or from the step's cwd.
endpointstring0.1.0The base URL of an HTTP backend: required for openai-compatible, and an override for openrouter, openai, openai-compatible, ollama and commandcode. Any other provider, an ACP harness among them, takes none. Must start with http:// or https://.
auth_envstring0.1.0The name of the environment variable that holds the API key. The file never holds the key. Capital letters, digits and _, not starting with a digit.
commandlist of strings0.1.0The ACP harness and its arguments, in place of the provider's own. Must not be empty. Each entry: must not be empty.
configtable of <option> to any value0.1.0Options of the session, such as effort = "high", applied when it starts. A harness that does not offer one fails the session, naming it. Each value is a string, a number, or true or false.

Harness fields

Written as [harnesses.<name>].

FieldTypeRequiredSinceDescription
commandlist of stringsyes0.1.0The harness and its arguments. command[0] is found on PATH. Must not be empty. Each entry: must not be empty.

A coding loop: a coder whose session lasts through the CI gate's and the review's retries, and a reviewer of its own. (named-agents) Loads.

[metadata]
spec_version = "0.1.0"
name = "code-loop"

[agents.coder]
lifetime = "step"

[[agents.coder.llm]]
provider = "codex"
model = "gpt-5.1-codex"
config = { effort = "high" }

[[agents.coder.llm]]
provider = "claude"
model = "opus"

[agents.reviewer]
lifetime = "step"

[[agents.reviewer.llm]]
provider = "claude"
model = "sonnet"

[[step.code]]
kind = "agent"
description = "Implements the task."
agent = { name = "coder" }
brief = "briefs/code.md"

[[step.ci]]
kind = "shell-gate"
description = "Runs the tests."
needs = ["code"]
run = ["make test"]
accept_exit = [0]
on_fail = "code"
max_loops = 5

[[step.review]]
kind = "agent-gate"
description = "Reviews the change."
needs = ["ci"]
agent = { name = "reviewer" }
brief = "briefs/review.md"
accept = "accept"
on_fail = "code"
max_loops = 2

briefs/code.md:

Implement the task.

briefs/review.md:

Review the change.

An extra harness, an OpenAI-compatible backend whose key is in an environment variable, and an inline agent beside them. (harnesses) Loads.

[metadata]
spec_version = "0.1.0"
name = "triage"

[harnesses.amp]
command = ["amp-acp"]

[agents.triager]
lifetime = "run"

[[agents.triager.llm]]
provider = "amp"

[[agents.triager.llm]]
provider = "openai-compatible"
endpoint = "https://api.groq.com/openai/v1"
auth_env = "GROQ_API_KEY"
model = "llama-3.3-70b-versatile"

[[step.triage]]
kind = "agent"
description = "Sorts the issues."
agent = { name = "triager" }
brief = "brief.md"

[[step.second]]
kind = "agent-gate"
description = "Checks the sorting."
needs = ["triage"]
agent = { command = ["claude-agent-acp"], model = "opus" }
brief = "brief.md"
accept = "ok"

brief.md:

Do it.

A looprail step whose looprail names the coder of the file that runs it: with lifetime = "item", each item has one coder session, shared with the steps it runs. (nested-agents) Loads.

[metadata]
spec_version = "0.1.0"
name = "tickets"

[agents.coder]
lifetime = "item"

[[agents.coder.llm]]
provider = "claude"
model = "opus"

[inputs.static]
tickets = { type = "string", description = "The tickets, as a JSON list." }

[[step.list]]
kind = "shell"
description = "Lists the tickets."
run = ["echo {{ inputs.tickets }}"]

[step.list.outputs]
tickets = { type = "list", description = "The tickets." }

[[step.each]]
kind = "looprail"
description = "Implements each ticket."
needs = ["list"]
for_each = "{{ steps.list.outputs.tickets }}"
looprail = "implement.toml"

code.md:

Implement the ticket.

implement.toml:

[metadata]
spec_version = "0.1.0"
name = "implement"

[[step.code]]
kind = "agent"
description = "Implements the ticket."
agent = { name = "coder" }
brief = "code.md"

A step's brief is described in Briefs.

The load rules are in Rules for named agents.

What this page sets out was brought in by LRP-0016.

Briefs

A brief is the file that holds an agent step's prompt.

  • brief is a path relative to the looprail file.
  • It is read at load, and its references are checked like any template's.
  • A missing brief, or an unresolved reference in one, fails the file.

For --continue, a brief is part of the looprail:

  • The checkpoint holds a hash of every brief read, by absolute path, of every looprail file and of the static inputs.
  • A changed hash refuses the run, naming each: the brief <path> changed since the checkpoint.
  • A checkpoint from before briefs were hashed is refused: the checkpoint was saved by an older looprail that did not record briefs, so use --fresh.

The load rules are in Rules for briefs.

What this page sets out was brought in by LRP-0016.

Outputs

Later steps read a step's outputs as {{ steps.<name>.outputs.<output> }}.

Declared outputs

  • Agent, agent-gate, shell, shell-gate, api and mcp steps declare outputs in [step.<name>.outputs].
  • A step must set exactly those. A missing or undeclared output, a wrong type or a value out of bounds fails the step.
  • An api or mcp step picks them out of an answer that may hold more.

Outputs a kind sets

KindOutputs
humananswer, a string
agent-gateverdict, a string, besides those it declares
apistatus_code, an int, and body, a string, besides those it declares: see [api steps](#api-steps)
mcptext, a string, besides those it declares: see [mcp steps](#mcp-steps)
decision-modelone per question, of the same name: see Questions

A decision-model question sets:

  • choice: an enum of its criteria keys.
  • yes-no: a float from 0 to 1.
  • score: a float from 0 to the index of its last level.
  • choice and score also set <question>_confidence and, with probabilities = true, <question>_probabilities.

These outputs are never declared, so they have no description. Only a declared output needs one.

  • A human or decision-model step that sets outputs fails: its kind has none.
  • An agent-gate that declares verdict fails: it is the gate's own.
  • An api or mcp step may not declare the outputs its kind sets.

How a step writes its outputs

Shell. The commands write to the file named by $LOOPRAIL_OUTPUTS, empty when the step starts.

  • KEY=value lines, or one JSON object.
  • Any command may append lines. A later line wins.
  • A list must be JSON.
  • $LOOPRAIL_CURRENT_RUN_DIR holds the run folder's absolute path, for files a later step reads.

Agent. The last message must end with one JSON object holding the outputs.

  • A closing code fence after it is allowed.
  • The prompt lists the fields it must hold.

Output fields

Written as [step.<name>.outputs], one key per output.

FieldTypeRequiredSinceDescription
typestringyes0.1.0The output's type. See Types. Must be one of string, enum, bool, int, float or list.
descriptionstringyes0.1.0One sentence on what the output holds. An agent step's prompt shows it beside the output's type. The outputs a kind sets itself, such as answer or verdict, are never declared, so they have none. Must not be blank.
default-not allowed0.1.0Outputs have no default. Setting it fails with an output has no default.
valueslist of strings0.1.0An enum's values. An enum needs them, and only an enum has them. Must not be empty.
min_lengthwhole number0.1.0A string's least length, in characters. At least 0.
max_lengthwhole number0.1.0A string's greatest length, in characters. Not below min_length.
minnumber0.1.0A number's lower bound. An int's bounds are whole numbers.
maxnumber0.1.0A number's upper bound. Not below min.
itemstable of <field> to item field0.1.0The fields every item of a list holds. Each item must then be an object holding those fields with those types, and may hold others too. A list without items holds anything, and each.<field> on its items is not checked at load. Must not be empty.

Item field fields

Written as items = { <field> = { ... } }, on a list.

FieldTypeRequiredSinceDescription
typestringyes0.1.0The field's type. See Types. Must be one of string, enum, bool, int, float or list.
descriptionstring0.1.0What the field holds. Unlike an input's or an output's, it may be left out.
default-not allowed0.1.0Item fields have no default. Setting it fails with an item field has no default.
valueslist of strings0.1.0An enum's values. An enum needs them, and only an enum has them. Must not be empty.
min_lengthwhole number0.1.0A string's least length, in characters. At least 0.
max_lengthwhole number0.1.0A string's greatest length, in characters. Not below min_length.
minnumber0.1.0A number's lower bound. An int's bounds are whole numbers.
maxnumber0.1.0A number's upper bound. Not below min.
itemstable of <field> to item field0.1.0The fields every item of a list holds. Each item must then be an object holding those fields with those types, and may hold others too. A list without items holds anything, and each.<field> on its items is not checked at load. Must not be empty.

A shell step writes its outputs to $LOOPRAIL_OUTPUTS, as KEY=value lines or one JSON object. (shell-outputs) Loads.

[metadata]
spec_version = "0.1.0"
name = "outputs"

[[step.pr]]
kind = "shell"
description = "Opens a pull request."
run = [
  "gh pr create --fill | tail -1 | sed 's/^/url=/' >> $LOOPRAIL_OUTPUTS",
  "echo draft=true >> $LOOPRAIL_OUTPUTS",
]

[step.pr.outputs]
url = { type = "string", description = "The pull request's URL." }
draft = { type = "bool", description = "Whether it opened as a draft." }

[[step.report]]
kind = "shell"
description = "Lists the files the change touched."
needs = ["pr"]
run = ["echo '{\"files\": [\"a.go\", \"b.go\"]}' > $LOOPRAIL_OUTPUTS"]

[step.report.outputs]
files = { type = "list", description = "The paths of the changed files." }

An output has no default. (output-default) Fails to load, breaking [output-default](#output-default):

[metadata]
spec_version = "0.1.0"
name = "outputs"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo n=1 >> $LOOPRAIL_OUTPUTS"]

[step.a.outputs]
n = { type = "int", description = "The n.", default = 0 }
step.a.outputs.n.default: an output has no default

A declared output says what it holds, as every static input and step says what it is for. (description-required) Fails to load, breaking [description-required](#description-required):

[metadata]
spec_version = "0.1.0"
name = "outputs"

[[step.count]]
kind = "shell"
description = "Counts the Go files."
run = ["echo n=$(ls *.go | wc -l) >> $LOOPRAIL_OUTPUTS"]

[step.count.outputs]
n = { type = "int" }
step.count.outputs.n.description: is required

A human step's output is answer, which its kind sets, so it declares none. (human-outputs) Fails to load, breaking [kind-has-no](#kind-has-no):

[metadata]
spec_version = "0.1.0"
name = "outputs"

[[step.ask]]
kind = "human"
description = "Runs ask."
ask = "Which branch?"

[step.ask.outputs]
answer = { type = "string", description = "The answer." }
step.ask.outputs: a human step has no outputs

An agent-gate's verdict is its own output, and may not be declared. (verdict-declared) Fails to load, breaking [verdict-declared](#verdict-declared):

[metadata]
spec_version = "0.1.0"
name = "outputs"

[[step.review]]
kind = "agent-gate"
description = "Runs review."
agent = { command = ["claude-agent-acp"] }
brief = "review.md"
accept = "accept"

[step.review.outputs]
verdict = { type = "string", description = "The verdict." }

review.md:

Review it.
step.review.outputs.verdict: verdict is the gate's own output

The load rules are in Rules for types and Rules for steps.

What this page sets out was brought in by LRP-0017.

References

A template is text with references in {{ }}. Each {{ }} holds one reference, never an expression. They may appear in:

  • run, ask, cwd, state and for_each,
  • a brief's text,
  • an api or mcp step's request fields: url, headers, body, command and arguments,
  • a derived input,
  • when, which holds an expression.
ReferenceIs
{{ inputs.<name> }}A static or derived input.
{{ steps.<name>.outputs.<output> }}One output of a step.
{{ steps.<name>.outputs }}A for_each step's entries: a list.
{{ steps.<name>.status }}One of pending, running, passed, failed or skipped.
{{ steps.<name>.loops }}How many times the step has run, from 1.
{{ steps.<name>.accepted }}Whether a gate passed.
{{ each }} and {{ each.<field> }}The item of a for_each step, and one of its fields.
{{ env.<NAME> }}A variable of the environment looprail runs in, only in the request fields of an api or mcp step, and hidden from all the step writes. See Secrets.
  • Names. Letters, digits, _ and -, starting with a letter or _. Any other name goes in double quotes: {{ steps."needs work".status }}. Errors quote it the same way: step."needs work".kind.
  • Through needs. A referenced step must be in needs, directly or through other steps. So a step cannot reference itself.
  • for_each steps have no single outputs: steps.<name>.outputs.<output> fails at load. Go over the entries with another for_each.
  • each is valid only in a step with for_each.
  • Checked at load: the step, the output and, where known, the type.
  • In a shell command a reference becomes one quoted word: see shell quoting.
  • Elsewhere it is plain text. A list or object is written as JSON.
  • No value. A reference with no value, such as an output of a skipped step, fails the step that uses it.

A step can reference only the steps it needs, directly or through others. (unreachable) Fails to load, breaking [unreachable](#unreachable):

[metadata]
spec_version = "0.1.0"
name = "refs"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo n=1 >> $LOOPRAIL_OUTPUTS"]

[step.a.outputs]
n = { type = "int", description = "The n." }

[[step.b]]
kind = "shell"
description = "Runs b."
run = ["echo {{ steps.a.outputs.n }}"]
step.b.run[0]: {{ steps.a.outputs.n }}: step "a" is not reachable through needs, so it may not have run

A reference to an output the step does not have fails, listing the ones it has. (no-such-output) Fails to load, breaking [no-such-output](#no-such-output):

[metadata]
spec_version = "0.1.0"
name = "refs"

[[step.a]]
kind = "human"
description = "Runs a."
ask = "Name?"

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["echo {{ steps.a.outputs.name }}"]
step.b.run[0]: {{ steps.a.outputs.name }}: step "a" has no output "name" (it has answer)

when

when is one {{ }} holding a true-or-false expression. It may hold:

  • references,
  • 'strings' or "strings", with no escapes, so a string cannot hold its own quote,
  • numbers, true and false,
  • ==, !=, !, &&, || and parentheses.

|| binds loosest, then &&, then !, then == and !=. == and != do not chain: !a == b is !(a == b).

  • Comparing. Numbers compare by value. Values of different types are never equal.
  • Types. Comparing two known, different types fails at load. So does a known non-boolean with !, && or ||.
  • Enums. Comparing an enum with a string that is not one of its values fails at load. Enums are an enum input or output, a choice question and a step's status.
  • No value. A reference with no value equals nothing: == is false, != true.
  • With for_each, when is checked per item. Items where it is false are skipped. A step with every item skipped, or an empty list, is skipped.

when compares references with literals, and combines them with &&, || and !. (when) Loads.

[metadata]
spec_version = "0.1.0"
name = "when"

[inputs.static]
mode = { type = "enum", description = "The mode.", values = ["fast", "full"], default = "full" }

[[step.test]]
kind = "shell-gate"
description = "Runs test."
run = ["go test ./..."]
accept_exit = [0, 1]

[[step.report]]
kind = "shell"
description = "Runs report."
needs = ["test"]
when = "{{ inputs.mode == 'full' && (steps.test.status == 'passed' || !steps.test.accepted) }}"
run = ["echo done"]

Comparing an enum with a string that is not one of its values fails at load. (when-enum) Fails to load, breaking [when-enum-value](#when-enum-value):

[metadata]
spec_version = "0.1.0"
name = "when"

[inputs.static]
mode = { type = "enum", description = "The mode.", values = ["fast", "full"] }

[[step.report]]
kind = "shell"
description = "Runs report."
when = "{{ inputs.mode == 'quick' }}"
run = ["echo done"]
step.report.when: "quick" is not one of the values of inputs.mode (fast, full)

Comparing two known types that differ fails at load. (when-types) Fails to load, breaking [when-compare-types](#when-compare-types):

[metadata]
spec_version = "0.1.0"
name = "when"

[inputs.static]
n = { type = "int", description = "The n." }

[[step.report]]
kind = "shell"
description = "Runs report."
when = "{{ inputs.n == 'one' }}"
run = ["echo done"]
step.report.when: == compares a number with a string

for_each

for_each is one reference to a list: a list output, or another for_each step's steps.<name>.outputs.

  • Running. Once per item, all at the same time, each taking its own slot of the limits, in item order.
  • The item. {{ each }}, with {{ each.<field> }} for one field.
  • Entries. The step's steps.<name>.outputs is the list of its entries: each item's fields plus the outputs the step set for it.
  • Non-objects. An item that is not an object becomes the entry {"item": <value>}.

each.<field> is checked at load when the items' shape is known.

  • The shape is the items of a list output. For a for_each step's entries, it is the source's item fields plus the step's own outputs.
  • Known shape. A field it does not name fails, naming the fields it has. when checks against the field's type.
  • Unknown shape, when a list on the way has no items. A named field is still typed, and any other field is accepted at load. An item without the field has no value at run time.

When the items declare their fields, each.<field> is checked at load. (for-each-field) Fails to load, breaking [no-such-item-field](#no-such-item-field):

[metadata]
spec_version = "0.1.0"
name = "each"

[[step.list]]
kind = "shell"
description = "Runs list."
run = ["echo '{\"files\": [{\"path\": \"a.go\"}]}' > $LOOPRAIL_OUTPUTS"]

[step.list.outputs]
files = { type = "list", description = "The files.", items = { path = { type = "string" } } }

[[step.lint]]
kind = "shell"
description = "Runs lint."
needs = ["list"]
for_each = "{{ steps.list.outputs.files }}"
run = ["gofmt -l {{ each.name }}"]
step.lint.run[0]: {{ each.name }}: the items have no field "name" (they have path)

A for_each step's outputs are its entries: each item's fields plus the outputs the step set for it. (for-each-entries) Loads.

[metadata]
spec_version = "0.1.0"
name = "each"

[[step.list]]
kind = "shell"
description = "Runs list."
run = ["echo '{\"files\": [{\"path\": \"a.go\"}]}' > $LOOPRAIL_OUTPUTS"]

[step.list.outputs]
files = { type = "list", description = "The files.", items = { path = { type = "string" } } }

[[step.count]]
kind = "shell"
description = "Runs count."
needs = ["list"]
for_each = "{{ steps.list.outputs.files }}"
run = ["wc -l < {{ each.path }} | sed 's/^/lines=/' >> $LOOPRAIL_OUTPUTS"]

[step.count.outputs]
lines = { type = "int", description = "The lines." }

[[step.big]]
kind = "shell"
description = "Runs big."
needs = ["count"]
for_each = "{{ steps.count.outputs }}"
when = "{{ each.lines != 0 }}"
run = ["echo {{ each.path }}"]

The load rules are in Rules for templates, Rules for references, [Rules for when](#rules-for-when) and [Rules for for_each](#rules-for-for_each).

What this page sets out was brought in by LRP-0018, LRP-0019 and LRP-0020.

Shell quoting

Each entry of run runs through sh -c. A reference becomes one single-quoted word, so no value can change how the shell reads the command. Write it bare: echo {{ inputs.title }}.

What works

  • Next to plain text, outside quotes: --title={{ x }}, pre-{{ x }} or {{ x }}/sub. The value stays part of that one word.
  • Lists. A list must stand alone as a word. It becomes one quoted word per element.
  • Lists after a flag. With a flag word just before the list (-x or --name, only blanks between), the flag is repeated before each element. An empty list drops the flag. The flag is read from the command's text, never from values filled in before it.

What fails to load

Each fails the file, naming the command as step.<name>.run[<n>]. A reference:

  • Inside the command's quotes: '...{{ x }}...' or "...{{ x }}...".
  • In a here-document, or right after a \ or a $.
  • Anywhere after the shell starts quoting afresh: $(, a backtick, ${, $((, ((, $[, $' or $". Set a variable first, as in X={{ x }}; echo "$(f "$X")", or use a pipe.
  • Anywhere after a comment, a # that starts a word outside quotes. The shell ignores quotes inside it. A # inside a word or quotes is not a comment. Put comments after the last reference.
  • After a backslash-newline, which the shell deletes before reading the command. Keep a command with references on one line.

The check prefers a load error to a risk, so it rejects some safe forms too, such as any reference after a here-document.

A reference is one quoted word, which may be glued to plain text outside quotes. A list after a flag repeats the flag. (shell-glued) Loads.

[metadata]
spec_version = "0.1.0"
name = "shell"

[inputs.static]
title = { type = "string", description = "The title." }

[[step.labels]]
kind = "shell"
description = "Runs labels."
run = ["echo '{\"labels\": [\"bug\", \"ci\"]}' > $LOOPRAIL_OUTPUTS"]

[step.labels.outputs]
labels = { type = "list", description = "The labels." }

[[step.issue]]
kind = "shell"
description = "Runs issue."
needs = ["labels"]
run = [
  "gh issue create --title={{ inputs.title }} --body - --label {{ steps.labels.outputs.labels }} < /dev/null",
  "X={{ inputs.title }}; echo \"$(printf %s \"$X\")\"",
]

A reference inside the command's own quotes fails: it is quoted for you. (shell-in-quotes) Fails to load, breaking [shell-in-quotes](#shell-in-quotes):

[metadata]
spec_version = "0.1.0"
name = "shell"

[inputs.static]
title = { type = "string", description = "The title." }

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo \"title: {{ inputs.title }}\""]
step.a.run[0]: {{ inputs.title }} is inside quotes; a reference is quoted for you, so write it bare, as in echo {{ inputs.title }}

A reference after $(, a backtick, ${ and the like fails, because the shell quotes afresh inside them. (shell-substitution) Fails to load, breaking [shell-nested](#shell-nested):

[metadata]
spec_version = "0.1.0"
name = "shell"

[inputs.static]
pr = { type = "int", description = "The pr." }

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["test \"$(gh pr view {{ inputs.pr }} --json state --jq .state)\" = MERGED"]
step.a.run[0]: {{ inputs.pr }} comes after a $(, ${, $((, backtick or similar, inside which the shell quotes afresh; set a variable first, as in X={{ inputs.title }}; echo "$(f "$X")"

Use a pipe where a "$(...)" would hold a reference. (shell-pipe) Loads.

[metadata]
spec_version = "0.1.0"
name = "shell"

[inputs.static]
pr = { type = "int", description = "The pr." }

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["gh pr view {{ inputs.pr }} --json state --jq .state | grep -qx MERGED"]

A reference after a # comment fails. (shell-comment) Fails to load, breaking [shell-comment](#shell-comment):

[metadata]
spec_version = "0.1.0"
name = "shell"

[inputs.static]
title = { type = "string", description = "The title." }

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true # it's {{ inputs.title }}"]
step.a.run[0]: {{ inputs.title }} comes after a # comment, inside which the shell ignores quotes; put comments after the last reference, or drop them

A reference right after a $ or a \ fails. (shell-dollar) Fails to load, breaking [shell-dollar](#shell-dollar):

[metadata]
spec_version = "0.1.0"
name = "shell"

[inputs.static]
var = { type = "string", description = "The var." }

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo ${{ inputs.var }}"]
step.a.run[0]: {{ inputs.var }} follows a $, which would change its quoting

A reference in or after a here-document fails. (shell-heredoc) Fails to load, breaking [shell-heredoc](#shell-heredoc):

[metadata]
spec_version = "0.1.0"
name = "shell"

[inputs.static]
body = { type = "string", description = "The body." }

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["cat <<EOF > out.txt\n{{ inputs.body }}\nEOF"]
step.a.run[0]: {{ inputs.body }} is inside a here-document, where quoting does not apply

A reference after a backslash-newline fails. (shell-continued) Fails to load, breaking [shell-continued](#shell-continued):

[metadata]
spec_version = "0.1.0"
name = "shell"

[inputs.static]
title = { type = "string", description = "The title." }

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["gh issue create \\\n  --title {{ inputs.title }}"]
step.a.run[0]: {{ inputs.title }} comes after a backslash-newline, which the shell deletes before reading the command; keep the command on one line, or split it into two commands

The load rules are in Rules for shell quoting.

What this page sets out was brought in by LRP-0021.

Failure

A step fails when:

  • a command exits non-zero,
  • an agent's JSON does not match its outputs,
  • a gate rejects, or
  • a reference has no value.

A failed command's error ends with the last 80 lines of its output (about 8 KB at most) and the path of the step run's log folder.

on_fail handles a failure first, then failover.

Going back with on_fail

  • The run goes back to the on_fail step while max_loops allows. Unset, there is no cap.
  • That step and everything downstream go back to pending. Any still running is cancelled.
  • steps.<name>.loops counts the runs.
  • A usage-limit failure does not loop. It goes to failover.

Handing over with failover

  • failover = "agent": a new session of the same agent gets the brief and the failure. If it fails too, the run stops.
  • failover = "human": a person is asked Step <name> failed: <error>. Continue, or stop?.

What the person sees

  • The error, the end of a failed command's output and the path of the step run's log folder, which holds all of that output, or the records of a failed api or mcp call.
  • A summary, if any: see The failure summary.
  • The actions retry, skip and stop.
  • feedback (while retries are left) and ask, when a failed gate's on_fail target, or the gate itself, names an agent with a live session.

The actions

  • retry runs the step again in the same loop, with the answer's text as feedback.
  • An agent or agent-gate step is prompted again with the error, the summary if there is one (the failure's, or the step's summary output) and A person reviewed the failure and says: <feedback>.
  • Any other step runs again as it is, after a fix if there is feedback.
  • A second failure asks again, with the new error.
  • skip passes the step, keeping its outputs, entries and error. A gate's accepted stays false. Only an explicit skip does this.
  • stop, as an action or plain text, ends the run with exit 1.
  • feedback prompts the live session with the error and A person reviewed the failure and says: <text>, then runs the gate again. Costs a retry.
  • ask prompts the live session with the error and the question, or asks why it failed when the text is empty. The person is asked again with the answer in failure.reply. Costs no retry and may be repeated.
  • Anything else is refused with a line on the run's output, and the question is asked again.

Neither feedback nor ask starts a new session.

Retries

  • max_retries per loop, 3 by default. After that only skip and stop are offered.
  • steps.<name>.loops does not count them.
  • Each retry's files go in a retry-<n> folder of the loop's.

Fixing a step that is not an agent

  • A retry with feedback first prompts the upstream agent's live session, in place, to fix what failed.
  • With no live session, the step just runs again.
  • Time limit: DefaultFixWait, 30 minutes. ask and feedback have 30 minutes too.
  • A failure or timeout of any of the three shows as failure.session_error.

The failure summary

looprail fills the question's summary before asking.

  • Who writes it.
  • Usage limit: a fixed sentence, no prompt.
  • Agent or agent-gate step: its own session, before it closes.
  • Any other step: the live session of its nearest upstream agent step, in place.
  • What. At most four sentences on what failed and the likely cause. No new session.
  • Where. failure-summary.md in the step's folder. A retry passes it to the agent step it reruns.
  • Time limit. 10 seconds. Failing or slower, the summary is could not generate summary.
  • None with no live session: after an inline agent, or with no agent upstream.
  • Not asked for when:
  • on_fail or failover = "agent" handles the failure,
  • a gate's rejection is sent ahead, or
  • an agent turn ran past idle_limit.

Sending a rejection ahead

A gate without for_each may name a downstream step in on_fail. Its rejection goes ahead to the steps that act on it, then the gate runs again. When it rejects:

  • It settles as passed, with accepted = false, its outputs, and the verdict as its error. Later steps run and read its outputs.
  • The run returns to the gate once the on_fail step settles. The gate and everything downstream go back to pending.
  • Make the on_fail step settle last, through its needs. A downstream step still running then is cancelled.
  • max_loops is required, or the file fails to load. max_loops = 3 runs the gate at most four times.
  • Past the cap the run goes on with the gate rejected. A step after the on_fail step with when = "{{ steps.<gate>.accepted == false }}" runs only then.
  • A crash, as opposed to a rejection, goes to failover.

A human step answered stop ends the run at once, with no failover.

Only an agent or agent-gate step can fail over to an agent. (failover-agent) Fails to load, breaking [failover-agent](#failover-agent):

[metadata]
spec_version = "0.1.0"
name = "kinds"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]
failover = "agent"
step.a.failover: only an agent or agent-gate step can fail over to an agent

A failure sends the run back to the step itself or one upstream of it, max_loops times at most. (loop-back) Loads.

[metadata]
spec_version = "0.1.0"
name = "failure"

[[step.build]]
kind = "shell"
description = "Runs build."
run = ["make"]

[[step.test]]
kind = "shell"
description = "Runs test."
needs = ["build"]
run = ["make test"]
on_fail = "build"
max_loops = 2

A gate that sends its rejection ahead must set max_loops. (ahead-no-max-loops) Fails to load, breaking [ahead-max-loops](#ahead-max-loops):

[metadata]
spec_version = "0.1.0"
name = "failure"

[[step.check]]
kind = "shell-gate"
description = "Runs check."
run = ["make lint"]
accept_exit = [0]
on_fail = "fix"

[[step.fix]]
kind = "shell"
description = "Runs fix."
needs = ["check"]
run = ["make fix"]
step.check.max_loops: must be set, because on_fail sends this gate's rejection ahead to "fix"

Only a gate without for_each may send its failure ahead. (ahead-not-gate) Fails to load, breaking [on-fail-ahead](#on-fail-ahead):

[metadata]
spec_version = "0.1.0"
name = "failure"

[[step.build]]
kind = "shell"
description = "Runs build."
run = ["make"]
on_fail = "fix"
max_loops = 1

[[step.fix]]
kind = "shell"
description = "Runs fix."
needs = ["build"]
run = ["make fix"]
step.build.on_fail: "fix" is downstream of this step; only a gate without for_each may send its rejection ahead

max_loops needs an on_fail to cap. (max-loops-alone) Fails to load, breaking [max-loops-alone](#max-loops-alone):

[metadata]
spec_version = "0.1.0"
name = "failure"

[[step.build]]
kind = "shell"
description = "Runs build."
run = ["make"]
max_loops = 3
step.build.max_loops: has no on_fail to cap

The load rules are in Rules for needs and loops.

What this page sets out was brought in by LRP-0022.

Limits

A limit caps how many steps run at once. Each step that takes a slot counts against one key.

StepKey
shell, shell-gateshell
agent, agent-gate with an inline harnessagent.<command[0]>
decision-modeldecision-model.<provider>, from the first llm row of its decision model
human, looprailnone

An unset key has no cap.

Named agents and slots

  • A step that names an agent counts against the harness of the agent's pinned llm row, or its first row.
  • An HTTP llm row has no key, so the step takes no slot.
  • A step that names an agent takes its slot when it starts and gives it back when it settles, as any step does.
  • Its session stays live between steps for as long as its lifetime (step, item or run) says, but holds no slot while idle.
  • A step that resumes a live session waits for a free slot like any other step, then gets the same session, with its conversation. One step at a time uses a session.

Limits across looprail steps

Limits are worked out per key before anything runs:

  1. --limit key=N wins.
  2. Then a key this file sets.
  3. Then the largest value any looprail it runs sets.

The whole run has one pool of slots per key.

Limits fields

Written as [limits].

FieldTypeRequiredSinceDescription
agenttable of <command> to limit0.1.0Caps agent and agent-gate steps by agent.command[0] exactly as written (a step naming an agent counts against the harness of its agent's pinned llm row, or of its first row), not its base name: ["npx", "claude-agent-acp"] counts against agent.npx. Quote a command that is not a plain name: [limits.agent."/usr/bin/claude-agent-acp"].
shelllimit0.1.0Caps shell and shell-gate steps.
decision-modeltable of <provider> to limit0.1.0Caps decision-model steps by the provider of the first llm row of their decision model. Each key must be jev.

Limit fields

Written as [limits.shell], [limits.agent.<command>] and [limits.decision-model.<provider>].

FieldTypeRequiredSinceDescription
max_parallelwhole numberyes0.1.0How many such steps, or for_each items, of this run run at once. Every step also counts against its kind's limit, which every run in the home shares and looprail run --kind-limit sets: agent, shell, mcp and api. At least 1.

Limits by key. (limits) Loads.

[metadata]
spec_version = "0.1.0"
name = "limits"

[limits.shell]
max_parallel = 4

[limits.agent.claude-agent-acp]
max_parallel = 2

[limits.decision-model.jev]
max_parallel = 1

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

A decision-model limit must name a provider. (limits-provider) Fails to load, breaking [provider](#provider):

[metadata]
spec_version = "0.1.0"
name = "limits"

[limits.decision-model.gpt]
max_parallel = 1

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]
limits.decision-model.gpt: "gpt" is not a provider; use one of jev

The load rules are in Rules for limits.

What this page sets out was brought in by LRP-0023.

Load rules

Every load error comes from one of these rules, and nothing else fails a load.

  • Each rule has an example that breaks it.
  • The generator loads every example and checks it fails with that rule alone, so this list cannot fall behind the loader.
  • The rules are in internal/spec/rules.go and internal/spec/tmpl/rules.go.

A new check needs:

  1. a rule in one of those files,
  2. an example that breaks it, in internal/docgen/specdoc,
  3. the generator run again.

A load error with no rule fails the tests. A rule with no example fails the generator.

The table.

  • Each group of rules has a page, showing each rule with its examples.
  • The last column says whether looprail.schema.json rejects the rule's examples too, which the tests check: see What the schema can't check.
  • An example from a subject page is linked, with only its error.
  • The operating system's wording in an error shows as <the system's error>, and Go's JSON decoder's as <the JSON decoder's error>. Both differ between systems or Go versions, and this keeps the pages the same everywhere.
RuleGroupWhat breaks itThe schema rejects it
[config-unknown-key](#config-unknown-key)the file[config] sets a key the table does not have.yes
[file-read](#file-read)the fileThe looprail file cannot be read, as when it does not exist.no: there is no file
[json-encode](#json-encode)the fileA JSON file cannot be turned into TOML.not known: no example
[json-null](#json-null)the fileA JSON file holds null.yes
[json-number](#json-number)the fileA JSON number is too large to hold.yes
[json-object](#json-object)the fileA JSON file is not one JSON object.yes
[json-shape](#json-shape)the fileA JSON file has text after its object, or an inputs that is not an object.yes
[json-step](#json-step)the fileA JSON file's step is not an object of step name to step.yes
[json-step-entry](#json-step-entry)the fileA step in a JSON file is not an object, or a list holding one object.yes
[metadata-required](#metadata-required)the fileThe file has no [metadata] table.yes
[metadata-unknown-key](#metadata-unknown-key)the file[metadata] sets a key the table does not have.yes
[name-required](#name-required)the file[metadata] has no name, or a blank one.yes
[no-steps](#no-steps)the fileThe file has no step.yes
[spec-major](#spec-major)the filespec_version has a major other than the one this looprail reads.yes
[spec-since](#spec-since)the fileA file sets a field, or uses a kind, that entered the format in a spec version higher than its spec_version.not known: no example
[spec-too-new](#spec-too-new)the filespec_version has the major this looprail reads, but is higher than the version it supports.no
[spec-version-format](#spec-version-format)the filespec_version is not a plain MAJOR.MINOR.PATCH, such as v0.1, 0.1 or 0.1.0-rc1.yes
[spec-version-required](#spec-version-required)the file[metadata] has no spec_version, or a blank one.yes
[step-twice](#step-twice)the fileTwo [[step.<name>]] tables share a name.yes
[toml-syntax](#toml-syntax)the fileThe file is not valid TOML.yes
[toml-type](#toml-type)the fileThe TOML decoder rejects the file for a reason other than its syntax, most often a value of the wrong type for its field, such as a string where a list goes.yes
[unknown-field](#unknown-field)the fileThe file sets a field the format does not have.yes
[whole-number](#whole-number)the fileA field that takes a whole number holds a fraction, such as max_loops = 2.5, an infinity or NaN, or a value that is not a number.yes
[whole-number-range](#whole-number-range)the fileA field that takes a whole number holds a float of 2^53 or more, such as max_loops = 1e300, which the loader cannot hold exactly.no
[default](#default)inputsAn input's default is of the wrong type, or outside its bounds or its values.no
[derived-ref](#derived-ref)inputsA derived input references anything but a static input.no
[derived-shares-name](#derived-shares-name)inputsA derived input is named like a static input.no
[bound-order](#bound-order)typesmin exceeds max.no
[bound-type](#bound-type)typesA bound is set on a type it does not apply to: min_length or max_length on anything but a string, min or max on anything but an int or a float.yes
[enum-values](#enum-values)typesAn enum has no values, or an empty list.yes
[int-bound](#int-bound)typesAn int's min or max is not a whole number.no
[item-default](#item-default)typesAn item field sets default.yes
[items-empty](#items-empty)typesA list's items names no fields.yes
[items-not-list](#items-not-list)typesA type that is not a list sets items.yes
[kind-output-declared](#kind-output-declared)typesAn api or mcp step declares an output its kind sets itself: status_code or body on an api step, text on an mcp step.no
[length-order](#length-order)typesmin_length exceeds max_length.no
[min-length-negative](#min-length-negative)typesmin_length is negative.yes
[output-default](#output-default)typesAn output sets default.yes
[type](#type)typesA declaration's type is not one of the types it may have.yes
[values-not-enum](#values-not-enum)typesA type that is not an enum sets values.yes
[verdict-declared](#verdict-declared)typesAn agent-gate declares an output named verdict, which is its own.no
[accept-exit-empty](#accept-exit-empty)stepsA shell-gate's accept_exit is an empty list.yes
[api-method](#api-method)stepsAn api step's method is not one of the methods.yes
[choice-criteria](#choice-criteria)stepsA choice question has no criteria.yes
[choices](#choices)stepsA human step's choices is an empty list, or holds a blank or repeated choice.yes
[command-empty-arg](#command-empty-arg)stepsAn entry of an agent's or an llm row's command is empty.yes
[command-required](#command-required)stepsAn inline agent's or an llm row's command is an empty list.yes
[criteria-not-choice](#criteria-not-choice)stepsA question that is not a choice sets criteria.yes
[description-required](#description-required)stepsA static input, a step or a declared output has no description, or a blank one. The outputs a kind sets itself (answer, verdict, a decision-model step's questions) are never declared, so they carry none.yes
[env-name](#env-name)stepsA name in a step's env is not letters, digits and _, or starts with a digit.yes
[env-nul](#env-nul)stepsA value in a step's env holds a NUL character.yes
[env-reserved](#env-reserved)stepsA step's env sets a variable looprail uses itself.yes
[failover](#failover)stepsfailover is not one of the failovers.yes
[failover-agent](#failover-agent)stepsA step that is not an agent or agent-gate sets failover = "agent".yes
[idle-limit](#idle-limit)stepsAn agent or agent-gate step's idle_limit is not a duration such as 30m or 2h, or unlimited.yes
[kind](#kind)stepsA step's kind is not one of the kinds.yes
[kind-has-no](#kind-has-no)stepsA step sets a field its kind does not have, or outputs on a kind whose outputs are its own.yes
[kind-needs](#kind-needs)stepsA step leaves out a field its kind needs.yes
[levels-not-score](#levels-not-score)stepsA question that is not a score sets levels.yes
[mcp-command](#mcp-command)stepsAn mcp step's command is an empty list, or holds an empty entry.yes
[mcp-env](#mcp-env)stepsAn mcp step sets env with url: env goes to a server it starts with command.no
[mcp-headers](#mcp-headers)stepsAn mcp step sets headers with command: headers go to a server it reaches at url.no
[mcp-server](#mcp-server)stepsAn mcp step sets neither url nor command, or both.no
[probabilities-yes-no](#probabilities-yes-no)stepsA yes-no question sets probabilities.yes
[question-output-name](#question-output-name)stepsA question is named like an output another question sets, such as category_confidence beside category.no
[question-type](#question-type)stepsA question's type is not one of the question types.yes
[questions-empty](#questions-empty)stepsA decision-model step's questions names no questions.yes
[run-empty](#run-empty)stepsA shell or shell-gate step's run is an empty list.yes
[score-levels](#score-levels)stepsA score question has no levels, too few or too many.yes
[step-name](#step-name)stepsA step name is empty or holds ", { or }.yes
[agent-lifetime-on-step](#agent-lifetime-on-step)named agentsA step's or an override's agent sets lifetime, which belongs to the named agent.yes
[agent-model-with-name](#agent-model-with-name)named agentsA step's or an override's agent sets model with name: a named agent's model is in its llm.yes
[agent-name-missing](#agent-name-missing)named agentsagent.name names no named agent of the file or of a looprail that runs it.no
[agent-name-or-command](#agent-name-or-command)named agentsA step's or an override's agent sets name with provider or command, or none of them.yes
[agent-provider](#agent-provider)named agentsAn inline agent names a provider that is neither a built-in harness nor one of the file's [harnesses], and has no command.no
[agents-lifetime-required](#agents-lifetime-required)named agentsA named agent's lifetime is missing, empty, or not step, item or run.yes
[agents-llm-empty](#agents-llm-empty)named agentsA named agent has no llm, or an empty one.yes
[agents-name](#agents-name)named agentsA named agent's name is empty or holds ", { or }.yes
[agents-unused](#agents-unused)named agentsNo step of the file, or of a looprail it runs, names a named agent.no
[harnesses-command](#harnesses-command)named agentsAn extra harness has no command, an empty one, or an empty entry in it.yes
[harnesses-name](#harnesses-name)named agentsAn extra harness's name is empty or holds ", { or }.yes
[lifetime-cwd-env](#lifetime-cwd-env)named agentsTwo steps share the session of a named agent whose lifetime is item or run, neither needs the other, and their literal cwd or their env differ.no
[llm-auth-env](#llm-auth-env)named agentsAn llm row's auth_env is not a variable name: capital letters, digits and _, not starting with a digit.yes
[llm-config-value](#llm-config-value)named agentsA value of an llm row's config is not a string, a number or a boolean.yes
[llm-endpoint](#llm-endpoint)named agentsAn openai-compatible llm row has no endpoint, an endpoint is not an http:// or https:// URL, or a provider that takes no endpoint, such as an ACP harness, sets one.no
[llm-harness](#llm-harness)named agentsAn llm row sets neither provider nor command.yes
[llm-provider](#llm-provider)named agentsAn llm row's provider is not a built-in provider or an extra harness of the file, and the row has no command.no
[decision-model-name-missing](#decision-model-name-missing)decision modelsdecision-model.name names no decision model of the file or of a looprail that runs it.no
[decision-model-name-required](#decision-model-name-required)decision modelsA step's decision-model has no name, or an empty one.yes
[decision-model-only-name](#decision-model-only-name)decision modelsA step's decision-model sets anything but name.yes
[decision-models-agent-name](#decision-models-agent-name)decision modelsA decision model and a named agent share a name, among those of the file and of the looprails that run it.no
[decision-models-llm-empty](#decision-models-llm-empty)decision modelsA decision model has no llm, or an empty one.yes
[decision-models-llm-provider](#decision-models-llm-provider)decision modelsAn llm row of a decision model has no provider, or names one looprail does not have.yes
[decision-models-name](#decision-models-name)decision modelsA decision model's name is empty or holds ", { or }.yes
[decision-models-unused](#decision-models-unused)decision modelsNo step of the file, or of a looprail it runs, names a decision model.no
[step-provider](#step-provider)decision modelsA decision-model step sets provider, which belongs on an llm row of a decision model.yes
[ahead-max-loops](#ahead-max-loops)needs and loopsA gate sends its rejection ahead without max_loops.no
[max-loops-alone](#max-loops-alone)needs and loopsA step sets max_loops without on_fail.yes
[max-loops-low](#max-loops-low)needs and loopsmax_loops is below 1.yes
[max-retries-low](#max-retries-low)needs and loopsmax_retries is below 0.yes
[needs-cycle](#needs-cycle)needs and loopsThe needs form a cycle.no
[needs-self](#needs-self)needs and loopsA step lists itself in needs.no
[needs-twice](#needs-twice)needs and loopsA step lists a step twice in needs.no
[no-such-step](#no-such-step)needs and loopsneeds, on_fail or a reference names a step that does not exist.no
[on-fail-ahead](#on-fail-ahead)needs and loopson_fail names a step downstream of a step that is not a gate, or of a gate with for_each.no
[on-fail-unrelated](#on-fail-unrelated)needs and loopson_fail names a step neither upstream nor downstream of this one.no
[expr-ends-early](#expr-ends-early)templatesA {{ }} ends where a value should come, as after == or &&, or is empty.no
[expr-name](#expr-name)templatesA . in a reference is not followed by a name.no
[expr-string](#expr-string)templatesA quoted string or quoted name has no closing quote.no
[expr-unexpected](#expr-unexpected)templatesA {{ }} holds a character that cannot start or continue a reference or an expression.no
[template-expression](#template-expression)templatesA {{ }} outside when holds an expression, not one reference.no
[template-unclosed](#template-unclosed)templatesA {{ has no closing }}.no
[env-ref-form](#env-ref-form)referencesAn env reference is not env.<NAME>, with a variable's name.no
[env-ref-place](#env-ref-place)referencesAn env reference sits anywhere but the url, headers, body, command or arguments of an api or mcp step.no
[input-ref-form](#input-ref-form)referencesAn input reference is not inputs.<name>.no
[namespace](#namespace)referencesA reference starts with something other than inputs, steps, each or env.no
[no-such-input](#no-such-input)referencesA reference names an input the file does not declare.no
[no-such-output](#no-such-output)referencesA reference names an output the step does not have.no
[output-ref-form](#output-ref-form)referencesA reference to a step's outputs does not name exactly one output.no
[step-field](#step-field)referencesA reference names a step field other than outputs, status, loops or accepted.no
[step-field-parts](#step-field-parts)referencesA reference goes past a step's status, loops or accepted.no
[step-ref-form](#step-ref-form)referencesA step reference names only the step.no
[unreachable](#unreachable)referencesA reference names a step this one does not reach through needs.no
[expr-number](#expr-number)[when](#rules-for-when)A number in when does not parse.no
[expr-paren](#expr-paren)[when](#rules-for-when)A ( in when has no closing ).no
[when-compare-types](#when-compare-types)[when](#rules-for-when)== or != compares two values whose types are known and differ.no
[when-enum-value](#when-enum-value)[when](#rules-for-when)An enum is compared with a string that is not one of its values.no
[when-form](#when-form)[when](#rules-for-when)when is not exactly one {{ }}.no
[when-not-bool](#when-not-bool)[when](#rules-for-when)when is known not to be true or false.no
[when-operand](#when-operand)[when](#rules-for-when)!, && or `\\` has an operand known not to be true or false.no
[each-field-parts](#each-field-parts)[for_each](#rules-for-for_each)A reference goes past an item field that has no fields.no
[each-outside](#each-outside)[for_each](#rules-for-for_each)A step without for_each references each.no
[for-each-not-list](#for-each-not-list)[for_each](#rules-for-for_each)for_each references something that is not a list.no
[for-each-outputs](#for-each-outputs)[for_each](#rules-for-for_each)A reference names one output of a for_each step, whose outputs are a list.no
[for-each-single](#for-each-single)[for_each](#rules-for-for_each)for_each is not one reference.no
[no-such-item-field](#no-such-item-field)[for_each](#rules-for-for_each)A reference names an item field the items are known not to have.no
[shell-backslash](#shell-backslash)shell quotingA reference in a shell command comes right after a \.no
[shell-comment](#shell-comment)shell quotingA reference in a shell command comes after a # comment.no
[shell-continued](#shell-continued)shell quotingA reference in a shell command comes after a backslash-newline.no
[shell-dollar](#shell-dollar)shell quotingA reference in a shell command comes right after a $.no
[shell-heredoc](#shell-heredoc)shell quotingA reference in a shell command sits in a here-document.no
[shell-in-quotes](#shell-in-quotes)shell quotingA reference in a shell command sits inside the command's own quotes.no
[shell-nested](#shell-nested)shell quotingA reference in a shell command comes after $(, a backtick, ${, $((, ((, $[, $' or $".no
[agents-redefine](#agents-redefine)looprail stepsA looprail a looprail step runs defines a named agent of the file, or of a looprail that runs it, with a different llm or lifetime.no
[decision-models-redefine](#decision-models-redefine)looprail stepsA looprail a looprail step runs defines a decision model of the file, or of a looprail that runs it, with different llm rows.no
[looprail-invalid](#looprail-invalid)looprail stepsThe looprail a looprail step names does not load.no
[looprail-nested](#looprail-nested)looprail stepsA looprail step of the looprail a looprail step names fails.no
[looprail-override-no-agent](#looprail-override-no-agent)looprail stepsA looprail step has overrides, but its looprail has no agent or agent-gate step.no
[looprail-path](#looprail-path)looprail stepsA looprail step's looprail path cannot be made absolute.not known: no example
[looprail-self](#looprail-self)looprail stepsA looprail step runs the file it is in, directly or through other looprails.no
[override-agent-required](#override-agent-required)looprail stepsAn override has no agent.yes
[override-match-required](#override-match-required)looprail stepsAn override has no match, or an empty one.yes
[override-match-value](#override-match-value)looprail stepsAn override's match holds a value that is not a string, a number or a boolean.yes
[override-reusable-inline](#override-reusable-inline)looprail stepsAn override puts an inline command in place of a named agent whose lifetime is item or run.no
[override-step](#override-step)looprail stepsAn override sets anything but match and agent.yes
[limit-low](#limit-low)limitsA limit's max_parallel is below 1.yes
[limit-required](#limit-required)limitsA limit has no max_parallel.yes
[provider](#provider)limitsA decision-model limit names a provider looprail does not have.yes
[brief-read](#brief-read)briefsA brief cannot be read.no

The base file

Most examples on the rule pages add to this file, which loads:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

What the schema can't check

  • It checks each field on its own: its type, its allowed values, what each kind and type may set, and that a required string is not empty.
  • It cannot compare fields, read other files or follow references. So a file it accepts can still fail to load.
  • The loader decides. looprail validate, looprail doctor or looprail run loads the file and every file it runs, and reports every error.
  • Which rules the schema lets through is in the last column above.

Rules for the file

Reading and decoding the file: TOML and JSON, the top level, unknown fields and whole numbers. Every rule is in the index of load rules.

config-unknown-key: [config] sets a key the table does not have. Adding this to the end of the base file fails with config.enable_flakes: "enable_flakes" is not a config key; use enable_nix:

[config]
enable_flakes = true

file-read: The looprail file cannot be read, as when it does not exist. Loading missing.toml, which does not exist, fails with open missing.toml: <the system's error>.

json-encode: A JSON file cannot be turned into TOML. No example: every JSON value looprail accepts has a TOML form.

json-null: A JSON file holds null. This file fails with metadata.description: null is not allowed:

{"metadata": {"spec_version": "0.1.0", "name": "x", "description": null}, "step": {"a": {"kind": "shell", "run": ["true"]}}}

json-number: A JSON number is too large to hold. This file fails with step.a.accept_exit[0]: 1e999 is too large to hold:

{"metadata": {"spec_version": "0.1.0", "name": "x"}, "step": {"a": {"kind": "shell", "description": "Runs a.", "run": ["true"], "accept_exit": [1e999]}}}

json-object: A JSON file is not one JSON object. This file fails with the file is not a JSON object: it is an array:

["x"]

json-shape: A JSON file has text after its object, or an inputs that is not an object. This file fails with <the JSON decoder's error>:

{"metadata": {"spec_version": "0.1.0", "name": "x"}, "step": {"a": {"kind": "shell", "description": "Runs a.", "run": ["true"]}}} {}

json-step: A JSON file's step is not an object of step name to step. This file fails with step: must be an object of step name to step:

{"metadata": {"spec_version": "0.1.0", "name": "x"}, "step": [{"kind": "shell", "run": ["true"]}]}

json-step-entry: A step in a JSON file is not an object, or a list holding one object. This file fails with step.a: must be an object, or a list holding one object:

{"metadata": {"spec_version": "0.1.0", "name": "x"}, "step": {"a": "shell"}}

metadata-required: The file has no [metadata] table. This file fails with metadata: is required:

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

metadata-unknown-key: [metadata] sets a key the table does not have. This file fails with metadata.version: "version" is not a metadata key; use spec_version, name or description:

[metadata]
spec_version = "0.1.0"
name = "x"
version = "1"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

name-required: [metadata] has no name, or a blank one. This file fails with metadata.name: is required:

[metadata]
spec_version = "0.1.0"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

no-steps: The file has no step. This file fails with step: the file has no steps:

[metadata]
spec_version = "0.1.0"
name = "x"

spec-major: spec_version has a major other than the one this looprail reads. This file fails with metadata.spec_version: this file is spec 1.0.0; this looprail reads 0.x, so upgrade looprail:

[metadata]
name = "x"
spec_version = "1.0.0"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

spec-since: A file sets a field, or uses a kind, that entered the format in a spec version higher than its spec_version. No example: every field and kind entered the format in 0.1.0, so no file this looprail loads can break it.

spec-too-new: spec_version has the major this looprail reads, but is higher than the version it supports. This file fails with metadata.spec_version: this file needs spec 0.2.0; this looprail supports up to 0.1.0, so upgrade looprail:

[metadata]
name = "x"
spec_version = "0.2.0"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

spec-version-format: spec_version is not a plain MAJOR.MINOR.PATCH, such as v0.1, 0.1 or 0.1.0-rc1. This file fails with metadata.spec_version: "v0.1" is not MAJOR.MINOR.PATCH, such as "0.1.0":

[metadata]
name = "x"
spec_version = "v0.1"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

spec-version-required: [metadata] has no spec_version, or a blank one. This file fails with metadata.spec_version: is required; add spec_version = "0.1.0":

[metadata]
name = "x"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

step-twice: Two [[step.<name>]] tables share a name. Adding this to the end of the base file fails with step.a: two steps share the name "a":

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

toml-syntax: The file is not valid TOML. This file fails with line 9: expected a comma (',') or array terminator (']'), but got end of file:

[metadata]
spec_version = "0.1.0"
name = "x"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"

toml-type: The TOML decoder rejects the file for a reason other than its syntax, most often a value of the wrong type for its field, such as a string where a list goes. This file fails with step.a.run: line 9: is a string, but must be a list:

[metadata]
spec_version = "0.1.0"
name = "x"

[[step.a]]
kind = "shell"
description = "Runs a."
run = "true"

Adding this to the end of the base file fails with config.enable_nix: line 12: is a string, but must be true or false:

[config]
enable_nix = "yes"

unknown-field: The file sets a field the format does not have. The example [unknown-field](#example-unknown-field) fails with step.hello.nedes: unknown field.

whole-number: A field that takes a whole number holds a fraction, such as max_loops = 2.5, an infinity or NaN, or a value that is not a number. Adding this to the end of the base file fails with step.a.max_loops: line 11: 2.5 is not a whole number:

on_fail = "a"
max_loops = 2.5

whole-number-range: A field that takes a whole number holds a float of 2^53 or more, such as max_loops = 1e300, which the loader cannot hold exactly. Adding this to the end of the base file fails with step.a.max_loops: line 11: 1e+300 is not a whole number:

on_fail = "a"
max_loops = 1e300

Rules for inputs

Derived inputs, and the defaults of static ones. Every rule is in the index of load rules.

default: An input's default is of the wrong type, or outside its bounds or its values. The example [bad-default](#example-bad-default) fails with inputs.static.slug.default: "too long" is 8 characters, above max_length 4.

derived-ref: A derived input references anything but a static input. The example [derived-from-step](#example-derived-from-step) fails with inputs.derived.when: {{ steps.a.status }}: a derived input may only reference a static input.

derived-shares-name: A derived input is named like a static input. Adding this to the end of the base file fails with inputs.derived.title: a static input and a derived input share the name "title":

[inputs.static]
title = { type = "string", description = "The title." }
[inputs.derived]
title = "{{ inputs.title }}!"

Rules for types

The declarations of inputs, outputs and item fields: their types, bounds and defaults. Every rule is in the index of load rules.

bound-order: min exceeds max. Adding this to the end of the base file fails with inputs.static.n.min: 5 exceeds max 2:

[inputs.static]
n = { type = "int", description = "The n.", min = 5, max = 2 }

bound-type: A bound is set on a type it does not apply to: min_length or max_length on anything but a string, min or max on anything but an int or a float. Adding this to the end of the base file fails with inputs.static.n.min_length: an int has no min_length:

[inputs.static]
n = { type = "int", description = "The n.", min_length = 1 }

enum-values: An enum has no values, or an empty list. Adding this to the end of the base file fails with inputs.static.mode.values: an enum needs values:

[inputs.static]
mode = { type = "enum", description = "The mode." }

int-bound: An int's min or max is not a whole number. Adding this to the end of the base file fails with inputs.static.n.min: an int bound must be a whole number, not 1.5:

[inputs.static]
n = { type = "int", description = "The n.", min = 1.5 }

item-default: An item field sets default. Adding this to the end of the base file fails with step.a.outputs.files.items.path.default: an item field has no default:

[step.a.outputs]
files = { type = "list", description = "The files.", items = { path = { type = "string", default = "." } } }

items-empty: A list's items names no fields. Adding this to the end of the base file fails with step.a.outputs.files.items: names no fields:

[step.a.outputs]
files = { type = "list", description = "The files.", items = {} }

items-not-list: A type that is not a list sets items. Adding this to the end of the base file fails with step.a.outputs.path.items: only a list has items:

[step.a.outputs]
path = { type = "string", description = "The path.", items = { x = { type = "string" } } }

kind-output-declared: An api or mcp step declares an output its kind sets itself: status_code or body on an api step, text on an mcp step. This file fails with step.a.outputs.body: body is an api step's own output:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "api"
description = "Runs a."
url = "https://example.com"
[step.a.outputs]
body = { type = "string", description = "The body." }

length-order: min_length exceeds max_length. Adding this to the end of the base file fails with inputs.static.title.min_length: 5 exceeds max_length 2:

[inputs.static]
title = { type = "string", description = "The title.", min_length = 5, max_length = 2 }

min-length-negative: min_length is negative. Adding this to the end of the base file fails with inputs.static.title.min_length: must not be negative:

[inputs.static]
title = { type = "string", description = "The title.", min_length = -1 }

output-default: An output sets default. The example [output-default](#example-output-default) fails with step.a.outputs.n.default: an output has no default.

type: A declaration's type is not one of the types it may have. The example [input-list](#example-input-list) fails with inputs.static.issues.type: "list" is not a type; use one of string, enum, bool, int, float.

values-not-enum: A type that is not an enum sets values. Adding this to the end of the base file fails with inputs.static.mode.values: only an enum has values:

[inputs.static]
mode = { type = "string", description = "The mode.", values = ["fast"] }

verdict-declared: An agent-gate declares an output named verdict, which is its own. The example [verdict-declared](#example-verdict-declared) fails with step.review.outputs.verdict: verdict is the gate's own output.

Rules for steps

A step's name, kind and description, and the fields each kind needs, may set and may not. Every rule is in the index of load rules.

accept-exit-empty: A shell-gate's accept_exit is an empty list. The example [empty-accept-exit](#example-empty-accept-exit) fails with step.a.accept_exit: is empty; a gate that accepts no exit code can never pass.

api-method: An api step's method is not one of the methods. This file fails with step.a.method: "get" is not a method; use one of GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "api"
description = "Runs a."
url = "https://example.com"
method = "get"

choice-criteria: A choice question has no criteria. This file fails with step.a.questions.next.criteria: a choice needs criteria:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "decision-model"
description = "Runs a."
decision-model = { name = "triage" }
state = "s"
[step.a.questions.next]
type = "choice"
[[decision-models.triage.llm]]
provider = "jev"

choices: A human step's choices is an empty list, or holds a blank or repeated choice. This file fails with step.a.choices: is empty:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "human"
description = "Asks a."
ask = "Ship it?"
choices = []

command-empty-arg: An entry of an agent's or an llm row's command is empty. This file, with the files below, fails with step.a.agent.command[1]: is empty:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "agent"
description = "Runs a."
agent = { command = ["claude-agent-acp", ""] }
brief = "brief.md"

brief.md:

Do it.

command-required: An inline agent's or an llm row's command is an empty list. This file, with the files below, fails with step.a.agent.command: is empty; name the harness and its arguments:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "agent"
description = "Runs a."
agent = { command = [] }
brief = "brief.md"

brief.md:

Do it.

criteria-not-choice: A question that is not a choice sets criteria. This file fails with step.a.questions.ok.criteria: only a choice has criteria:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "decision-model"
description = "Runs a."
decision-model = { name = "triage" }
state = "s"
[step.a.questions.ok]
type = "yes-no"
criteria = { yes = "It works." }
[[decision-models.triage.llm]]
provider = "jev"

description-required: A static input, a step or a declared output has no description, or a blank one. The outputs a kind sets itself (answer, verdict, a decision-model step's questions) are never declared, so they carry none. The example [description-required](#example-description-required) fails with step.count.outputs.n.description: is required.

env-name: A name in a step's env is not letters, digits and _, or starts with a digit. This file, with the files below, fails with step.a.env.1A: a variable's name is letters, digits and _, not starting with a digit:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "agent"
description = "Runs a."
agent = { command = ["claude-agent-acp"] }
brief = "brief.md"
env = { "1A" = "x" }

brief.md:

Do it.

env-nul: A value in a step's env holds a NUL character. This file, with the files below, fails with step.a.env.A: holds a NUL character, which no variable can hold:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "agent"
description = "Runs a."
agent = { command = ["claude-agent-acp"] }
brief = "brief.md"
env = { A = "a\u0000b" }

brief.md:

Do it.

env-reserved: A step's env sets a variable looprail uses itself. The example [env-reserved](#example-env-reserved) fails with step.code.env.PATH: PATH is reserved; a step's env may not set PATH, PWD, or a variable starting with LOOPRAIL_, which looprail uses itself.

failover: failover is not one of the failovers. Adding this to the end of the base file fails with step.a.failover: "nobody" is not a failover; use human or agent:

failover = "nobody"

failover-agent: A step that is not an agent or agent-gate sets failover = "agent". The example [failover-agent](#example-failover-agent) fails with step.a.failover: only an agent or agent-gate step can fail over to an agent.

idle-limit: An agent or agent-gate step's idle_limit is not a duration such as 30m or 2h, or unlimited. The example [idle-limit](#example-idle-limit) fails with step.code.idle_limit: "90" is not a duration such as 30m or 2h, or unlimited.

kind: A step's kind is not one of the kinds. This file fails with step.a.kind: "bash" is not a kind; use one of agent, shell, agent-gate, shell-gate, decision-model, human, api, mcp, looprail:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "bash"
description = "Runs a."
run = ["true"]

kind-has-no: A step sets a field its kind does not have, or outputs on a kind whose outputs are its own. The example [wrong-kind-field](#example-wrong-kind-field) fails with step.a.ask: a shell step has no ask. The example [env-shell](#example-env-shell) fails with step.a.env: a shell step has no env. The example [human-outputs](#example-human-outputs) fails with step.ask.outputs: a human step has no outputs. The example [looprail-has-no](#example-looprail-has-no) fails with step.change.when: a looprail step has no when.

kind-needs: A step leaves out a field its kind needs. The example [missing-kind-field](#example-missing-kind-field) fails with step.a.accept_exit: a shell-gate step needs accept_exit. Adding this to the end of the base file fails with step.c.looprail: a looprail step needs looprail:

[[step.c]]
kind = "looprail"
description = "Runs the child."

levels-not-score: A question that is not a score sets levels. This file fails with step.d.questions.ok.levels: only a score has levels:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[step.d.questions.ok]
type = "yes-no"
levels = ["no", "yes"]
[[decision-models.triage.llm]]
provider = "jev"

mcp-command: An mcp step's command is an empty list, or holds an empty entry. This file fails with step.a.command[1]: is empty:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "mcp"
description = "Runs a."
command = ["slack-mcp", ""]
tool = "post"

mcp-env: An mcp step sets env with url: env goes to a server it starts with command. This file fails with step.a.env: env goes with command; a server reached at url gets headers instead:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "mcp"
description = "Runs a."
url = "http://127.0.0.1:1985/mcp"
env = { A = "x" }
tool = "post"

mcp-headers: An mcp step sets headers with command: headers go to a server it reaches at url. This file fails with step.a.headers: headers go with url; a server started with command gets env instead:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "mcp"
description = "Runs a."
command = ["slack-mcp"]
headers = { Authorization = "x" }
tool = "post"

mcp-server: An mcp step sets neither url nor command, or both. The example [mcp-server](#example-mcp-server) fails with step.post: an mcp step sets both url and command; set one.

probabilities-yes-no: A yes-no question sets probabilities. This file fails with step.d.questions.ok.probabilities: a yes-no question has no probabilities; only a choice or a score does:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[step.d.questions.ok]
type = "yes-no"
probabilities = true
[[decision-models.triage.llm]]
provider = "jev"

question-output-name: A question is named like an output another question sets, such as category_confidence beside category. This file fails with step.d.questions.category_confidence: "category_confidence" is an output question "category" sets:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[[decision-models.triage.llm]]
provider = "jev"
[step.d.questions.category]
type = "choice"
criteria = { bug = "A bug." }
[step.d.questions.category_confidence]
type = "yes-no"

question-type: A question's type is not one of the question types. This file fails with step.a.questions.q.type: "rank" is not a question type; use choice, yes-no, score:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "decision-model"
description = "Runs a."
decision-model = { name = "triage" }
state = "s"
[step.a.questions.q]
type = "rank"
[[decision-models.triage.llm]]
provider = "jev"

questions-empty: A decision-model step's questions names no questions. This file fails with step.a.questions: names no questions:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "decision-model"
description = "Runs a."
decision-model = { name = "triage" }
state = "s"
questions = {}
[[decision-models.triage.llm]]
provider = "jev"

run-empty: A shell or shell-gate step's run is an empty list. The example [quoted-name](#example-quoted-name) fails with step."needs work".run: is empty; a shell step needs at least one command.

score-levels: A score question has no levels, too few or too many. This file fails with step.d.questions.risk.levels: a score needs 2 to 10 levels, lowest first, and has 0:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[[decision-models.triage.llm]]
provider = "jev"
[step.d.questions.risk]
type = "score"

This file fails with step.d.questions.risk.levels: a score needs 2 to 10 levels, lowest first, and has 1:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[[decision-models.triage.llm]]
provider = "jev"
[step.d.questions.risk]
type = "score"
levels = ["low"]

step-name: A step name is empty or holds ", { or }. This file fails with step."a{": a step name must not be empty or hold ", { or }:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step."a{"]]
kind = "shell"
description = "Runs a."
run = ["true"]

Rules for named agents

Named agents, their llm rows, harnesses, and the agent a step names. Every rule is in the index of load rules.

agent-lifetime-on-step: A step's or an override's agent sets lifetime, which belongs to the named agent. This file, with the files below, fails with step.code.agent.lifetime: lifetime belongs on [agents.<name>], not on a step's agent:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder", lifetime = "run" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "claude"
model = "opus"

brief.md:

Do it.

agent-model-with-name: A step's or an override's agent sets model with name: a named agent's model is in its llm. This file, with the files below, fails with step.code.agent.model: a named agent's model is in its llm; --set @<agent> model=<model> changes it for a run:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder", model = "sonnet" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "claude"
model = "opus"

brief.md:

Do it.

agent-name-missing: agent.name names no named agent of the file or of a looprail that runs it. This file, with the files below, fails with step.code.agent.name: no named agent is named "coder":

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }

brief.md:

Do it.

agent-name-or-command: A step's or an override's agent sets name with provider or command, or none of them. This file, with the files below, fails with step.code.agent: set name, or provider or command, not both:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder", command = ["claude-agent-acp"] }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "claude"
model = "opus"

brief.md:

Do it.

agent-provider: An inline agent names a provider that is neither a built-in harness nor one of the file's [harnesses], and has no command. This file, with the files below, fails with step.a.agent.provider: provider "nosuch" has no harness: use one of claude, codex, grok, goose, pi, or add [harnesses.nosuch] with a command:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "agent"
description = "Runs a."
agent = { provider = "nosuch" }
brief = "brief.md"

brief.md:

Do it.

agents-lifetime-required: A named agent's lifetime is missing, empty, or not step, item or run. This file, with the files below, fails with agents.coder.lifetime: "forever" is not a lifetime; use step, item or run:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "forever"
[[agents.coder.llm]]
provider = "claude"

brief.md:

Do it.

agents-llm-empty: A named agent has no llm, or an empty one. This file, with the files below, fails with agents.coder.llm: is required; list at least one llm:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "step"

brief.md:

Do it.

agents-name: A named agent's name is empty or holds ", { or }. This file, with the files below, fails with agents."a{": a named agent's name must not be empty or hold ", { or }:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "a{" }
[agents."a{"]
lifetime = "step"
[[agents."a{".llm]]
provider = "claude"

brief.md:

Do it.

agents-unused: No step of the file, or of a looprail it runs, names a named agent. Adding this to the end of the base file fails with agents.coder: no step names the agent "coder":

[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "claude"
model = "opus"

harnesses-command: An extra harness has no command, an empty one, or an empty entry in it. Adding this to the end of the base file fails with harnesses.amp.command: is required; name the harness and its arguments:

[harnesses.amp]
command = []

harnesses-name: An extra harness's name is empty or holds ", { or }. Adding this to the end of the base file fails with harnesses."a{": a harness's name must not be empty or hold ", { or }:

[harnesses."a{"]
command = ["amp-acp"]

lifetime-cwd-env: Two steps share the session of a named agent whose lifetime is item or run, neither needs the other, and their literal cwd or their env differ. This file, with the files below, fails with step.docs.cwd: steps "code" and "docs" share the session of agent "coder", but their cwd differ; a session runs in one cwd and env:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[[step.docs]]
kind = "agent"
description = "Writes the docs."
brief = "brief.md"
agent = { name = "coder" }
cwd = "docs"
[agents.coder]
lifetime = "item"
[[agents.coder.llm]]
provider = "claude"

brief.md:

Do it.

llm-auth-env: An llm row's auth_env is not a variable name: capital letters, digits and _, not starting with a digit. This file, with the files below, fails with agents.coder.llm[0].auth_env: "sk-or-123" is not a variable name; auth_env names the variable that holds the key, never the key:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "openrouter"
auth_env = "sk-or-123"

brief.md:

Do it.

llm-config-value: A value of an llm row's config is not a string, a number or a boolean. This file, with the files below, fails with agents.coder.llm[0].config.effort: must be a string, a number or true or false:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "codex"
config = { effort = { level = "high" } }

brief.md:

Do it.

llm-endpoint: An openai-compatible llm row has no endpoint, an endpoint is not an http:// or https:// URL, or a provider that takes no endpoint, such as an ACP harness, sets one. This file, with the files below, fails with agents.coder.llm[0].endpoint: openai-compatible needs an endpoint, the base URL of the server:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "openai-compatible"
model = "llama-3.3-70b-versatile"

brief.md:

Do it.

This file, with the files below, fails with agents.coder.llm[0].endpoint: an ACP harness takes no endpoint; only openrouter, openai, openai-compatible, ollama, commandcode do:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "claude"
endpoint = "https://api.anthropic.com"

brief.md:

Do it.

This file, with the files below, fails with agents.coder.llm[0].endpoint: "127.0.0.1:11434" is not an http:// or https:// URL:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "ollama"
endpoint = "127.0.0.1:11434"

brief.md:

Do it.

llm-harness: An llm row sets neither provider nor command. This file, with the files below, fails with agents.coder.llm[0]: an llm needs provider, command or both:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
model = "opus"

brief.md:

Do it.

llm-provider: An llm row's provider is not a built-in provider or an extra harness of the file, and the row has no command. This file, with the files below, fails with agents.coder.llm[0].provider: "acme" is not a provider; use one of claude, codex, grok, goose, pi, openrouter, openai, openai-compatible, ollama, goinfer, commandcode, a [harnesses.<name>] of the file, or set command:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[agents.coder]
lifetime = "step"
[[agents.coder.llm]]
provider = "acme"

brief.md:

Do it.

Rules for decision models

Decision models, their llm rows, and the decision model a step names. Every rule is in the index of load rules.

decision-model-name-missing: decision-model.name names no decision model of the file or of a looprail that runs it. This file fails with step.d.decision-model.name: no decision model is named "triage":

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[step.d.questions.ok]
type = "yes-no"

decision-model-name-required: A step's decision-model has no name, or an empty one. This file fails with step.d.decision-model.name: is required; name a [decision-models.<name>]:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = {}
[step.d.questions.ok]
type = "yes-no"

decision-model-only-name: A step's decision-model sets anything but name. This file fails with step.d.decision-model.provider: provider belongs on [[decision-models.<name>.llm]], not on a step's decision-model:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage", provider = "jev" }
[step.d.questions.ok]
type = "yes-no"
[[decision-models.triage.llm]]
provider = "jev"

This file fails with step.d.decision-model.model: model belongs on [[decision-models.<name>.llm]], not on a step's decision-model:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage", model = "jev-1.14.0" }
[step.d.questions.ok]
type = "yes-no"
[[decision-models.triage.llm]]
provider = "jev"

This file fails with step.d.decision-model.lifetime: a step's decision-model has only name:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage", lifetime = "run" }
[step.d.questions.ok]
type = "yes-no"
[[decision-models.triage.llm]]
provider = "jev"

decision-models-agent-name: A decision model and a named agent share a name, among those of the file and of the looprails that run it. This file, with the files below, fails with decision-models.triage: a decision model and an agent share the name "triage":

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[step.d.questions.ok]
type = "yes-no"
[[decision-models.triage.llm]]
provider = "jev"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "triage" }
[agents.triage]
lifetime = "step"
[[agents.triage.llm]]
provider = "claude"

brief.md:

Do it.

decision-models-llm-empty: A decision model has no llm, or an empty one. This file fails with decision-models.triage.llm: is required; list at least one llm:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[step.d.questions.ok]
type = "yes-no"
[decision-models.triage]

decision-models-llm-provider: An llm row of a decision model has no provider, or names one looprail does not have. This file fails with decision-models.triage.llm[0].provider: is required; use one of jev:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[step.d.questions.ok]
type = "yes-no"
[[decision-models.triage.llm]]
model = "jev-1.14.0"

This file fails with decision-models.triage.llm[0].provider: "gpt" is not a provider; use one of jev:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
[step.d.questions.ok]
type = "yes-no"
[[decision-models.triage.llm]]
provider = "gpt"

decision-models-name: A decision model's name is empty or holds ", { or }. This file fails with decision-models."a{": a decision model's name must not be empty or hold ", { or }:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "a{" }
[step.d.questions.ok]
type = "yes-no"
[[decision-models."a{".llm]]
provider = "jev"

decision-models-unused: No step of the file, or of a looprail it runs, names a decision model. Adding this to the end of the base file fails with decision-models.triage: no step names the decision model "triage":

[[decision-models.triage.llm]]
provider = "jev"

step-provider: A decision-model step sets provider, which belongs on an llm row of a decision model. This file fails with step.d.provider: a step has no provider; list it under [decision-models.<name>] and set decision-model = { name = "..." }:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }
provider = "jev"
[step.d.questions.ok]
type = "yes-no"
[[decision-models.triage.llm]]
provider = "jev"

Rules for needs and loops

needs, on_fail, max_loops and max_retries. Every rule is in the index of load rules.

ahead-max-loops: A gate sends its rejection ahead without max_loops. The example [ahead-no-max-loops](#example-ahead-no-max-loops) fails with step.check.max_loops: must be set, because on_fail sends this gate's rejection ahead to "fix".

max-loops-alone: A step sets max_loops without on_fail. The example [max-loops-alone](#example-max-loops-alone) fails with step.build.max_loops: has no on_fail to cap.

max-loops-low: max_loops is below 1. Adding this to the end of the base file fails with step.a.max_loops: 0 is below 1:

on_fail = "a"
max_loops = 0

max-retries-low: max_retries is below 0. Adding this to the end of the base file fails with step.a.max_retries: -1 is below 0:

max_retries = -1

needs-cycle: The needs form a cycle. Adding this to the end of the base file fails with step.a.needs: the needs form a cycle: a -> b -> a:

needs = ["b"]
[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["true"]

needs-self: A step lists itself in needs. Adding this to the end of the base file fails with step.a.needs[0]: a step cannot need itself:

needs = ["a"]

needs-twice: A step lists a step twice in needs. Adding this to the end of the base file fails with step.b.needs[1]: "a" is listed twice:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a", "a"]
run = ["true"]

no-such-step: needs, on_fail or a reference names a step that does not exist. Adding this to the end of the base file fails with step.a.needs[0]: no step is named "build":

needs = ["build"]

on-fail-ahead: on_fail names a step downstream of a step that is not a gate, or of a gate with for_each. The example [ahead-not-gate](#example-ahead-not-gate) fails with step.build.on_fail: "fix" is downstream of this step; only a gate without for_each may send its rejection ahead.

on-fail-unrelated: on_fail names a step neither upstream nor downstream of this one. Adding this to the end of the base file fails with step.check.on_fail: "a" is neither upstream nor downstream of this step through needs:

[[step.check]]
kind = "shell-gate"
description = "Runs check."
run = ["true"]
accept_exit = [0]
on_fail = "a"

Rules for templates

The form of a {{ }} template and the expression it holds. Every rule is in the index of load rules.

expr-ends-early: A {{ }} ends where a value should come, as after == or &&, or is empty. Adding this to the end of the base file fails with step.b.when: expression ends early:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
when = "{{ steps.a.loops == }}"
run = ["true"]

expr-name: A . in a reference is not followed by a name. Adding this to the end of the base file fails with step.b.run[0]: {{ steps.a. }}: missing name after . at position 10:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["echo {{ steps.a. }}"]

expr-string: A quoted string or quoted name has no closing quote. Adding this to the end of the base file fails with step.b.when: unterminated string at position 20:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
when = "{{ steps.a.status == 'passed }}"
run = ["true"]

expr-unexpected: A {{ }} holds a character that cannot start or continue a reference or an expression. Adding this to the end of the base file fails with step.b.when: unexpected "> 1 " at position 16:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
when = "{{ steps.a.loops > 1 }}"
run = ["true"]

template-expression: A {{ }} outside when holds an expression, not one reference. Adding this to the end of the base file fails with step.b.run[0]: {{ steps.a.loops == 1 }} must hold one reference, not an expression:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["echo {{ steps.a.loops == 1 }}"]

template-unclosed: A {{ has no closing }}. This file fails with step.a.run[0]: {{ at position 6 has no closing }}:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo {{ inputs.title"]

Rules for references

What a reference may name, and where it may appear. Every rule is in the index of load rules.

env-ref-form: An env reference is not env.<NAME>, with a variable's name. This file fails with step.a.url: {{ env.TOKEN.x }}: write a variable as env.<NAME>: letters, digits and _, not starting with a digit:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "api"
description = "Runs a."
url = "https://example.com/{{ env.TOKEN.x }}"

env-ref-place: An env reference sits anywhere but the url, headers, body, command or arguments of an api or mcp step. The example [env-ref-place](#example-env-ref-place) fails with step.show.run[0]: {{ env.NOTES_TOKEN }}: env may only be referenced in the url, headers, body, command or arguments of an api or mcp step, where its value is hidden from what the step writes.

input-ref-form: An input reference is not inputs.<name>. This file fails with step.a.run[0]: {{ inputs }}: write an input as inputs.<name>:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo {{ inputs }}"]

namespace: A reference starts with something other than inputs, steps, each or env. This file fails with step.a.run[0]: {{ vars.HOME }}: "vars" is not a namespace; use inputs, steps, each or env:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo {{ vars.HOME }}"]

no-such-input: A reference names an input the file does not declare. This file fails with step.a.run[0]: {{ inputs.title }}: no input is named "title":

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo {{ inputs.title }}"]

no-such-output: A reference names an output the step does not have. The example [no-such-output](#example-no-such-output) fails with step.b.run[0]: {{ steps.a.outputs.name }}: step "a" has no output "name" (it has answer).

output-ref-form: A reference to a step's outputs does not name exactly one output. Adding this to the end of the base file fails with step.b.run[0]: {{ steps.a.outputs }}: name one output: steps.a.outputs.<output>:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["echo {{ steps.a.outputs }}"]

step-field: A reference names a step field other than outputs, status, loops or accepted. Adding this to the end of the base file fails with step.b.run[0]: {{ steps.a.exit }}: "exit" is not a step field; use outputs, status, loops or accepted:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["echo {{ steps.a.exit }}"]

step-field-parts: A reference goes past a step's status, loops or accepted. Adding this to the end of the base file fails with step.b.run[0]: {{ steps.a.status.text }}: status has no fields:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["echo {{ steps.a.status.text }}"]

step-ref-form: A step reference names only the step. Adding this to the end of the base file fails with step.b.run[0]: {{ steps.a }}: write a step reference as steps.<name>.outputs.<output>, or .status, .loops or .accepted:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["echo {{ steps.a }}"]

unreachable: A reference names a step this one does not reach through needs. The example [unreachable](#example-unreachable) fails with step.b.run[0]: {{ steps.a.outputs.n }}: step "a" is not reachable through needs, so it may not have run.

Rules for when

The expression of when and the types it compares. Every rule is in the index of load rules.

expr-number: A number in when does not parse. Adding this to the end of the base file fails with step.b.when: bad number "1.2.3":

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
when = "{{ steps.a.loops == 1.2.3 }}"
run = ["true"]

expr-paren: A ( in when has no closing ). Adding this to the end of the base file fails with step.b.when: missing ) at position 22:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
when = "{{ (steps.a.loops == 1 }}"
run = ["true"]

when-compare-types: == or != compares two values whose types are known and differ. The example [when-types](#example-when-types) fails with step.report.when: == compares a number with a string.

when-enum-value: An enum is compared with a string that is not one of its values. The example [when-enum](#example-when-enum) fails with step.report.when: "quick" is not one of the values of inputs.mode (fast, full).

when-form: when is not exactly one {{ }}. Adding this to the end of the base file fails with step.b.when: must be one {{ }} expression, such as {{ steps.review.accepted == false }}:

[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
when = "steps.a.accepted"
run = ["true"]

when-not-bool: when is known not to be true or false. Adding this to the end of the base file fails with step.a.when: is not a true or false expression:

when = "{{ inputs.title }}"
[inputs.static]
title = { type = "string", description = "The title." }

when-operand: !, && or || has an operand known not to be true or false. Adding this to the end of the base file fails with step.a.when: ! needs true or false, not a string:

when = "{{ !inputs.title }}"
[inputs.static]
title = { type = "string", description = "The title." }

Rules for for_each

for_each, each and the fields of an item. Every rule is in the index of load rules.

each-field-parts: A reference goes past an item field that has no fields. This file fails with step.lint.run[0]: {{ each.path.dir }}: each.path is a string, which has no fields:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.list]]
kind = "shell"
description = "Runs list."
run = ["true"]
[step.list.outputs]
files = { type = "list", description = "The files.", items = { path = { type = "string" } } }
[[step.lint]]
kind = "shell"
description = "Runs lint."
needs = ["list"]
for_each = "{{ steps.list.outputs.files }}"
run = ["gofmt -l {{ each.path.dir }}"]

each-outside: A step without for_each references each. This file fails with step.a.run[0]: {{ each }}: each is only valid in a step with for_each:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo {{ each }}"]

for-each-not-list: for_each references something that is not a list. Adding this to the end of the base file fails with step.a.for_each: {{ inputs.title }} is not a list:

for_each = "{{ inputs.title }}"
[inputs.static]
title = { type = "string", description = "The title." }

for-each-outputs: A reference names one output of a for_each step, whose outputs are a list. This file fails with step.b.run[0]: {{ steps.a.outputs.n }}: step "a" has for_each, so its outputs are a list of entries; iterate them with for_each:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.list]]
kind = "shell"
description = "Runs list."
run = ["true"]
[step.list.outputs]
files = { type = "list", description = "The files." }
[[step.a]]
kind = "shell"
description = "Runs a."
needs = ["list"]
for_each = "{{ steps.list.outputs.files }}"
run = ["true"]
[step.a.outputs]
n = { type = "int", description = "The n." }
[[step.b]]
kind = "shell"
description = "Runs b."
needs = ["a"]
run = ["echo {{ steps.a.outputs.n }}"]

for-each-single: for_each is not one reference. Adding this to the end of the base file fails with step.a.for_each: must be one reference to a list, such as {{ steps.review.outputs.findings }}:

for_each = "files: {{ inputs.title }}"
[inputs.static]
title = { type = "string", description = "The title." }

no-such-item-field: A reference names an item field the items are known not to have. The example [for-each-field](#example-for-each-field) fails with step.lint.run[0]: {{ each.name }}: the items have no field "name" (they have path).

Rules for shell quoting

Where a reference may sit in a shell command. Every rule is in the index of load rules.

shell-backslash: A reference in a shell command comes right after a \. This file fails with step.a.run[0]: {{ inputs.title }} follows a backslash, which would undo its quoting:

[metadata]
spec_version = "0.1.0"
name = "x"
[inputs.static]
title = { type = "string", description = "The title." }
[[step.a]]
kind = "shell"
description = "Runs a."
run = ["echo \\{{ inputs.title }}"]

shell-comment: A reference in a shell command comes after a # comment. The example [shell-comment](#example-shell-comment) fails with step.a.run[0]: {{ inputs.title }} comes after a # comment, inside which the shell ignores quotes; put comments after the last reference, or drop them.

shell-continued: A reference in a shell command comes after a backslash-newline. The example [shell-continued](#example-shell-continued) fails with step.a.run[0]: {{ inputs.title }} comes after a backslash-newline, which the shell deletes before reading the command; keep the command on one line, or split it into two commands.

shell-dollar: A reference in a shell command comes right after a $. The example [shell-dollar](#example-shell-dollar) fails with step.a.run[0]: {{ inputs.var }} follows a $, which would change its quoting.

shell-heredoc: A reference in a shell command sits in a here-document. The example [shell-heredoc](#example-shell-heredoc) fails with step.a.run[0]: {{ inputs.body }} is inside a here-document, where quoting does not apply.

shell-in-quotes: A reference in a shell command sits inside the command's own quotes. The example [shell-in-quotes](#example-shell-in-quotes) fails with step.a.run[0]: {{ inputs.title }} is inside quotes; a reference is quoted for you, so write it bare, as in echo {{ inputs.title }}.

shell-nested: A reference in a shell command comes after $(, a backtick, ${, $((, ((, $[, $' or $". The example [shell-substitution](#example-shell-substitution) fails with step.a.run[0]: {{ inputs.pr }} comes after a $(, ${, $((, backtick or similar, inside which the shell quotes afresh; set a variable first, as in X={{ inputs.title }}; echo "$(f "$X")".

Rules for looprail steps

Looprail steps, the files they run, and their overrides. Every rule is in the index of load rules.

agents-redefine: A looprail a looprail step runs defines a named agent of the file, or of a looprail that runs it, with a different llm or lifetime. This file, with the files below, fails with step.c.looprail: child.toml defines agent "coder" with a different llm or lifetime:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }
[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"
[agents.coder]
lifetime = "item"
[[agents.coder.llm]]
provider = "claude"

brief.md:

Do it.

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }

[agents.coder]
lifetime = "step"

[[agents.coder.llm]]
provider = "claude"
model = "opus"

decision-models-redefine: A looprail a looprail step runs defines a decision model of the file, or of a looprail that runs it, with different llm rows. This file, with the files below, fails with step.c.looprail: child.toml defines decision model "triage" with different llm rows:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"
[[decision-models.triage.llm]]
provider = "jev"

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

[[step.d]]
kind = "decision-model"
description = "Decides."
state = "s"
decision-model = { name = "triage" }

[step.d.questions.ok]
type = "yes-no"

[[decision-models.triage.llm]]
provider = "jev"
model = "jev-1.14.0"

looprail-invalid: The looprail a looprail step names does not load. Adding this to the end of the base file, with the files below:

[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

It fails with:

step.c.looprail: child.toml is not valid:
step: the file has no steps

looprail-nested: A looprail step of the looprail a looprail step names fails. Adding this to the end of the base file, with the files below:

[[step.m]]
kind = "looprail"
description = "Runs the middle."
looprail = "middle.toml"

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

middle.toml:

[metadata]
spec_version = "0.1.0"
name = "middle"

[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"

It fails with:

step.m.looprail: middle.toml:
step.c.looprail: child.toml is not valid:
step: the file has no steps

looprail-override-no-agent: A looprail step has overrides, but its looprail has no agent or agent-gate step. Adding this to the end of the base file, with the files below, fails with step.c.override: child.toml has no agent or agent-gate step for an override to replace:

[[step.plan]]
kind = "shell"
description = "Runs plan."
run = ["true"]
[step.plan.outputs]
changes = { type = "list", description = "The changes.", items = { hard = { type = "bool" } } }
[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"
needs = ["plan"]
for_each = "{{ steps.plan.outputs.changes }}"
[[step.c.override]]
match = { hard = true }
agent = { command = ["claude-agent-acp"] }

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

looprail-path: A looprail step's looprail path cannot be made absolute. No example: it fails only when looprail cannot read its own working directory.

looprail-self: A looprail step runs the file it is in, directly or through other looprails. The example [looprail-self](#example-looprail-self) fails with step.again.looprail: looprail.toml runs itself.

override-agent-required: An override has no agent. Adding this to the end of the base file, with the files below, fails with step.c.override[0].agent: is required:

[[step.plan]]
kind = "shell"
description = "Runs plan."
run = ["true"]
[step.plan.outputs]
changes = { type = "list", description = "The changes.", items = { hard = { type = "bool" } } }
[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"
needs = ["plan"]
for_each = "{{ steps.plan.outputs.changes }}"
[[step.c.override]]
match = { hard = true }

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

override-match-required: An override has no match, or an empty one. Adding this to the end of the base file, with the files below, fails with step.c.override[0].match: is required:

[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"
[[step.c.override]]
agent = { command = ["claude-agent-acp"] }

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

override-match-value: An override's match holds a value that is not a string, a number or a boolean. Adding this to the end of the base file, with the files below, fails with step.c.override[0].match.hard: must be a string, a number or true or false:

[[step.plan]]
kind = "shell"
description = "Runs plan."
run = ["true"]
[step.plan.outputs]
changes = { type = "list", description = "The changes.", items = { hard = { type = "bool" } } }
[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"
needs = ["plan"]
for_each = "{{ steps.plan.outputs.changes }}"
[[step.c.override]]
match = { hard = [true] }
agent = { command = ["claude-agent-acp"] }

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

override-reusable-inline: An override puts an inline command in place of a named agent whose lifetime is item or run. This file, with the files below, fails with step.c.override[0].agent: step "code" of child.toml uses agent "coder", whose session outlives a step; replace it with agent = { name = "<agent>" }:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.plan]]
kind = "shell"
description = "Runs plan."
run = ["true"]
[step.plan.outputs]
changes = { type = "list", description = "The changes.", items = { hard = { type = "bool" } } }
[[step.c]]
kind = "looprail"
description = "Runs the child."
looprail = "child.toml"
needs = ["plan"]
for_each = "{{ steps.plan.outputs.changes }}"
[[step.c.override]]
match = { hard = true }
agent = { command = ["codex-acp"] }
[agents.coder]
lifetime = "item"
[[agents.coder.llm]]
provider = "claude"

brief.md:

Do it.

child.toml:

[metadata]
spec_version = "0.1.0"
name = "child"

[[step.code]]
kind = "agent"
description = "Codes."
brief = "brief.md"
agent = { name = "coder" }

override-step: An override sets anything but match and agent. The example [looprail-override-step](#example-looprail-override-step) fails with step.change.override.kind: an override can only replace an agent; it cannot add, remove or reorder a step.

Rules for limits

The [limits] table. Every rule is in the index of load rules.

limit-low: A limit's max_parallel is below 1. Adding this to the end of the base file fails with limits.shell.max_parallel: 0 is below 1:

[limits.shell]
max_parallel = 0

limit-required: A limit has no max_parallel. Adding this to the end of the base file fails with limits.shell.max_parallel: is required:

[limits.shell]

provider: A decision-model limit names a provider looprail does not have. The example [limits-provider](#example-limits-provider) fails with limits.decision-model.gpt: "gpt" is not a provider; use one of jev.

Rules for briefs

Reading a step's brief. Every rule is in the index of load rules.

brief-read: A brief cannot be read. This file fails with step.a.brief: open briefs/missing.md: <the system's error>:

[metadata]
spec_version = "0.1.0"
name = "x"
[[step.a]]
kind = "agent"
description = "Runs a."
agent = { command = ["claude-agent-acp"] }
brief = "briefs/missing.md"

Proposals

Every change to the format is a proposal, an LRP, numbered from 0000 up. LRP-0000 sets out how one is written, accepted and implemented. Each breaking version has a migration guide, and the changelog lists the LRPs each version implemented. looprail spec <page> prints each of them.

LRPTitleStatusTypeSincepage
LRP-0000Spec proposalsimplementedclarification0.1.0proposals/0000
LRP-0001Spec versioningimplementedfeature0.1.0proposals/0001
LRP-0002The file formatimplementedfeature0.1.0proposals/0002
LRP-0003Configimplementedfeature0.1.0proposals/0003
LRP-0004Inputsimplementedfeature0.1.0proposals/0004
LRP-0005Typesimplementedfeature0.1.0proposals/0005
LRP-0006Stepsimplementedfeature0.1.0proposals/0006
LRP-0007Agent stepsimplementedfeature0.1.0proposals/0007
LRP-0008Shell stepsimplementedfeature0.1.0proposals/0008
LRP-0009Agent-gate stepsimplementedfeature0.1.0proposals/0009
LRP-0010Shell-gate stepsimplementedfeature0.1.0proposals/0010
LRP-0011Decision-model stepsimplementedfeature0.1.0proposals/0011
LRP-0012Human stepsimplementedfeature0.1.0proposals/0012
LRP-0013API stepsimplementedfeature0.1.0proposals/0013
LRP-0014MCP stepsimplementedfeature0.1.0proposals/0014
LRP-0015Looprail stepsimplementedfeature0.1.0proposals/0015
LRP-0016Agentsimplementedfeature0.1.0proposals/0016
LRP-0017Outputsimplementedfeature0.1.0proposals/0017
LRP-0018Templates and referencesimplementedfeature0.1.0proposals/0018
LRP-0019Conditional stepsimplementedfeature0.1.0proposals/0019
LRP-0020For eachimplementedfeature0.1.0proposals/0020
LRP-0021Shell quotingimplementedfeature0.1.0proposals/0021
LRP-0022Failureimplementedfeature0.1.0proposals/0022
LRP-0023Limitsimplementedfeature0.1.0proposals/0023

Migration guides

A file moves to a new major version by hand, with the guide of each breaking version between its own and the one it moves to.

No version has a guide yet.

LRP-0000: Spec proposals

FieldValue
LRP0000
AuthorAriel Sosnovsky
Statusimplemented
Typeclarification
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0000-spec-proposals.md

Motivation (LRP-0000)

Files written for one version of the looprail spec must keep working, or say plainly what to change. A change to the spec that lands with no record of what changed, why, and how to move a file over leaves the people and agents who write looprails guessing. Specs such as the Compose spec and Nostr's NIPs solve this with numbered proposals: one short document per change, kept for good.

Specification (LRP-0000)

Every change to the looprail file format is a proposal, an LRP, numbered from 0000 up. A change to the format is any change to its fields, step kinds, types, load rules or their meaning. A fix to the wording of a page that changes no meaning needs no LRP.

An LRP is a Markdown file, looprail/internal/spec/lrp/proposals/<NNNN>-<slug>.md, so the binary embeds it and looprail spec and the MCP tools serve it. It starts with front matter, key: value lines between two --- lines:

KeyHolds
lrpIts number, which the file's name starts with, four digits wide.
titleA few words on what it changes.
authorWho wrote it.
statusdraft, accepted, implemented, rejected or superseded.
typefeature (adds to the format), change (changes it, and every file that loaded still loads), breaking (a file that loaded may fail, or mean something else) or clarification (says what the format already does).
sinceThe spec version that implemented it. Required once it is implemented.
supersedesThe numbers of the LRPs it replaces, separated by commas.
migrationThe version of the migration guide it needs. Required for a breaking LRP.

The body has no title of its own, since the generator writes one from title, and holds these sections, in this order:

  • Motivation: the problem, and why the format should change.
  • Specification: exactly what changes, field by field and rule by rule.
  • Examples: files before and after, in TOML and JSON where they differ.
  • Compatibility: which files still load, and which fail or change meaning.
  • Migration, for a breaking LRP: what a file must change, in short. The full steps are in the migration guide.

Each breaking version has a migration guide, looprail/internal/spec/lrp/migrations/<version>.md, whose front matter holds to (its version, which names the file), from (the version before it) and lrp (the breaking LRPs it covers, separated by commas). It says what changed and why, shows files before and after in TOML and JSON, and lists the steps to move a file by hand. There is no command that rewrites a file.

The life of an LRP (LRP-0000)

  1. A proposal's pull request adds its file with the status draft, or accepted once the maintainers agree to it. It may merge before any code changes.
  2. The pull request that implements it sets the status implemented and since to the new spec version, and bumps spec.Version: the MINOR version for a feature or a change, the MAJOR version for a breaking LRP, and the PATCH version for a clarification. A breaking LRP adds its migration guide in the same pull request.
  3. A new or changed field or kind needs an entry in spec.SinceTable, keyed by its place (KindPlace(kind) for a kind).
  4. The entry names the LRP and the spec version. Once the LRP is implemented, the version must match the LRP's since.
  5. The implementing pull request adds these entries along with the spec.Version bump.
  6. An LRP that will not be built is rejected. One that a later LRP replaces is superseded, and the later one names it in supersedes.

An LRP's number never changes and its file is never removed.

What the generator checks (LRP-0000)

The generator writes each LRP and guide into the spec's pages, with an index of the LRPs and a changelog of the implemented ones by version. It fails on two LRPs with one number, an unknown status or type, an implemented LRP with no since, a breaking LRP with no migration guide, and a guide that names an LRP that does not exist. It also fails on:

  • a field or kind with no since entry;
  • a since that names an LRP that is missing, or is neither implemented nor accepted;
  • a since whose version differs from the LRP's since;
  • a spec.Version lower than the highest since.

The generator adds the LRP's number to each heading of its body, and a guide's version to each of its headings, so their anchors stay unique across the spec.

Examples (LRP-0000)

The front matter of a feature, once implemented:

---
lrp: 7
title: Step timeouts
author: A. Writer
status: implemented
type: feature
since: 0.2.0
supersedes:
migration:
---

Compatibility (LRP-0000)

This LRP changes no file. It sets out how every later change is made.

LRP-0001: Spec versioning

FieldValue
LRP0001
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0001-spec-versioning.md

Motivation (LRP-0001)

A file that does not say which spec it was written for can be broken silently by any later change to the spec, its fields, step kinds or load rules. A loader that reads a file written for a newer spec should say so, and an agent that meets a file of an older major version should be able to find what to change.

Specification (LRP-0001)

The metadata table (LRP-0001)

A file declares its spec version in a [metadata] table, which also holds what the file is:

FieldHolds
spec_versionThe spec version the file is written for. Required.
nameThe looprail's name. Required.
descriptionOne sentence on what it does.

A key the table does not have fails, naming it, like a key of [config]. A file with no [metadata] table fails to load, and name or description at the top level is an unknown field.

Versions (LRP-0001)

spec_version is plain semver, MAJOR.MINOR.PATCH, with no v, no pre-release and no short form such as 0.1. The first version is 0.1.0. Each LRP that is implemented bumps the spec's version, as LRP-0000 sets out: MINOR for a feature or a change, MAJOR for a break, PATCH for a clarification.

A looprail built for spec X.Y.Z loads a file whose major version is X and whose version is no higher than X.Y.Z. So a looprail for 1.2.3 loads 1.0.1 and 1.2.0. It fails on 1.2.4 and 2.0.1, saying to upgrade looprail, and on 0.3.5, an older major version, pointing to the migration guide the file needs.

Since (LRP-0001)

Every field and step kind records the spec version that added it, its since, and the LRP that did. A file may use only what exists at the version it declares: a file that declares 0.1.0 and sets a field added in 0.1.3 fails, naming the field and both versions. Everything in the spec when this LRP is implemented is since 0.1.0.

Moving a file over (LRP-0001)

There is no looprail migrate. A file moves to a new major version by hand, following the version's migration guide. The guides are pages of the spec, as looprail spec migrations/<version>, and the MCP tool get_looprail_migration returns the guides a file needs, from its declared version to the spec of the running looprail. validate_looprail points to the tool when a file is of an older major version.

Examples (LRP-0001)

A file at spec 0.1.0:

[metadata]
spec_version = "0.1.0"
name = "hello"
description = "Says hello."

[[step.greet]]
kind = "shell"
description = "Greets."
run = ["echo", "hello"]

Compatibility (LRP-0001)

0.1.0 is the first version of the spec, so there are no earlier files to move over.

LRP-0002: The file format

FieldValue
LRP0002
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0002-file-format.md

Motivation (LRP-0002)

A looprail is written by people and by agents, and read by a loader that must reject a mistake before any step runs. The file needs one plain shape, in a format both can write, with errors that say exactly which field is wrong.

Specification (LRP-0002)

  • A looprail is TOML, or JSON for a file named .json or a document on stdin that starts with {. JSON is turned into the same TOML document before it is decoded, so both give the same errors with the same field names, and null is not allowed anywhere.
  • The top level holds metadata (LRP-0001), inputs, step, agents, harnesses, decision-models, limits and config, each set out by the LRP of its part. Only metadata and step are required.
  • A step is [[step.<name>]] in TOML, an array of tables holding exactly one element; in JSON, step.<name> is an object or a list holding one object. The order of the file is only the order of the list.
  • A name of a step, named agent, harness or decision model must not be empty or hold ", { or }. A name that is not letters, digits, _ and -, starting with a letter or _, is written in double quotes in references and errors.
  • A field the format does not have fails, naming it. A field that takes a whole number also takes one written as a float, such as 2.0; 2.5 fails.
  • The whole file, every brief it reads and every looprail it runs are checked before anything is asked or run. A file that is not valid exits 2. Every error names its field by its path, as step.fix.run[0], and the loader lists every error it finds.

The full text is The file and Rules for the file.

Examples (LRP-0002)

The same looprail in TOML and in JSON:

[metadata]
spec_version = "0.1.0"
name = "hello"

[[step.hello]]
kind = "shell"
description = "Prints a greeting."
run = ["echo hello"]
{
  "metadata": { "spec_version": "0.1.0", "name": "hello" },
  "step": {
    "hello": {
      "kind": "shell",
      "description": "Prints a greeting.",
      "run": ["echo hello"]
    }
  }
}

Compatibility (LRP-0002)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0003: Config

FieldValue
LRP0003
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0003-config.md

Motivation (LRP-0003)

Some settings apply to a whole run rather than to one step, such as running every step inside the project's Nix dev shell so each has the same tools. They need one place in the file, apart from the steps.

Specification (LRP-0003)

  • A [config] table holds the settings for the whole file. A file without it loads with every setting off, and a key the table does not have fails, naming it.
  • enable_nix, true or false, runs the whole of looprail run inside the Nix dev shell of the directory it was started in: from its flake.nix through nix develop, or else from its shell.nix through nix-shell. Parent directories are not searched. A run already inside a Nix shell, with IN_NIX_SHELL set, carries on as it is. Outside one, the looprail must come from a file, not stdin. Only the file given to run counts; enable_nix in a file a looprail step runs has no effect.

The full text is Config and The Nix dev shell.

Examples (LRP-0003)

[metadata]
spec_version = "0.1.0"
name = "config"

[config]
enable_nix = true

[[step.a]]
kind = "shell"
description = "Runs a."
run = ["true"]

Compatibility (LRP-0003)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0004: Inputs

FieldValue
LRP0004
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0004-inputs.md

Motivation (LRP-0004)

One looprail runs for many changes, issues or branches. Its caller needs to pass the values that differ between runs, have them checked before anything runs, and derive the values that follow from them, such as a branch name, in one place rather than in every step.

Specification (LRP-0004)

  • [inputs.static] declares the inputs a caller passes, by name, in the order a person is asked for them. Each has a type (string, enum, bool, int or float), a description, an optional default and the bounds of its type (LRP-0005). An input with no default is required, an input the file does not declare is an error, and an input cannot be a list, so it has no items.
  • A caller passes them as run's inputs JSON, the inputs event in --std mode, the questions of the terminal UI or the form --web serves, and each is checked against its declaration.
  • [inputs.derived] maps a name to a template that may reference only static inputs, rendered as plain text before any step runs. A derived input is a string and may not share a name with a static one.
  • A step reads either as {{ inputs.<name> }}.

The full text is Inputs and Rules for inputs.

Examples (LRP-0004)

[metadata]
spec_version = "0.1.0"
name = "inputs"

[inputs.static]
issue = { type = "int", description = "The number of the issue it fixes.", min = 1 }
label = { type = "enum", description = "The label the pull request gets.", values = ["bug", "chore"], default = "bug" }

[inputs.derived]
branch = "{{ inputs.label }}/{{ inputs.issue }}"

[[step.show]]
kind = "shell"
description = "Prints the branch."
run = ["echo {{ inputs.branch }}"]

Compatibility (LRP-0004)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0005: Types

FieldValue
LRP0005
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0005-types.md

Motivation (LRP-0005)

Values cross from a caller to a step, and from one step to the next, often written by an agent. A declared type with bounds lets the loader check every reference before the run, and lets the run reject a value that does not fit before a later step acts on it.

Specification (LRP-0005)

  • Inputs, outputs and the fields of a list's items declare a type. Inputs have string, enum, bool, int and float; outputs and item fields also have list.
  • string takes min_length and max_length, counted in characters. enum needs values, a non-empty list. int and float take min and max, and an int's bounds are whole numbers. list takes items, the fields each item, an object, holds; a list without items holds anything.
  • A bound applies to its type only, min may not exceed max nor min_length max_length, and an empty values or items fails.
  • Every static input and declared output has a description; an item field may have one. Only an input has a default, which must check out against its declaration.

The full text is Types and Rules for types.

Examples (LRP-0005)

[step.review.outputs]
verdict_note = {
    type = "string",
    description = "Why, in a sentence.",
    min_length = 1,
    max_length = 200
}
severity = {
    type = "enum",
    description = "How bad the worst finding is.",
    values = ["low", "high"]
}
findings = {
    type = "list",
    description = "One item per problem.",
    items = {
        title = { type = "string" },
        line = { type = "int", min = 1 }
    }
}

Compatibility (LRP-0005)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0006: Steps

FieldValue
LRP0006
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0006-steps.md

Motivation (LRP-0006)

A looprail is a graph of work. Each node needs a name, a kind that says what it does, a sentence on why it is there, and the steps it waits for, so independent work runs at the same time and a step reads only what has already happened.

Specification (LRP-0006)

  • A step is a table in the array step.<name>, written [[step.<name>]] with its sub-tables after it. Two steps may not share a name.
  • Every step sets kind, one of agent, shell, agent-gate, shell-gate, decision-model, human, api, mcp or looprail, each set out by an LRP of its own, and description, one sentence that must not be blank.
  • needs lists the steps that must settle before this one starts. Each name must exist, appear once and not be the step itself, and the needs may not form a cycle. A step runs once every step it needs has passed or been skipped, and steps that are ready run at the same time, up to the limits.
  • cwd is the directory the step's commands or agent run in: a template rendered as plain text, relative to the directory looprail was started in, which is also its default. A looprail step has none.
  • env sets environment variables for the harness of an agent or agent-gate step, or the server an mcp step starts, merged over looprail's own. Values are taken as written, with no references. PATH, PWD and LOOPRAIL_* are reserved.
  • A step has no provider: it belongs on an llm row.
  • A step that sets a field its kind does not have fails, naming it, and so does one that leaves out a field its kind needs.

The common fields when (LRP-0019), for_each (LRP-0020), and on_fail, failover, max_loops and max_retries (LRP-0022) have LRPs of their own. The full text is Steps, Rules for steps and Rules for needs and loops.

Examples (LRP-0006)

[[step.build]]
kind = "shell"
description = "Builds the binary."
run = ["make"]

[[step.test]]
kind = "shell"
description = "Runs the tests."
needs = ["build"]
cwd = "looprail"
run = ["go test ./..."]

Compatibility (LRP-0006)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0007: Agent steps

FieldValue
LRP0007
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0007-agent-steps.md

Motivation (LRP-0007)

Most of the work a looprail does is done by coding agents. A step needs to start one, hand it a prompt written beside the looprail, and get back typed outputs the steps after it can read, while the agent keeps working on background tasks it started.

Specification (LRP-0007)

  • kind = "agent" needs agent and brief (LRP-0016), and may set env (LRP-0006) and idle_limit. It declares outputs (LRP-0017) and may set failover = "agent".
  • The step starts its agent, sends the rendered brief as the prompt with a note listing the fields the final JSON must hold, and takes its outputs from the JSON object the last message ends with. When that message has none, the JSON does not parse or it does not match the outputs, the step asks again in the same session, with the reason, up to 2 times before it fails. A turn that ends for any reason but the end of the turn fails the step.
  • With a harness that reports background tasks through the AIR asyncTasks extension, the step goes on until no task and no autonomous turn is live, and the last message is the last one the agent wrote.
  • idle_limit is how long the step may wait for its background tasks with no update from the harness before it fails: a duration such as 30m, or unlimited. Unset, it is 1h.

The full text is [agent steps](#agent-steps).

Examples (LRP-0007)

[[step.code]]
kind = "agent"
description = "An agent fixes the issue."
agent = { provider = "claude", model = "opus" }
brief = "briefs/code.md"
idle_limit = "2h"

[step.code.outputs]
summary = { type = "string", description = "What the agent changed.", min_length = 1 }

Compatibility (LRP-0007)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0008: Shell steps

FieldValue
LRP0008
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0008-shell-steps.md

Motivation (LRP-0008)

Much of a loop is plain commands: making a branch, building, running the tests, pushing. They need no agent, and should run as written, with their results passed on to later steps.

Specification (LRP-0008)

  • kind = "shell" needs run, a non-empty list of shell commands. It declares outputs (LRP-0017).
  • Each entry of run runs through sh -c in the step's cwd, in order, with stdin closed, and the step fails at the first that exits non-zero. Each is a template under the shell quoting rules (LRP-0021). Its line and exit go to the step run's log folder in the run folder, with its whole output when it fails.
  • The commands write the step's outputs to the file named by $LOOPRAIL_OUTPUTS, as KEY=value lines or one JSON object, and $LOOPRAIL_CURRENT_RUN_DIR holds the run folder's path.

The full text is [shell steps](#shell-steps).

Examples (LRP-0008)

[[step.branch]]
kind = "shell"
description = "Makes the branch and says its name."
run = [
  "git switch -c {{ inputs.branch }}",
  "echo name={{ inputs.branch }} >> \"$LOOPRAIL_OUTPUTS\""
]

[step.branch.outputs]
name = {
  type = "string",
  description = "The branch it made."
}

Compatibility (LRP-0008)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0009: Agent-gate steps

FieldValue
LRP0009
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0009-agent-gate-steps.md

Motivation (LRP-0009)

A loop often needs a judgment rather than a change: is this diff ready, does it fix the issue. An agent can make that call, and the loop needs it as a pass or a rejection that on_fail and when can act on.

Specification (LRP-0009)

  • kind = "agent-gate" needs agent, brief and accept, and may set env and idle_limit. It declares outputs, and sets verdict, a string, itself; it may not declare verdict.
  • It prompts its agent as an agent step does (LRP-0007), and its prompt tells it to change no file. Its JSON also holds verdict, and the gate passes, with {{ steps.<name>.accepted }} true, when the verdict equals accept. Any other verdict rejects it.
  • A gate that rejects fails like any step, unless its on_fail names a step downstream of it and sends its rejection ahead (LRP-0022).

The full text is [agent-gate steps](#agent-gate-steps).

Examples (LRP-0009)

[[step.review]]
kind = "agent-gate"
description = "An agent reviews the change."
needs = ["code"]
agent = { provider = "claude", model = "sonnet" }
brief = "briefs/review.md"
accept = "accept"
on_fail = "code"
max_loops = 3

Compatibility (LRP-0009)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0010: Shell-gate steps

FieldValue
LRP0010
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0010-shell-gate-steps.md

Motivation (LRP-0010)

Many checks are commands whose exit code is the answer: the linter, the tests, git diff --quiet. A loop needs them as a gate, so a failing check can send the run back to fix it, rather than as a plain step that only fails.

Specification (LRP-0010)

  • kind = "shell-gate" needs run and accept_exit, a non-empty list of exit codes. It declares outputs.
  • It runs run as a shell step does (LRP-0008), and passes, with {{ steps.<name>.accepted }} true, when every command exits with a code in accept_exit. Another code rejects it.
  • A gate that rejects fails like any step, unless its on_fail names a step downstream of it and sends its rejection ahead (LRP-0022).

The full text is [shell-gate steps](#shell-gate-steps).

Examples (LRP-0010)

[[step.clean]]
kind = "shell-gate"
description = "Passes when the tree has no changes."
run = ["git diff --quiet"]
accept_exit = [0]

Compatibility (LRP-0010)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0011: Decision-model steps

FieldValue
LRP0011
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0011-decision-model-steps.md

Motivation (LRP-0011)

Some choices in a loop are small typed judgments, such as which of three routes to take or how risky a change is, where a full agent session is slow and its answer hard to parse. A decision model answers set questions about a piece of state with typed values and confidences that when can compare.

Specification (LRP-0011)

  • [decision-models.<name>] defines a decision model with one field, llm: the models it may call, in order, each [[decision-models.<name>.llm]] with a provider, which must be jev, and a model, jev-latest when unset. A decision model must be named by a step of the file or of a looprail it runs, may not share its name with a named agent, and a looprail that defines the name again must give it the same rows.
  • kind = "decision-model" needs decision-model, { name = "<name>" }, state, a template rendered as plain text, and questions, a non-empty table of [step.<name>.questions.<question>]. It declares no outputs.
  • A question has a type: choice, with criteria mapping each value to what it means; yes-no; or score, with 2 to 10 levels, lowest first. It may set instructions, and a choice or score may set probabilities.
  • Each question sets an output of its name: a choice an enum of its criteria keys, yes-no a float from 0 to 1, score a float from 0 to the index of its last level. A choice and a score also set <question>_confidence, and with probabilities = true <question>_probabilities.
  • No provider is built yet, so the step fails when it runs.

The full text is [decision-model steps](#decision-model-steps) and Rules for decision models.

Examples (LRP-0011)

[[decision-models.judge.llm]]
provider = "jev"

[[step.route]]
kind = "decision-model"
description = "Judges how risky the change is."
needs = ["code"]
decision-model = { name = "judge" }
state = "{{ steps.code.outputs.summary }}"

[step.route.questions.risk]
type = "score"
levels = ["low", "medium", "high"]

Compatibility (LRP-0011)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0012: Human steps

FieldValue
LRP0012
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0012-human-steps.md

Motivation (LRP-0012)

Some decisions belong to a person: whether to merge, which option to take. A loop needs to stop, ask, and carry the answer on to the steps after it, from whichever front end the person is using.

Specification (LRP-0012)

  • kind = "human" needs ask, a template rendered as plain text, and may set choices, a non-empty list of answers, none blank or listed twice. It declares no outputs, and sets answer, a string: the reply.
  • The terminal UI, the --web page, a question event in --std mode or an MCP client asks the person. A front end shows choices as buttons, and an answer that names one with action sets answer to it; a person may still answer with text.
  • The reply stop, in any case, ends the run at once, with no failover.

The full text is [human steps](#human-steps).

Examples (LRP-0012)

[[step.merge]]
kind = "human"
description = "Asks a person whether to merge."
needs = ["review"]
ask = "Merge {{ inputs.branch }}?"
choices = ["merge", "wait"]

Compatibility (LRP-0012)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0013: API steps

FieldValue
LRP0013
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0013-api-steps.md

Motivation (LRP-0013)

A looprail may sometimes need to interact with external services, with no agent and no shell script that builds JSON by hand, and without writing its token into the file.

Specification (LRP-0013)

  • kind = "api" needs url, and may set method, headers and body. It declares outputs, and sets status_code, an int, and body, the answer as text, itself.
  • It sends one request to url, a template rendered as plain text, with method (one of GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS, GET when unset) and headers, each value a template. A string body is a template sent as written; any other value is sent as JSON, with Content-Type: application/json unless headers sets one, and a string in it that is one reference alone takes the referenced value with its type.
  • A redirect is not followed, and like any status outside 2xx it fails the step. Declared outputs are picked by name from the JSON object the answer holds. The step's log records the call and its status, and keeps the answer only when the status is outside 2xx.
  • The request fields may reference {{ env.<NAME> }}, a variable of looprail's environment. Its value is hidden from all the step writes, and it fails at load anywhere but the request fields of an api or mcp step.

url and headers are shared with mcp steps (LRP-0014). The full text is [api steps](#api-steps) and Secrets.

Examples (LRP-0013)

[[step.notify]]
kind = "api"
description = "Posts the summary to Slack."
needs = ["code"]
method = "POST"
url = "https://slack.com/api/chat.postMessage"
headers = {
  Authorization = "Bearer {{ env.SLACK_TOKEN }}"
}
body = {
  channel = "#dev",
  text = "{{ steps.code.outputs.summary }}"
}

Compatibility (LRP-0013)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0014: MCP steps

FieldValue
LRP0014
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0014-mcp-steps.md

Motivation (LRP-0014)

Many services already offer their actions as MCP tools. A loop should be able to call one directly, with typed arguments and outputs, rather than prompting an agent to call it.

Specification (LRP-0014)

  • kind = "mcp" needs tool, and may set url, headers, command, env and arguments. It sets url or command, not both. It declares outputs, and sets text, a string, itself.
  • It reaches its server at url over streamable HTTP, with headers on every request (LRP-0013), or starts command, a non-empty argv whose entries are templates, in the step's cwd and talks to it over stdio, with env merged over its environment.
  • It calls tool with arguments, a table sent as a JSON object, whose strings are templates; a string that is one reference alone takes the referenced value with its type.
  • A redirect from url is not followed and fails the step, as does a result marked as an error. Its output text is the result's text, and declared outputs are picked by name from the structured content, or from text when it is a JSON object. The step's log records the call, whether it was an error, and a started server's stderr, and keeps the result only when the call failed.
  • Its request fields may reference {{ env.<NAME> }}, hidden from all the step writes, as an api step's do.

The full text is [mcp steps](#mcp-steps).

Examples (LRP-0014)

[[step.file]]
kind = "mcp"
description = "Files the issue."
command = ["github-mcp-server", "stdio"]
env = { GITHUB_TOOLSETS = "issues" }
tool = "create_issue"
arguments = {
  owner = "acme",
  repo = "app",
  title = "{{ inputs.title }}"
}

Compatibility (LRP-0014)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0015: Looprail steps

FieldValue
LRP0015
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0015-looprail-steps.md

Motivation (LRP-0015)

Loops are built from loops: a wave of tickets runs the single-ticket loop once per ticket. A file needs to run another looprail as one of its nodes, once or once per item, and to swap the agents it uses without copying it.

Specification (LRP-0015)

  • kind = "looprail" needs looprail, the path of the file it runs, relative to the directory looprail was started in. It may set override, and of the common fields only needs and for_each. It declares no outputs.
  • The looprail, and every file it runs, is loaded and validated before anything runs, and a file may not run itself, directly or through others. Each is checked against its own spec_version. Its steps show as <step>/<its step>, or <step>[<item>]/<its step> with for_each.
  • Without for_each, the looprail gets this run's inputs of the same names. With it, it runs once per item, and an item's fields named as the looprail's static inputs are its inputs; an item that is not an object is the field item.
  • [[step.<name>.override]] has only match, the fields of the for_each item it applies to, and agent, which replaces the agent of every agent and agent-gate step of the looprail for the items it matches. match reads the item, which comes from the list for_each goes over, never the looprail it runs, so an item may carry fields that are not that looprail's inputs for match alone. Without for_each there is no item, and an override never applies. A later override that matches wins. An override on a looprail with no agent step fails at load.
  • A looprail step takes no slot of the limits, but the looprail's steps share this run's slots. It passes when every run of the looprail passes.

The full text is [looprail steps](#looprail-steps) and Rules for looprail steps.

Examples (LRP-0015)

[[step.tickets]]
kind = "looprail"
description = "Runs the change looprail once per ticket."
for_each = "{{ steps.plan.outputs.tickets }}"
looprail = "looprails/change.toml"

[[step.tickets.override]]
match = { size = "small" }
agent = { provider = "claude", model = "sonnet" }

Compatibility (LRP-0015)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0016: Agents

FieldValue
LRP0016
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0016-agents.md

Motivation (LRP-0016)

Agent and agent-gate steps need to say which agent they prompt and with what. One step may want a fresh harness of its own; several may want to share one session, so the reviewer remembers the code it read, and fall back to another model when the first will not start. The prompt itself is long text that belongs in a file of its own, checked like any template.

Specification (LRP-0016)

  • A step's agent is a table that sets name, for a named agent, or an inline harness by provider, command or both, with an optional model. An inline harness is started afresh for every prompt and spoken to over ACP. A provider resolves to an argv from the file's [harnesses.<provider>] or a built-in harness (claude, codex, grok, goose, pi), and command wins. model is a name the harness offers through the session's model option, not an API model id.
  • [harnesses.<name>] holds command, a non-empty argv, and adds a harness a provider may name, or replaces a built-in one in this file.
  • [agents.<name>] is a named agent with two required fields: lifetime, step, item or run, how long its session lives; and llm, a non-empty list of [[agents.<name>.llm]] rows, the models it may run on, in order. A row sets provider, command or both, and may set model, endpoint, auth_env and config. A provider is an ACP harness, or a backend looprail calls itself (openrouter, openai, openai-compatible, ollama, goinfer or commandcode). A session starts on the first row that starts, and stays on it.
  • A step that names an agent sets neither provider, command, model nor lifetime. Every named agent must be named by a step, here or in a looprail this one runs, and a looprail that defines the name again must define it the same.
  • brief is the path of the step's prompt, relative to the looprail file. It is read at load, its references are checked, and its text, rendered as plain text, is the prompt. Its hash is part of the checkpoint, and a changed brief refuses --continue.

The full text is Agents, Rules for named agents and Rules for briefs.

Examples (LRP-0016)

[agents.coder]
lifetime = "run"

[[agents.coder.llm]]
provider = "claude"
model = "opus"
config = { effort = "high" }

[[agents.coder.llm]]
provider = "codex"

[[step.code]]
kind = "agent"
description = "An agent fixes the issue."
agent = { name = "coder" }
brief = "briefs/code.md"

Compatibility (LRP-0016)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0017: Outputs

FieldValue
LRP0017
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0017-outputs.md

Motivation (LRP-0017)

A step's result has to reach the steps after it in a form they can rely on. Declaring each output with a type lets the loader check every reference to it, tells an agent exactly what JSON to end with, and fails the step that produces a wrong value rather than the one that reads it.

Specification (LRP-0017)

  • Agent, agent-gate, shell, shell-gate, api and mcp steps declare their outputs in [step.<name>.outputs], one key per output, each with a type (LRP-0005), including list, and a description. An output has no default.
  • A step must set exactly the outputs it declares: a missing output, an undeclared one, a value of the wrong type or out of bounds fails the step. An api or mcp step picks them out of an answer that may hold more.
  • A shell step writes them to the file named by $LOOPRAIL_OUTPUTS, as KEY=value lines, a later line winning, or one JSON object; a list must be JSON. An agent step's last message ends with one JSON object holding them.
  • Some outputs are set by the kind and never declared: a human step's answer, an agent-gate's verdict, a decision-model step's per question, an api step's status_code and body, and an mcp step's text.
  • Later steps read an output as {{ steps.<name>.outputs.<output> }}.

The full text is Outputs.

Examples (LRP-0017)

[[step.count]]
kind = "shell"
description = "Counts the open issues."
run = ["echo open=$(gh issue list --json number --jq length) >> \"$LOOPRAIL_OUTPUTS\""]

[step.count.outputs]
open = { type = "int", description = "How many issues are open.", min = 0 }

Compatibility (LRP-0017)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0018: Templates and references

FieldValue
LRP0018
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0018-templates-and-references.md

Motivation (LRP-0018)

Steps are only useful together when one can use what another produced. Text fields need a way to name an input or an earlier step's output, plain enough for anyone to read, and strict enough that every name is checked at load rather than failing halfway through a run.

Specification (LRP-0018)

  • A template is text holding references in {{ }}, each holding exactly one reference, never an expression. Templates may appear in run, a brief's text, ask, cwd, state, for_each, the request fields of an api or mcp step, a derived input, and when, which holds an expression (LRP-0019).
  • A reference is inputs.<name>; steps.<name>.outputs.<output>, .outputs (a for_each step's entries), .status, .loops or .accepted; each or each.<field> (LRP-0020); or env.<NAME>, only in the request fields of an api or mcp step (LRP-0013).
  • A name is letters, digits, _ and -, starting with a letter or _; any other name is written in double quotes.
  • A reference to a step must go through needs, directly or through other steps. Every reference is checked at load: its step, its output and, where known, its type.
  • In a shell command a reference becomes one quoted word (LRP-0021). Elsewhere it is plain text, and a list or object is written as JSON. A reference to something with no value fails the step when it is substituted.

The full text is References, Rules for templates and Rules for references.

Examples (LRP-0018)

[[step.merge]]
kind = "human"
description = "Asks a person whether to merge."
needs = ["code", "review"]
ask = "Merge {{ inputs.branch }} after {{ steps.review.loops }} reviews? {{ steps.code.outputs.summary }}"

Compatibility (LRP-0018)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0019: Conditional steps

FieldValue
LRP0019
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0019-conditional-steps.md

Motivation (LRP-0019)

A loop branches: merge only when the review accepted, notify only when something changed, act on a decision model's choice. A step needs a condition, checked at load against the types of what it compares, that skips it when false.

Specification (LRP-0019)

  • when is one {{ }} holding an expression, true or false; the step is skipped when it is false. A looprail step has no when.
  • The expression may hold references, 'strings' or "strings" with no escapes, numbers, true and false, == and !=, !, &&, || and parentheses. || binds loosest, then &&, then !, then == and !=, which do not chain.
  • Numbers compare by value, and values of different types are never equal. The file fails to load when it compares two known types that differ, uses a known non-boolean with !, && or ||, or compares an enum with a string that is not one of its values.
  • A reference with no value equals nothing, so == is false and != true.
  • On a for_each step when is evaluated per item; items where it is false are skipped, and a step whose items were all skipped is skipped.

The full text is when and [Rules for when](#rules-for-when).

Examples (LRP-0019)

[[step.merge]]
kind = "shell"
description = "Merges the pull request once the review accepts it."
needs = ["review"]
when = "{{ steps.review.accepted && inputs.draft == false }}"
run = ["gh pr merge --merge"]

Compatibility (LRP-0019)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0020: For each

FieldValue
LRP0020
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0020-for-each.md

Motivation (LRP-0020)

A review returns a list of findings, a planner a list of tickets, and each needs the same work done to it, at the same time. A step needs to run once per item of a list it is given, and hand its results on as a list in turn.

Specification (LRP-0020)

  • for_each is one reference to a list: an output of type list, or another for_each step's steps.<name>.outputs. The step runs once per item, the items at the same time, each taking its own slot of the limits, in item order.
  • {{ each }} is the item, and {{ each.<field> }} one of its fields; each is valid only in a step with for_each.
  • The step's own steps.<name>.outputs is the list of its entries: each item's fields plus the outputs the step set for it. An item that is not an object becomes {"item": <value>}. A for_each step has no single outputs, so steps.<name>.outputs.<output> on one fails at load.
  • each.<field> is checked at load when the items' shape is known, from a list's items or a for_each step's entries, and its type is what when checks against.

The full text is for_each and [Rules for for_each](#rules-for-for_each).

Examples (LRP-0020)

[[step.fix]]
kind = "agent"
description = "An agent fixes one finding."
needs = ["review"]
for_each = "{{ steps.review.outputs.findings }}"
agent = { provider = "claude", model = "opus" }
brief = "briefs/fix.md"

Compatibility (LRP-0020)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0021: Shell quoting

FieldValue
LRP0021
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0021-shell-quoting.md

Motivation (LRP-0021)

Values that reach a shell command often come from an agent or a caller: a title, a branch, a list of files. Pasting them into the command as text lets any value change how it parses. The value must stay one word whatever it holds, and a reference where the shell would quote it again must fail at load.

Specification (LRP-0021)

  • Each entry of run runs through sh -c, and a reference in it becomes one single-quoted word. It is written bare, and may be glued to plain text outside quotes, as in --title={{ x }}.
  • A list must stand alone as a word. It becomes one quoted word per element, or, after a flag word such as -x or --name, the flag repeated before each element. An empty list drops the flag.
  • The file fails to load, naming the command, when a reference sits inside the command's own quotes, in a here-document, right after a \ or a $, anywhere after $(, a backtick, ${, $((, ((, $[, $' or $", after a # comment, or after a backslash-newline.
  • The check errs on the side of a load error, so it rejects some safe forms too.

The full text is Shell quoting and Rules for shell quoting.

Examples (LRP-0021)

[[step.pr]]
kind = "shell"
description = "Opens the pull request."
run = ["X={{ inputs.title }}; gh pr create --title \"$X\" --label {{ inputs.labels }}"]

Compatibility (LRP-0021)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0022: Failure

FieldValue
LRP0022
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0022-failure.md

Motivation (LRP-0022)

A loop exists to recover from failure: a failed test goes back to the coder, a rejected review to the fix. A file needs to say where a failure sends the run, how often, and what happens when nothing in the file handles it.

Specification (LRP-0022)

  • on_fail names the step a failure sends the run back to: the step itself or one upstream of it through needs. That step and everything downstream of it go back to pending, and steps.<name>.loops counts the runs.
  • max_loops, at least 1, caps how many times on_fail may send the run back; it needs on_fail, and unset the loop has no cap.
  • A gate without for_each may instead name a step downstream of it in on_fail, to send its rejection ahead: the gate settles as passed with accepted = false, the steps after it run, and once the on_fail step settles the gate runs again. Such a gate must set max_loops.
  • failover says what happens when on_fail does not apply. human, the default, asks a person to retry, skip or stop, and on a failed gate with a live agent session also offers feedback and ask. agent hands the brief and the failure to a new session of the same agent, and only an agent or agent-gate step may set it.
  • max_retries, at least 0 and 3 when unset, is how many times a person may answer retry per loop. Retries count toward neither loops nor max_loops.
  • A looprail step sets none of these fields.

The full text is Failure and Rules for needs and loops.

Examples (LRP-0022)

[[step.test]]
kind = "shell-gate"
description = "Passes when the tests pass."
needs = ["code"]
run = ["make test"]
accept_exit = [0]
on_fail = "code"
max_loops = 3
max_retries = 1

Compatibility (LRP-0022)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

LRP-0023: Limits

FieldValue
LRP0023
AuthorAriel Sosnovsky
Statusimplemented
Typefeature
Since0.1.0
Sourcelooprail/internal/spec/lrp/proposals/0023-limits.md

Motivation (LRP-0023)

Steps that are ready run at the same time, and a for_each step can start dozens of agents at once. A harness's rate limits, a machine's cores or a provider's quota need a cap per sort of step that the file can set.

A slot counts agents at work, not sessions alive. A session that held its slot while idle between steps, with lifetime = "item" or "run", could leave every slot to paused sessions, so the steps that would let them end never started and the run hung until max_run_time. A for_each whose coder sessions stay live through each item's review deadlocked with more than half max_parallel items.

Specification (LRP-0023)

  • [limits] holds shell, a limit for shell and shell-gate steps; agent.<command>, a limit per harness, keyed by agent.command[0] exactly as written; and decision-model.<provider>, a limit per decision model provider, which must be jev.
  • A limit has one field, max_parallel, at least 1: how many such steps, or for_each items, of this run run at once. A key nobody sets has no cap. Human and looprail steps take no slot.
  • A step that names an agent counts against the harness of its agent's pinned llm row, or of its first row; a row over HTTP has no key. It takes its slot when it starts and gives it back when it settles, as a step with an inline harness does.
  • A named agent's session stays live between steps for as long as its lifetime says, but holds no slot while idle. A step that resumes a live session waits for a free slot like any other step, then gets the same session, with its conversation. One step at a time uses a session, and a step waiting for a session another step uses holds no slot while it waits. An idle session does not count among the running agent steps the kind limits and get_looprail_capacity report.
  • With looprail steps, a key this file sets wins, a key it leaves unset takes the largest value any looprail it runs sets, and --limit key=N wins over both. There is one pool of slots per key for the whole run.

The full text is Limits and Rules for limits.

Examples (LRP-0023)

[limits.shell]
max_parallel = 4

[limits.agent.claude-agent-acp]
max_parallel = 2

A for_each of 8 items whose coder session lives through each item's review runs to the end with at most 4 agents working at once: each coder gives its slot back when its step settles, and the reviewers take them.

[agents.coder]
lifetime = "item"

[[agents.coder.llm]]
provider = "claude"

[agents.reviewer]
lifetime = "step"

[[agents.reviewer.llm]]
provider = "claude"

[limits.agent.claude-agent-acp]
max_parallel = 4

Compatibility (LRP-0023)

This LRP records a part of the format as it stood in 0.1.0, the first version of the spec, and changes no file.

Before 0.1.0 was final, a named agent's session held its slot while idle. Every file that loaded still loads and means the same, but a run of it may now run more named-agent steps over its life, never more than max_parallel at once. A file that sized max_parallel at two per item to leave room for paused sessions may lower it.

Changelog

The LRPs each version of the spec implemented, the newest version first. Proposals lists every LRP, whatever its status.

Version 0.1.0

The MCP server

looprail mcp is an MCP (Model Context Protocol) server over stdio. It lets an agent validate, list, start, watch, answer, stop and resume looprail runs through tools. Stdout carries MCP messages only. The server's own lines go to stderr.

looprail mcp [--dir path] [--global] [--kind-limit kind=N]...
  • --dir is the project folder, by default the folder the server started in. Relative looprail paths are relative to it, and every run works in it.
  • --global uses the home directory. Run folders go under ~/.looprail/runs, and list_looprails lists only ~/.agents/looprails unless asked for both.
  • --kind-limit kind=N (repeatable) caps how many steps of one kind run at once across every run in your home, whichever server or terminal started them. The server passes it on to each run it starts.
KindCoversDefault limit
agentagent and agent-gate steps30
shellshell and shell-gate steps10 per CPU
mcpmcp steps50
apiapi and decision-model steps50

Runs are not capped by count, so a start or resume is never refused for how many are active. A step whose kind is full waits for a free slot and says so in the run's output. Slots are the lock files ~/.looprail/slots/<kind>/slot-<n>.lock. The old --max-concurrent-runs is still accepted, and ignored with a warning.

The server runs until stdin ends, then cancels every run it owns and exits 0. A wrong invocation exits 2. looprail install registers it with Claude Code, Codex, Grok, goose and pi. Restart the session of the harness (the agent program) afterwards.

Each run is a child process, looprail run --std, in its own run folder, <LOOPRAIL_RUN_DIR>/<file name>-<8 hex digits> (.tmp/agents/looprail/runs when that is unset).

  • cancel_looprail sends SIGINT to the run's process group, so its checkpoint (its record of what finished) is kept, and SIGKILL after 10 seconds if it has not stopped.
  • A run found at startup that stopped before it finished is interrupted. It is never started again on its own.
  • If the server dies, its runs stop within about 10 seconds, on macOS too. On Linux the kernel also sends them SIGTERM. The server marks its runs with LOOPRAIL_KILL_AFTER, which the run unsets so its steps never inherit it.

A run waits on a pending request of one of three kinds:

KindCarriesAnswer with
inputsthe form's schemainputs
questionthe question idtext
checkpointcontinue, true or false

A question leaves the pending requests when its step, or its item of a for_each step, stops running without an answer, as when the step times out. An answer that cannot be written to the run leaves its request pending.

Tools

Each tool answers in plain text. Tools that report a run, a listing or capacity add the same as JSON in a second text block. A tool that cannot do what it was asked answers with an error result.

Claude Code (client name claude-code) gets no JSON block unless it declares the App UI extension, because it shows every block as it is, and only structuredContent when an answer has it. Its status line and hook read the run id from the text's Run <id> (<looprail>) is <state>. line.

The last output in a status leaves out colour codes and the harness's debug lines (claude-agent-acp's [session/...] timings, the info logs of ACP, the protocol looprail uses to talk to the harness). A shell step with a description shows it as its input.

validate_looprailLoad a looprail file and every looprail it runs, and list what is wrong with each, naming the field. list_looprailsList the looprails in .agents/looprails of the project and of the home directory, with their inputs. start_looprailStart a run of a looprail file, wait up to wait_seconds (5 by default) for its first change, and answer with its run_id and full status: the steps table to show the user, what it waits for, and the call to make next. When inputs are missing or wrong the run is awaiting_inputs, and its pending request carries the input form's schema. A progressToken gets progress notifications while it waits. resume_looprailContinue a cancelled, failed or interrupted run from its checkpoint, in its own run folder. cancel_looprailStop a run: interrupt its process and everything it started, and keep its checkpoint so resume_looprail can continue it. get_looprail_statusReport a run, or every run the server owns: under Show the user its state, steps table, tokens spent and changes (lines added and removed, files read), with step and run_id the files that step read and edited and the commands it ran (each list capped at 200, with how many it left out), then its pending requests (a failed step's with its full error, its explanation, the end of its output, its log, the agent's reply to an ask and the choices it offers), details such as the last output and last event time, and under Next the call to make next. wait_seconds (5 by default, 0 answers at once, at most 300) waits for a change when nothing needs an answer; use 60 to 120 while a run goes. A progressToken gets progress notifications while it waits. provide_looprail_inputAnswer a run's pending request: inputs for its input form, action (one of the question's choices, such as retry, skip, stop, feedback or ask for a failed step), text or both for a question (id names the question), or continue for a checkpoint. get_looprail_capacityShow the active runs, the steps of each kind (agent, shell, mcp, api) running in your home against their kind limits, and per limit key the slots in use and waiting, summed and per run, with each run's own max_parallel. get_looprail_file_specReturn the looprail file format, one page at a time. get_looprail_guideReturn the guide to running, writing, updating, stopping and resuming looprails, the same text as the resource looprail://guide. get_looprail_migrationReturn the migration guides that move a looprail file to the spec this looprail reads.

validate_looprail

MCP tool

Load a looprail file and every looprail it runs, and list what is wrong with each, naming the field. The same as looprail validate.

ArgumentTypeWhat
file requiredstringthe looprail file, absolute or relative to the project folder
{"file":".agents/looprails/release.toml"}

list_looprails

MCP tool

List the looprails in .agents/looprails of the project and of the home directory, with their inputs. The same as looprail list.

ArgumentTypeWhat
dirstringthe project folder whose .agents/looprails is the project scope; the server's folder by default
scopestringall lists the project and the global looprails, global only the global ones; all by default, or global when the server was started with --global
{"scope":"all"}

start_looprail

MCP tool

Start a run of a looprail file, wait up to wait_seconds (5 by default) for its first change, and answer with its run_id and full status: the steps table to show the user, what it waits for, and the call to make next. When inputs are missing or wrong the run is awaiting_inputs, and its pending request carries the input form's schema. A progressToken gets progress notifications while it waits.

ArgumentTypeWhat
file requiredstringthe looprail file, absolute or relative to the project folder
inputsobjectthe looprail's static inputs; leave out to have the run ask for them
modestringfresh starts from the first step (the default); continue resumes the latest stopped run of this file with a checkpoint, and with these inputs when they are given
wait_secondsintegeronce the run has started and while it is running and asks for nothing, wait up to this many seconds for a change before answering: default 5, 0 answers at once, at most 300
{"file":".agents/looprails/release.toml","inputs":{"version":"1.4.0"},"wait_seconds":5}

resume_looprail

MCP tool

Continue a cancelled, failed or interrupted run from its checkpoint, in its own run folder.

ArgumentTypeWhat
run_id requiredstringthe run's id, as start_looprail or get_looprail_status gave it
{"run_id":"release-3f9a01c2"}

cancel_looprail

MCP tool

Stop a run: interrupt its process and everything it started, and keep its checkpoint so resume_looprail can continue it.

ArgumentTypeWhat
run_id requiredstringthe run's id, as start_looprail or get_looprail_status gave it
{"run_id":"release-3f9a01c2"}

get_looprail_status

MCP tool

Report a run, or every run the server owns: under Show the user its state, steps table, tokens spent and changes (lines added and removed, files read), with step and run_id the files that step read and edited and the commands it ran (each list capped at 200, with how many it left out), then its pending requests (a failed step's with its full error, its explanation, the end of its output, its log, the agent's reply to an ask and the choices it offers), details such as the last output and last event time, and under Next the call to make next. wait_seconds (5 by default, 0 answers at once, at most 300) waits for a change when nothing needs an answer; use 60 to 120 while a run goes. A progressToken gets progress notifications while it waits.

ArgumentTypeWhat
run_idstringthe run to report; every run the server owns when left out
stepstringwith run_id, a step of the run, such as code or single[0]/review, whose files read and edited and commands run the status lists; no step lists them when left out
wait_secondsintegerwhen the run is running and asks for nothing, wait up to this many seconds for a change before answering: default 5, 0 answers at once, at most 300
{"run_id":"release-3f9a01c2","wait_seconds":120}

provide_looprail_input

MCP tool

Answer a run's pending request: inputs for its input form, action (one of the question's choices, such as retry, skip, stop, feedback or ask for a failed step), text or both for a question (id names the question), or continue for a checkpoint.

ArgumentTypeWhat
run_id requiredstringthe run that waits
idstringthe pending request's id, such as q2; may be left out when only one request of that kind is open
inputsobjectanswers an inputs request: values for the input form's fields
textstringanswers a question with text; with action, a note beside the choice, the feedback a retry runs the step again with or the agent is told, or the question an ask puts to the agent
actionstringanswers a question with one of its choices, such as retry, skip, stop, feedback or ask for a failed step
continuebooleananswers a checkpoint request: true continues from the checkpoint, false starts from the first step
{"run_id":"release-3f9a01c2","id":"q2","action":"skip"}

get_looprail_capacity

MCP tool

Show the active runs, the steps of each kind (agent, shell, mcp, api) running in your home against their kind limits, and per limit key the slots in use and waiting, summed and per run, with each run's own max_parallel.

Takes no arguments.

get_looprail_file_spec

MCP tool

Return the looprail file format, one page at a time. With no page, the index: what a looprail is, a first looprail, and every page with the value of page that returns it and its resource. With page, that page, such as kinds/api or rules/steps, the same text as the resource looprail://spec/<page>; the index is the resource looprail://spec. A page that does not exist is an error that lists the pages.

ArgumentTypeWhat
pagestringthe page to return, such as file, kinds/api or rules/steps; the index, which names every page, when left out
{"page":"kinds/api"}

get_looprail_guide

MCP tool

Return the guide to running, writing, updating, stopping and resuming looprails, the same text as the resource looprail://guide.

Takes no arguments.

get_looprail_migration

MCP tool

Return the migration guides that move a looprail file to the spec this looprail reads. With file, every guide from the spec_version the file declares, in order; it reads only that, so it works on a file that does not load. With from, and to (the spec this looprail reads by default), the guides between those versions. With nothing, the index of guides. Each guide is the resource looprail://spec/migrations/<version>. The answer ends with the call to make next.

ArgumentTypeWhat
filestringa looprail file, absolute or relative to the project folder: returns every guide from the spec_version it declares to the spec this looprail reads
fromstringwithout file, the spec version to move from, such as 0.1.0
tostringwith from, the spec version to move to; the one this looprail reads when left out
{"file":".agents/looprails/release.toml"}

Looprail tools

Every looprail the server can run also has a tool of its own, so an agent can call it without looking it up first. These are the looprails list_looprails lists: those in .agents/looprails of the project and of the home directory (only the home's with --global).

  • Name. looprail_ plus the looprail's name, with every run of characters outside A-Z a-z 0-9 _ . - turned into _. release is looprail_release, and tidy up is looprail_tidy_up.
  • Odd names. A name with none of those characters (!!!), or one that would make a tool name longer than 128 characters, ends in _ and 12 hex digits of a hash of the name.
  • Clashes. The project's file wins over the home's, and within a folder the first file in name order wins. A file that does not load still holds its name, so a broken project file leaves the home file of that name without a tool. The server says so on stderr.
  • Description. The looprail's own description, then a line naming its file and saying the tool is an alias for start_looprail and resume_looprail.
  • Arguments. One per static input, with its type (string, enum as a string with its values, bool, int, float), description, default and bounds, then an optional run_id. A looprail with an input called run_id gets no tool.
  • Schema. It takes either run_id alone, or the inputs without run_id. With the inputs, every input that has no default is required. It uses if, then and else, because some clients, the Anthropic API among them, refuse oneOf, anyOf and allOf at the top of a tool's schema.
  • Without run_id the call is start_looprail with that file and the arguments as inputs. Missing or wrong inputs leave the run awaiting_inputs.
  • With run_id alone, the call is resume_looprail for that run. A run of another looprail is refused, naming that looprail and its tool.

The server checks the looprail folders every two seconds, and before each tools/list and each call to a looprail_ tool. When a file changes, the tools change and the client gets notifications/tools/list_changed. A file that does not load gets no tool, and the server says why on stderr.

States

StateMeaning
awaiting_inputsThe run waits for its inputs. Nothing has run.
runningSteps are running, and nothing waits for an answer.
needs_inputA step asks a person a question, or the run asks whether to continue from a checkpoint.
passedEvery step passed or was skipped.
failedA step failed, the file was not valid, or the run could not start. The last output says why.
cancelledcancel_looprail, or the client closing, stopped it. Its checkpoint is kept.
interruptedIts process stopped before it finished and left a checkpoint. It is never started again on its own.

Resources

URIHolds
looprail://specThe index of the looprail file format, the same text as looprail spec: what a looprail is, a first looprail, and every page with its resource.
looprail://spec/<page>One page of the format, such as looprail://spec/kinds/api, the same text as looprail spec <page>. The server lists one resource per page.
looprail://spec/migrations/<version>The guide that moves a file to a breaking spec version, such as looprail://spec/migrations/1.0.0 once there is one. get_looprail_migration returns the guides a file needs.
looprail://spec/proposals/<NNNN>One spec proposal, an LRP, such as looprail://spec/proposals/0001.
looprail://guideHow to find, run, watch, answer, stop, resume and write a looprail.

Each resource has a tool that returns the same text, because a client may only use tools.

A kind limit is shared by every run in your home. A looprail's limits.<key>.max_parallel belongs to one run, so the summed in_use of a key can pass any one run's max. get_looprail_capacity gives kind_limits, with the steps running in your home against max for each kind, beside active_runs, this server's runs.

Optional layers

A client gets these layers only if it declares them in its capabilities, in initialize or in a request's _meta. The server then declares them back. A client that declares neither gets the same tools and text resources, with the same bytes.

Tasks

A client that declares capabilities.tasks, or the extension io.modelcontextprotocol/tasks, gets each run as an MCP task. The server declares tasks with list and cancel.

A task's taskId is its run's run_id, the one start_looprail returns. No other run ever gets that id, and it stays the same when the run is resumed. Its status comes from the run's state:

Run stateTask status
awaiting_inputs, needs_inputinput_required
runningworking
passedcompleted
failedfailed
cancelledcancelled
interruptedfailed, with _meta."looprail/retryable" true

Every task's _meta carries looprail/state, the run's own state, and looprail/retryable, whether resume_looprail can continue it. statusMessage names the pending requests, the last error or how to resume, or else the state and changes, as in running: +1231 -123, 42 files read. ttl is null, and pollInterval is 2000.

  • tasks/list lists every run the server owns or found.
  • tasks/get gives the task, with the run in _meta."looprail/run": its status, its static inputs and its last 50 events, oldest first.
  • tasks/cancel works like cancel_looprail and keeps the checkpoint. A run that has ended is refused.
  • tasks/result waits until the run ends, then answers what get_looprail_status says, with _meta."io.modelcontextprotocol/related-task".
  • notifications/tasks/status comes once for each state a run enters.

A run still starts with start_looprail or a looprail's tool and is answered with provide_looprail_input. The server does not take task-augmented tools/call.

Apps

A client that declares the extension io.modelcontextprotocol/ui (MCP Apps) gets two more resources beside the text ones. They are HTML apps of MIME type text/html;profile=mcp-app:

URIShows
ui://looprail/runsThe looprails, each with a form for its inputs and Start, and the server's runs, each opening its run view.
ui://looprail/runOne live run: state, tokens, changes (lines added and removed, files read), steps, pending requests with forms to answer them, checkpoint, errors, last events and last output, with Cancel and Resume.

The tools that report runs carry _meta.ui.resourceUri: list_looprails points to the runs app, and start_looprail, resume_looprail, cancel_looprail, get_looprail_status, provide_looprail_input and each looprail's tool point to the run app.

The apps call the same tools, plus one only they see: get_looprail_events (run_id, limit), with _meta.ui.visibility ["app"]. The run view asks for the run every two seconds while it is live. An open app never keeps a run going after the server ends.

The stdio protocol

looprail run --std writes events to stdout and reads replies from stdin, one JSON object per line each way. Stdout carries nothing else: command output, harness stderr and looprail's own messages go to stderr.

A file that fails validation prints its errors on stderr, and stdout gets only {"event":"done","exit":2}. A looprail read from stdin uses up stdin, so no reply can come, and a human step or a failover then fails with stdin is closed.

Answer a question by its id, or by the step's name when no question with that id is waiting. A line that is not a JSON object, or holds none of inputs, continue and answer, gets bad input.

Events

inputs

LoopRail writes it to stdoutEvent

Before anything runs, only when a static input is missing or wrong. An input with no default is required.

{
  "event": "inputs",
  "fields": [
    {
      "description": "A short name for the branch.",
      "min_length": 1,
      "name": "slug",
      "type": "string"
    },
    {
      "default": 2,
      "description": "How many to make.",
      "min": 1,
      "name": "count",
      "type": "int"
    }
  ]
}
FieldTypeWhat
eventstringAlways inputs.
fieldsarrayOne entry per static input still to ask for, in the file's order.
fields.defaultanyThe value an empty answer takes. Absent means the input is required.
fields.descriptionstringWhat the input is for.
fields.maxnumberA number input's upper bound.
fields.max_lengthintegerA string input's longest length.
fields.minnumberA number input's lower bound.
fields.min_lengthintegerA string input's shortest length.
fields.namestringThe input's name.
fields.typestringThe input's type: string, int, float, bool, enum or list.
fields.valuesarray of stringAn enum's allowed values.

error

LoopRail writes it to stdoutEvent

A reply, or an input the command line gave, is wrong, or a reply arrived that nothing is waiting for. error is bad input (with message, and field when it is about one input or continue) or not waiting (with id or step for an answer, or message for inputs or continue).

{
  "error": "bad input",
  "event": "error",
  "field": "slug",
  "message": "\"\" is 0 characters, below min_length 1"
}
FieldTypeWhat
errorstringbad input or not waiting.
eventstringAlways error.
fieldstringThe input the bad input is about, or continue.
idstringThe question id a not waiting answer named.
messagestringWhy a bad input was refused, or which reply was not waited for.
stepstringThe step a not waiting answer named.

checkpoint

LoopRail writes it to stdoutEvent

Before any step, when the run folder holds a checkpoint and neither --continue nor --fresh was passed. Nothing runs until the reply comes.

{
  "dir": "/work/.looprail/runs/change-ab12cd34",
  "event": "checkpoint",
  "finished": [
    "branch"
  ],
  "saved": "2026-11-09T10:00:00Z"
}
FieldTypeWhat
dirstringThe run folder.
eventstringAlways checkpoint.
finishedarray of stringThe steps the checkpoint marks finished.
savedstringWhen the checkpoint was saved, RFC 3339.

step

LoopRail writes it to stdoutEvent

A step, or one item of a for_each step, changed state. finished_at is set only once it ended. tokens.in and tokens.out count the turns that ended; tokens.context is the size of a turn still running, and a step event goes out, status unchanged, each time a harness reports one, and each time what an agent step waits for (waiting) changes, and each time an agent's tool call that changed or read files or ran a command finished, and each time a shell step starts a command. A continued run starts the token count and the changes again. The first step event of a run comes with one for every other step of the file, in the file's order, the pending ones included, so a reader knows all the steps before any runs. A step a checkpoint marks finished is sent once, as passed or skipped, when a continued run starts. A looprail step's steps are named <looprail step>[<item>]/<step>.

{
  "accepted": true,
  "brief": "/w/briefs/check.md",
  "changes": {
    "added": 231,
    "files_edited": 3,
    "files_read": 12,
    "removed": 23
  },
  "event": "step",
  "files": {
    "commands": [
      "go test ./internal/check"
    ],
    "edited": [
      "internal/check/check.go"
    ],
    "read": [
      "go.mod",
      "internal/check/check.go"
    ]
  },
  "finished_at": "2026-11-09T10:03:07Z",
  "input": "brief check.md",
  "item": 2,
  "loops": 1,
  "model": "claude-agent-acp opus",
  "output": "verdict=pass",
  "run_changes": {
    "added": 1231,
    "files_edited": 17,
    "files_read": 42,
    "removed": 123
  },
  "started_at": "2026-11-09T10:00:00Z",
  "status": "passed",
  "step": "check",
  "tokens": {
    "in": 120400,
    "out": 6100
  }
}
FieldTypeWhat
acceptedbooleanSet on a gate: whether it accepted.
briefstringThe absolute path of an agent step's brief.
changesobjectWhat the step's agents changed and read over every loop so far, counted from their finished tool calls, not from git. Absent before they changed or read anything.
changes.addedintegerLines the step's edits added: the lines of a diff's newText outside its common lines with oldText, every line of a new file.
changes.files_readintegerDistinct files the step's read tool calls named.
changes.removedintegerLines the step's edits removed: the lines of a diff's oldText outside its common lines with newText.
errorstringWhy a failed step failed.
eventstringAlways step.
feedbackstringWhat the person who asked for the retry said, in a retry or a feedback answer, absent when they said nothing. The step event of each retry carries its own.
filesobjectWhich files the step's agents read and edited and which commands the step ran, over every loop so far: an agent's execute tool calls, failed ones included, and each command of a shell step's run. Sent when a list changed and when the step's status did, absent otherwise: keep the last one sent. Each list keeps its first 200 entries and counts the rest in its _dropped field.
files.commandsarray of stringThe commands the step ran, in order, repeats included.
files.commands_droppedintegerCommands run past the first 200, not listed. Left out when none.
files.editedarray of stringDistinct files the step's edit tool calls changed, in the order first edited, relative to the step's working directory when inside it.
files.edited_droppedintegerFiles edited past the first 200, not listed. Left out when none.
files.readarray of stringDistinct files the step's read tool calls named, in the order first read, relative to the step's working directory when inside it.
files.read_droppedintegerFiles read past the first 200, not listed. Left out when none.
finished_atstringWhen the step ended, RFC 3339. Absent while it runs.
inputstringOne line on what the step is given.
itemintegerThe for_each item, from 0. Absent for a step that does not run per item.
loopsintegerHow many times the step has run, counting the one in flight.
modelstringThe harness and model of an agent step.
outcomestringlimited for a usage limit, rejected for a gate whose rejection went ahead. Absent otherwise.
outputstringOne line on what the step produced.
retryintegerWhich retry of its loop the step runs, after a person answered its failure with the action retry or feedback: 1 for the first. Absent before any retry. Retries do not count in loops.
run_changesobjectThe whole run's changes so far, those of its looprail steps included, on every step event once the run's agents changed or read anything. Each count only grows.
run_changes.addedintegerLines the run's edits added so far.
run_changes.files_readintegerDistinct files the run's agents read so far, each counted once whichever step read it.
run_changes.removedintegerLines the run's edits removed so far.
sessionstringWhy the step's named agent got a new session in place of the live one its lifetime shares: the harness exited, or the step's cwd, env or MCP servers differ from the live session's. Absent when the step reuses the live session or starts the first.
started_atstringWhen the step started, RFC 3339.
statusstringThe step's status: pending, running, passed, failed or skipped.
stepstringThe step's name, or <looprail step>[<item>]/<step> for a step of a looprail step.
tokensobjectWhat the step's agents spent over every loop so far.
tokens.contextintegerThe context size of a turn still running.
tokens.inintegerInput tokens of the turns that ended, cached tokens included.
tokens.outintegerOutput tokens of the turns that ended.
waitingstringWhat a running agent step waits for once its agent's turn ended, such as 2 background tasks: looprail-dev test affected, sleep 60. Absent when it waits for nothing, and on a step that ended.

question

LoopRail writes it to stdoutEvent

A human step, or a failover, asks a person. id is q1, q2, ... in the order the run asks, unique within the run. A failover's question carries failure and the choices retry, skip and stop, or skip and stop once the step spent its max_retries, with feedback (while retries are left) and ask after them when a failed gate's on_fail target, or the gate itself, names an agent whose session is live; a human step's carries the choices it declares. An answer to a failover that names no offered action is refused and the question asked again. A client that reads neither still gets an ask it can answer with text: a failover's ends in Continue, or stop?

{
  "ask": "Step ci failed: run[0] (sh ci.sh) exited 1\nFAIL TestLogin\nlog: /w/.looprail/runs/x/logs/0001/ci~1. Continue, or stop?",
  "choices": [
    "retry",
    "skip",
    "stop",
    "feedback",
    "ask"
  ],
  "event": "question",
  "failure": {
    "error": "run[0] (sh ci.sh) exited 1",
    "log": "/w/.looprail/runs/x/logs/0001/ci~1",
    "output": "FAIL TestLogin",
    "reply": "The login fixture is missing from testdata.",
    "summary": "TestLogin fails"
  },
  "id": "q3",
  "step": "ci"
}
FieldTypeWhat
askstringThe question, as the step asked it.
choicesarray of stringThe actions an answer may name: retry, skip and stop for a failure (skip and stop alone once the step spent its max_retries), followed by feedback (while retries are left) and ask when the failed step is a gate and the named agent of its on_fail target, or its own, has a live session, or a human step's declared choices. Absent when the question offers none.
eventstringAlways question.
failureobjectSet when a step failed and asks whether to go on.
failure.errorstringThe step's error, without the output tail.
failure.logstringThe absolute path of the failed step run's log folder, logs/<session>/<step>~<loop>[~<item>]/, whose records hold the failed command's whole output, the records of a failed api or mcp call, or the failed agent's thoughts, messages and tool calls.
failure.outputstringThe end of the failed command's output: its last 80 lines, at most about 8 KB. Absent when the failure was not a command's.
failure.replystringWhat the agent's live session answered the last ask. The question is asked again with it after each ask. Absent before any.
failure.session_errorstringWhy the last ask or feedback to the agent's live session, or the fix that runs before a retry with feedback of a step that is not an agent step, failed or timed out. The question is asked again with it, and the step did not run again. Absent when the last session worked.
failure.summarystringAt most four sentences, written in the live session of an agent that saw the work, on what failed and the likely cause; a fixed sentence for a usage limit; or could not generate summary when that session did not answer in 10 seconds. Absent when no live agent session saw the work.
idstringThe question's id, q1, q2, ... in the order the run asks.
itemintegerThe for_each item, when the step runs per item.
stepstringThe step that asks, named as in a step event.

limits

LoopRail writes it to stdoutEvent

How many units hold a slot of each limit key, and how many wait for one. At most once every 250 ms, and only when the numbers changed; the last numbers always go out before done.

{
  "event": "limits",
  "limits": {
    "agent.claude-agent-acp": {
      "in_use": 2,
      "max": 2,
      "waiting": 1
    },
    "shell": {
      "in_use": 1
    }
  }
}
FieldTypeWhat
eventstringAlways limits.
limitsobjectOne entry per limit key in use or capped. The key is the limit's name, such as shell or agent.claude-agent-acp.
limits.in_useintegerHow many units hold a slot of the key.
limits.maxintegerThe cap, from the file or --limit. Absent when the key has no cap.
limits.waitingintegerHow many units wait for a slot. Present only when the key has a cap.

live

LoopRail writes it to stdoutEvent

A line of an agent's thinking, or a tool call of an agent, while its step runs. Not part of any step event, and not kept: a reader that wants a trail shows the last few. A thought goes out once its line is complete, at most 300 characters.

{
  "event": "live",
  "kind": "tool",
  "step": "code",
  "text": "Read main.go"
}
FieldTypeWhat
eventstringAlways live.
itemintegerThe item of a for_each step the line comes from. Absent for any other step.
kindstringthought for a line of thinking, tool for a tool call.
stepstringThe step the line comes from, named as in step events.
textstringThe line.

done

LoopRail writes it to stdoutEvent

Always the last line. exit is the run's exit code: 0 passed, 1 a step failed, 2 the invocation or the file was wrong.

{
  "changes": {
    "added": 1231,
    "files_edited": 17,
    "files_read": 42,
    "removed": 123
  },
  "event": "done",
  "exit": 0
}
FieldTypeWhat
changesobjectWhat the whole run's agents changed and read, those of its looprail steps included, as the last step event's run_changes. Absent when they changed and read nothing.
changes.addedintegerLines the run's edits added.
changes.files_editedintegerDistinct files the run's agents edited. Left out when none.
changes.files_readintegerDistinct files the run's agents read.
changes.removedintegerLines the run's edits removed.
eventstringAlways done.
exitintegerThe run's exit code.

Replies

inputs

you write it to stdinReply

Answers an inputs event. Merged over the inputs the command line gave. Each input still wrong gets a bad input error, and the run waits again.

{
  "inputs": {
    "slug": "fix-login"
  }
}
FieldTypeWhat
inputsobjectValues for the inputs the inputs event asked for, by name.

continue

you write it to stdinReply

Answers a checkpoint event. Anything other than true or false gets bad input with field continue.

{
  "continue": true
}
FieldTypeWhat
continuebooleanTrue continues from the checkpoint. False starts from the first step.

answer

you write it to stdinReply

Answers a question, with action, text or both. Answer by the question's id: answer is a question id first, and a step name only when no waiting question has that id, so a step named like an id, such as q2, is answered by name only while no question q2 waits. The step name is kept for older producers. For a for_each step, answer each question by its id. An action the question does not offer gets bad input with field action, and the question still waits. An answer with text alone means what it always has: stop stops, and anything else continues past a failure.

{
  "action": "feedback",
  "answer": "q3",
  "text": "The login fixture is in testdata; use it."
}
FieldTypeWhat
actionstringOne of the question's choices. For a failure, retry runs the step again with text as the person's feedback (a step that is not an agent step first has the agent it needs fix it in its live session, when text is set), skip continues past it, stop ends the run, feedback tells the agent's live session text as what a person who reviewed the failure says and runs the gate again, spending a retry, and ask puts text, or why it failed when text is empty, to that session and asks again with its reply, spending none. For a human step it becomes the step's answer output.
answerstringThe question's id, or, for older producers, a step name when no question with that id is waiting.
textstringThe answer as text, required when action is left out. Alone, it becomes a human step's answer output, and stop ends the run; with action, it is a note beside the choice, with retry the feedback the step runs again with, with feedback what the agent is told, and with ask the question the agent answers. A failover answer with text alone is refused and asked again, unless the text is stop.

looprail spec prints the looprail file format. This page is only the line protocol.

Generated from the code. Do not edit this file.