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
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.
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.
| Harness | Project config | Global config | Skills 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/ |
| goose | none | ~/.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
| Command | What it does |
/looprail | Lists 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.
| Term | Means |
| Gate | A step that passes or rejects the work. |
| Harness | The agent program looprail starts, such as Claude Code or Codex. |
| ACP | Agent Client Protocol, how looprail talks to a harness. |
| MCP | Model Context Protocol, how an agent calls outside tools. |
| Checkpoint | A 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.
| Mode | Command | Who answers | Use it for |
| Terminal | looprail run tidy.toml | You, under a live list of steps. | Running a looprail by hand and watching it. |
| Browser | looprail run --web tidy.toml | You, on the page it opens. | Running by hand with the graph in view, or with no terminal. |
| Program | looprail run --std tidy.toml | The program, in JSON lines. | A program that drives runs. |
| Agent | looprail mcp | The 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 page | What it is |
| Questions | At the top of every view: missing inputs, questions from steps, and whether to continue from a checkpoint. Several can be open at once. |
| Graph | The opening view, with Follow live on: the steps, a searchable list, and each step's output from its log records, files, tokens and attempts. |
| Overview | Open questions first, then the work grouped by top looprail step and by state. |
| Failure modal | The error, the summary, and a button per choice. Click a failed box, or Answer the failure, to open it. |
| Keys | On 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:
| Parameter | Meaning |
q | Text found in the record's text, whatever its case. |
step | The step, or anything inside it. |
item, loop | A number: the records whose item or loop is it. |
source, kind | One value or several split by commas. A leading ! makes it every record but these, as kind=!step,stderr. |
limit | 1 to 1000, 100 by default. |
before, after, around | At 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. |
count | 1 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 page | What it is |
| Questions | At the top of both views: the inputs form, a step's question, and whether to continue from a checkpoint. |
| Line | The 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. |
| Trail | A 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 keys | On 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. |
| Graph | Each step's state on its shape, a box per for_each item, and the step list. |
| Step detail | A step's output from its log records, outputs, tokens, files and attempts. |
| Failure modal | The error, the summary, and a button per choice. |
| Theme | The 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.
| Answer | Send | In 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 stop | Its 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.
| Form | Changes |
--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=value | One 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.
| Kinds | At once |
agent, agent-gate | 30 |
shell, shell-gate | 10 per CPU |
mcp | 50 |
api, decision-model | 50 |
- 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.
| Variable | Holds |
LOOPRAIL_MODELS | A comma-separated list of the only models agent steps may use. Unset, every model is allowed. |
LOOPRAIL_MCP_SERVERS | A 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
| Path | Holds |
state.json | The 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.json | What 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>/:
| File | Holds |
prompt.md, reply.md | What the agent was sent and what it answered. |
usage.json | The tokens it spent. |
failure-summary.md | The 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.
| Key | Holds |
v | The format version, 1. |
seq | The record's place in the run folder, rising. |
at | When it was written, in UTC. |
session | Which start of the run wrote it: 1, 2, … |
source | Who it comes from: looprail, agent, harness, shell, api, mcp or human. |
kind | What it is, from the next table. |
step | The step's name, "" for the run itself. |
loop | Which loop of the step. |
item | The for_each item, or null. |
block | Ties together the records of one thought, message, call or failed output. |
text | The readable line: what a front end shows and search matches. |
data | The kind's extra fields, or null. |
| Kind | Is |
step | A step event from looprail: its status, tokens and changes. |
question, answer | What looprail asked, and what a human answered. |
thought, message | A piece of an agent's thinking or message. |
call, result | A call starting, and ending: an agent's tool, a shell command, an api request or an mcp tool. |
output | A piece of the output of a failed call. |
file | A path an agent read or edited. |
task | An agent's background task update. |
stderr | A 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 run | What it does |
--continue | Skips 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 --continue | Continues even when the looprail, a brief or the inputs differ, and prints what differed. |
--redo <step>, with --continue | Runs that step, and every step that needs it, again. |
--fresh | Starts 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.
| Key | Does |
/, ? | Search forward or back as you type. Enter keeps the match, Esc goes back. |
n, N | Repeat the search, wrapping around the list. |
f | Cycles the state filter: all, unfinished, passed, failed, resumable. |
s, S | Cycles the sort (started, looprail, state, run), or flips its direction. |
u | Rereads 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.
| Call | Does |
status | Prints the step list from state.json. |
status --json | Prints the record and the checkpoint. |
status --watch | Follows the run from any terminal, for a harness such as Zed that shows no progress. It prints the log records too. |
status --web | Serves the browser page for a run started elsewhere, such as through looprail mcp. |
status --web2 | Serves 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.
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
| Exit | run | validate | doctor |
| 0 | Every step passed or was skipped. | The file and every file it runs are valid. | Every harness and model checked out. |
| 1 | A step failed and the file sent it nowhere else. | | A harness or model failed. |
| 2 | The 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. |
| Exit | mcp | install | spec |
| 0 | Stdin ended. | Every file was written or already right. | Printed. |
| 1 | The session failed. | A file could not be merged. | It could not print. |
| 2 | The 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.
| Flags | What it does |
| none | Writes looprail-<name>-*.html to the temp dir, prints its path and opens it. |
--raw | Prints the page to stdout. Writes and opens nothing. |
--out <file> | Writes the page to the file. Opens nothing. |
--v2 | Draws 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.
| Call | Prints |
spec | The index, which says what a looprail is and names every page. |
spec <page> | That page, such as kinds/api. |
spec --all | Every page as one document. |
spec --json | The 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.
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.
Pages
| To read | Command | Over MCP |
| This index | looprail spec | get_looprail_file_spec, or the resource looprail://spec |
| One page | looprail spec <page>, as looprail spec kinds/api | get_looprail_file_spec with page, or the resource in the page's row |
| All pages as one document | looprail spec --all | |
| Page | page | Resource | What it holds |
| The file | file | looprail://spec/file | The top level of a looprail file, its [metadata] table and spec versions, its [config] table, its JSON form, and how errors name fields. |
| Inputs | inputs | looprail://spec/inputs | The static inputs a caller passes, and the derived inputs worked out from them. |
| Types | types | looprail://spec/types | The types of inputs, outputs and list items, their bounds and their descriptions. |
| Steps | steps | looprail://spec/steps | The fields every step shares, needs, and the kinds at a glance. |
[agent steps](#agent-steps) | kinds/agent | looprail://spec/kinds/agent | Starts 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/shell | looprail://spec/kinds/shell | Runs run, each command through sh -c. |
[agent-gate steps](#agent-gate-steps) | kinds/agent-gate | looprail://spec/kinds/agent-gate | An agent that judges and changes nothing. |
[shell-gate steps](#shell-gate-steps) | kinds/shell-gate | looprail://spec/kinds/shell-gate | Runs 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-model | looprail://spec/kinds/decision-model | Asks the decision model that decision-model names the questions about state. |
[human steps](#human-steps) | kinds/human | looprail://spec/kinds/human | Asks a person ask, offering choices when it has them. |
[api steps](#api-steps) | kinds/api | looprail://spec/kinds/api | Sends one HTTP request to url, with method, headers and body. |
[mcp steps](#mcp-steps) | kinds/mcp | looprail://spec/kinds/mcp | Calls tool on an MCP server, reached at url or started with command, with arguments. |
[looprail steps](#looprail-steps) | kinds/looprail | looprail://spec/kinds/looprail | 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. |
| Agents | agents | looprail://spec/agents | Inline agents, named agents, llm rows and harnesses. |
| Briefs | briefs | looprail://spec/briefs | The file an agent step's prompt comes from, and how a changed brief stops a run from continuing. |
| Outputs | outputs | looprail://spec/outputs | What a step sets for later steps to read, and how each kind sets it. |
| References | references | looprail://spec/references | References in templates, when and for_each. |
| Shell quoting | shell-quoting | looprail://spec/shell-quoting | How a reference becomes one word of a shell command, and the forms that fail. |
| Failure | failure | looprail://spec/failure | What happens when a step fails: on_fail, failover, retries, and gates that send a rejection ahead. |
| Limits | limits | looprail://spec/limits | How many steps of each sort run at once. |
| Load rules | rules | looprail://spec/rules | Every load rule, the file most of their examples build on, and what the schema can't check. |
| Rules for the file | rules/file | looprail://spec/rules/file | Reading and decoding the file: TOML and JSON, the top level, unknown fields and whole numbers. |
| Rules for inputs | rules/inputs | looprail://spec/rules/inputs | Derived inputs, and the defaults of static ones. |
| Rules for types | rules/types | looprail://spec/rules/types | The declarations of inputs, outputs and item fields: their types, bounds and defaults. |
| Rules for steps | rules/steps | looprail://spec/rules/steps | A step's name, kind and description, and the fields each kind needs, may set and may not. |
| Rules for named agents | rules/agents | looprail://spec/rules/agents | Named agents, their llm rows, harnesses, and the agent a step names. |
| Rules for decision models | rules/decision-models | looprail://spec/rules/decision-models | Decision models, their llm rows, and the decision model a step names. |
| Rules for needs and loops | rules/loops | looprail://spec/rules/loops | needs, on_fail, max_loops and max_retries. |
| Rules for templates | rules/templates | looprail://spec/rules/templates | The form of a {{ }} template and the expression it holds. |
| Rules for references | rules/references | looprail://spec/rules/references | What a reference may name, and where it may appear. |
[Rules for when](#rules-for-when) | rules/when | looprail://spec/rules/when | The expression of when and the types it compares. |
[Rules for for_each](#rules-for-for_each) | rules/for-each | looprail://spec/rules/for-each | for_each, each and the fields of an item. |
| Rules for shell quoting | rules/shell | looprail://spec/rules/shell | Where a reference may sit in a shell command. |
| Rules for looprail steps | rules/looprail-steps | looprail://spec/rules/looprail-steps | Looprail steps, the files they run, and their overrides. |
| Rules for limits | rules/limits | looprail://spec/rules/limits | The [limits] table. |
| Rules for briefs | rules/briefs | looprail://spec/rules/briefs | Reading a step's brief. |
| Proposals | proposals | looprail://spec/proposals | Every proposal to change the format, an LRP, with its status, and the migration guides of the breaking versions. |
| LRP-0000: Spec proposals | proposals/0000 | looprail://spec/proposals/0000 | An implemented clarification proposal, since 0.1.0. |
| LRP-0001: Spec versioning | proposals/0001 | looprail://spec/proposals/0001 | An implemented feature proposal, since 0.1.0. |
| LRP-0002: The file format | proposals/0002 | looprail://spec/proposals/0002 | An implemented feature proposal, since 0.1.0. |
| LRP-0003: Config | proposals/0003 | looprail://spec/proposals/0003 | An implemented feature proposal, since 0.1.0. |
| LRP-0004: Inputs | proposals/0004 | looprail://spec/proposals/0004 | An implemented feature proposal, since 0.1.0. |
| LRP-0005: Types | proposals/0005 | looprail://spec/proposals/0005 | An implemented feature proposal, since 0.1.0. |
| LRP-0006: Steps | proposals/0006 | looprail://spec/proposals/0006 | An implemented feature proposal, since 0.1.0. |
| LRP-0007: Agent steps | proposals/0007 | looprail://spec/proposals/0007 | An implemented feature proposal, since 0.1.0. |
| LRP-0008: Shell steps | proposals/0008 | looprail://spec/proposals/0008 | An implemented feature proposal, since 0.1.0. |
| LRP-0009: Agent-gate steps | proposals/0009 | looprail://spec/proposals/0009 | An implemented feature proposal, since 0.1.0. |
| LRP-0010: Shell-gate steps | proposals/0010 | looprail://spec/proposals/0010 | An implemented feature proposal, since 0.1.0. |
| LRP-0011: Decision-model steps | proposals/0011 | looprail://spec/proposals/0011 | An implemented feature proposal, since 0.1.0. |
| LRP-0012: Human steps | proposals/0012 | looprail://spec/proposals/0012 | An implemented feature proposal, since 0.1.0. |
| LRP-0013: API steps | proposals/0013 | looprail://spec/proposals/0013 | An implemented feature proposal, since 0.1.0. |
| LRP-0014: MCP steps | proposals/0014 | looprail://spec/proposals/0014 | An implemented feature proposal, since 0.1.0. |
| LRP-0015: Looprail steps | proposals/0015 | looprail://spec/proposals/0015 | An implemented feature proposal, since 0.1.0. |
| LRP-0016: Agents | proposals/0016 | looprail://spec/proposals/0016 | An implemented feature proposal, since 0.1.0. |
| LRP-0017: Outputs | proposals/0017 | looprail://spec/proposals/0017 | An implemented feature proposal, since 0.1.0. |
| LRP-0018: Templates and references | proposals/0018 | looprail://spec/proposals/0018 | An implemented feature proposal, since 0.1.0. |
| LRP-0019: Conditional steps | proposals/0019 | looprail://spec/proposals/0019 | An implemented feature proposal, since 0.1.0. |
| LRP-0020: For each | proposals/0020 | looprail://spec/proposals/0020 | An implemented feature proposal, since 0.1.0. |
| LRP-0021: Shell quoting | proposals/0021 | looprail://spec/proposals/0021 | An implemented feature proposal, since 0.1.0. |
| LRP-0022: Failure | proposals/0022 | looprail://spec/proposals/0022 | An implemented feature proposal, since 0.1.0. |
| LRP-0023: Limits | proposals/0023 | looprail://spec/proposals/0023 | An implemented feature proposal, since 0.1.0. |
| Changelog | changelog | looprail://spec/changelog | The 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.
A looprail file, as TOML decodes it or as JSON writes it.
| Field | Type | Required | Since | Description |
metadata | metadata | yes | 0.1.0 | The file's spec version, name and description. See Metadata. |
inputs | inputs | | 0.1.0 | The inputs the looprail takes. |
agents | table of <name> to named agent | | 0.1.0 | Named 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 }. |
harnesses | table of <name> to harness | | 0.1.0 | Extra 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-models | table of <name> to decision model | | 0.1.0 | Decision 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 }. |
step | table of <name> to step | yes | 0.1.0 | The 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 }. |
limits | limits | | 0.1.0 | How many steps of each sort run at once. A key nobody sets has no cap. See Limits. |
config | config | | 0.1.0 | Settings for the whole file. See Config. |
[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.
Written as [metadata]. What the file is: the spec version it is written to, its name and its description.
| Field | Type | Required | Since | Description |
spec_version | string | yes | 0.1.0 | The 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. |
name | string | yes | 0.1.0 | The looprail's name. A looprail read from stdin names its run folder with it. Must not be blank. |
description | string | | 0.1.0 | One 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"]
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] holds settings for the whole file.
- Without it, every setting is off.
- An unknown key fails, naming it.
Written as [config].
| Field | Type | Required | Since | Description |
enable_nix | true or false | | 0.1.0 | Runs 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"]
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.
| Message | Cause |
Missing Nix installation but enable_nix is on | The 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.nix | No 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 shell | The 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.
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.
- 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.
Written as [inputs].
| Field | Type | Required | Since | Description |
static | table of <name> to static input | | 0.1.0 | The inputs a caller passes, in the order the file writes them, which is the order a person is asked for them. |
derived | table of <name> to string | | 0.1.0 | Inputs 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. |
Written as inputs.static.<name>.
| Field | Type | Required | Since | Description |
type | string | yes | 0.1.0 | The input's type. See Types. Must be one of string, enum, bool, int or float. |
description | string | yes | 0.1.0 | One 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. |
default | string, number, or true or false | | 0.1.0 | The value used when the caller gives none. It must check out against the declaration. An input without one is required. |
values | list of strings | | 0.1.0 | An enum's values. An enum needs them, and only an enum has them. Must not be empty. |
min_length | whole number | | 0.1.0 | A string's least length, in characters. At least 0. |
max_length | whole number | | 0.1.0 | A string's greatest length, in characters. Not below min_length. |
min | number | | 0.1.0 | A number's lower bound. An int's bounds are whole numbers. |
max | number | | 0.1.0 | A number's upper bound. Not below min. |
items | - | not allowed | 0.1.0 | Inputs 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.
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.
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.
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.
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.
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.
| Field | Type | Required | Since | Description |
name | string | yes | 0.1.0 | The 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. |
Written as [decision-models.<name>].
| Field | Type | Required | Since | Description |
llm | list of decision model llm | yes | 0.1.0 | The models the decision model may call, in order. Must not be empty. |
Written as [[decision-models.<name>.llm]].
| Field | Type | Required | Since | Description |
provider | string | yes | 0.1.0 | Who runs the model. Must be jev. |
model | string | | 0.1.0 | The model, as the provider names it. Unset, it is jev-latest. |
Each question is written [step.<name>.questions.<question>]. Its outputs depend on its type:
| Type | Outputs |
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.
Written as [step.<name>.questions.<question>].
| Field | Type | Required | Since | Description |
type | string | yes | 0.1.0 | choice 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. |
instructions | string | | 0.1.0 | What the decision model is told about the question. |
criteria | table of <value> to string | | 0.1.0 | A choice's values, each with what it means. A choice needs criteria, and only a choice has them. Must not be empty. |
levels | list of strings | | 0.1.0 | A score's levels, lowest first. A score needs them, and only a score has them. At most 10 entries. At least 2 entries. |
probabilities | true or false | | 0.1.0 | Also 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.
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.
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.
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.
- 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.
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.
Written as [[step.<name>.override]], after its [[step.<name>]].
| Field | Type | Required | Since | Description |
match | table of <field> to any value | yes | 0.1.0 | The 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. |
agent | agent | yes | 0.1.0 | The 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.
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>].
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.
| Field | Type | Required | Since | Description |
name | string | | 0.1.0 | The 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. |
provider | string | | 0.1.0 | An 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. |
command | list of strings | | 0.1.0 | An 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. |
model | string | | 0.1.0 | The 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 allowed | 0.1.0 | A 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. |
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.
lifetime | One session for |
step | one step, and the on_fail retries that send the run back to it |
item | every step that names it in one for_each item, nested looprails included |
run | every step that names it in the run |
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.
- 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.
--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.
With no command, these are called through their chat completions API:
| Provider | Default endpoint | Default key variable |
ollama | http://127.0.0.1:11434/v1 | none |
openai | https://api.openai.com/v1 | OPENAI_API_KEY |
openrouter | https://openrouter.ai/api/v1 | OPENROUTER_API_KEY |
commandcode | https://api.commandcode.ai/provider | COMMAND_CODE_API_KEY |
openai-compatible | none: set endpoint | none |
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.
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.
Written as [agents.<name>].
| Field | Type | Required | Since | Description |
lifetime | string | yes | 0.1.0 | How 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. |
llm | list of llm | yes | 0.1.0 | The 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. |
Written as [[agents.<name>.llm]].
| Field | Type | Required | Since | Description |
provider | string | | 0.1.0 | Who 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. |
model | string | | 0.1.0 | The model, as the provider names it; for goinfer, the path to a .gguf file, absolute or from the step's cwd. |
endpoint | string | | 0.1.0 | The 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_env | string | | 0.1.0 | The 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. |
command | list of strings | | 0.1.0 | The ACP harness and its arguments, in place of the provider's own. Must not be empty. Each entry: must not be empty. |
config | table of <option> to any value | | 0.1.0 | Options 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. |
Written as [harnesses.<name>].
| Field | Type | Required | Since | Description |
command | list of strings | yes | 0.1.0 | The 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.
Outputs
Later steps read a step's outputs as {{ steps.<name>.outputs.<output> }}.
- 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.
| Kind | Outputs |
| human | answer, a string |
| agent-gate | verdict, a string, besides those it declares |
| api | status_code, an int, and body, a string, besides those it declares: see [api steps](#api-steps) |
| mcp | text, a string, besides those it declares: see [mcp steps](#mcp-steps) |
| decision-model | one 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.
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.
Written as [step.<name>.outputs], one key per output.
| Field | Type | Required | Since | Description |
type | string | yes | 0.1.0 | The output's type. See Types. Must be one of string, enum, bool, int, float or list. |
description | string | yes | 0.1.0 | One 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 allowed | 0.1.0 | Outputs have no default. Setting it fails with an output has no default. |
values | list of strings | | 0.1.0 | An enum's values. An enum needs them, and only an enum has them. Must not be empty. |
min_length | whole number | | 0.1.0 | A string's least length, in characters. At least 0. |
max_length | whole number | | 0.1.0 | A string's greatest length, in characters. Not below min_length. |
min | number | | 0.1.0 | A number's lower bound. An int's bounds are whole numbers. |
max | number | | 0.1.0 | A number's upper bound. Not below min. |
items | table of <field> to item field | | 0.1.0 | The 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. |
Written as items = { <field> = { ... } }, on a list.
| Field | Type | Required | Since | Description |
type | string | yes | 0.1.0 | The field's type. See Types. Must be one of string, enum, bool, int, float or list. |
description | string | | 0.1.0 | What the field holds. Unlike an input's or an output's, it may be left out. |
default | - | not allowed | 0.1.0 | Item fields have no default. Setting it fails with an item field has no default. |
values | list of strings | | 0.1.0 | An enum's values. An enum needs them, and only an enum has them. Must not be empty. |
min_length | whole number | | 0.1.0 | A string's least length, in characters. At least 0. |
max_length | whole number | | 0.1.0 | A string's greatest length, in characters. Not below min_length. |
min | number | | 0.1.0 | A number's lower bound. An int's bounds are whole numbers. |
max | number | | 0.1.0 | A number's upper bound. Not below min. |
items | table of <field> to item field | | 0.1.0 | The 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.
| Reference | Is |
{{ 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 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 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 }}.
- 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.
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.
- 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.
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?.
- 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.
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.
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.
- 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.
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.
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.
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 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 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 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.
LRP-0000: Spec proposals
| Field | Value |
| LRP | 0000 |
| Author | Ariel Sosnovsky |
| Status | implemented |
| Type | clarification |
| Since | 0.1.0 |
| Source | looprail/internal/spec/lrp/proposals/0000-spec-proposals.md |
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.
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:
| Key | Holds |
lrp | Its number, which the file's name starts with, four digits wide. |
title | A few words on what it changes. |
author | Who wrote it. |
status | draft, accepted, implemented, rejected or superseded. |
type | feature (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). |
since | The spec version that implemented it. Required once it is implemented. |
supersedes | The numbers of the LRPs it replaces, separated by commas. |
migration | The 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.
- 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.
- 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.
- A new or changed field or kind needs an entry in
spec.SinceTable, keyed by its place (KindPlace(kind) for a kind).
- The entry names the LRP and the spec version. Once the LRP is implemented, the version must match the LRP's
since.
- The implementing pull request adds these entries along with the
spec.Version bump.
- 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.
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.
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:
---
This LRP changes no file. It sets out how every later change is made.
LRP-0001: Spec versioning
| Field | Value |
| LRP | 0001 |
| Author | Ariel Sosnovsky |
| Status | implemented |
| Type | feature |
| Since | 0.1.0 |
| Source | looprail/internal/spec/lrp/proposals/0001-spec-versioning.md |
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.
A file declares its spec version in a [metadata] table, which also holds what the file is:
| Field | Holds |
spec_version | The spec version the file is written for. Required. |
name | The looprail's name. Required. |
description | One 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.
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.
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.
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.
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"]
0.1.0 is the first version of the spec, so there are no earlier files to move over.
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.
| Kind | Covers | Default limit |
agent | agent and agent-gate steps | 30 |
shell | shell and shell-gate steps | 10 per CPU |
mcp | mcp steps | 50 |
api | api and decision-model steps | 50 |
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:
| Kind | Carries | Answer with |
inputs | the form's schema | inputs |
question | the question id | text |
checkpoint | | continue, 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.
States
| State | Meaning |
awaiting_inputs | The run waits for its inputs. Nothing has run. |
running | Steps are running, and nothing waits for an answer. |
needs_input | A step asks a person a question, or the run asks whether to continue from a checkpoint. |
passed | Every step passed or was skipped. |
failed | A step failed, the file was not valid, or the run could not start. The last output says why. |
cancelled | cancel_looprail, or the client closing, stopped it. Its checkpoint is kept. |
interrupted | Its process stopped before it finished and left a checkpoint. It is never started again on its own. |
Resources
| URI | Holds |
looprail://spec | The 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://guide | How 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 state | Task status |
awaiting_inputs, needs_input | input_required |
running | working |
passed | completed |
failed | failed |
cancelled | cancelled |
interrupted | failed, 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:
| URI | Shows |
ui://looprail/runs | The looprails, each with a form for its inputs and Start, and the server's runs, each opening its run view. |
ui://looprail/run | One 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
inputsBefore anything runs, only when a static input is missing or wrong.
errorA reply, or an input the command line gave, is wrong, or a reply arrived that nothing is waiting for.
checkpointBefore any step, when the run folder holds a checkpoint and neither --continue nor --fresh was passed.
stepA step, or one item of a for_each step, changed state.
questionA human step, or a failover, asks a person.
limitsHow many units hold a slot of each limit key, and how many wait for one.
liveA line of an agent's thinking, or a tool call of an agent, while its step runs.
doneAlways the last line.
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"
}
]
}
| Field | Type | What |
event | string | Always inputs. |
fields | array | One entry per static input still to ask for, in the file's order. |
fields.default | any | The value an empty answer takes. Absent means the input is required. |
fields.description | string | What the input is for. |
fields.max | number | A number input's upper bound. |
fields.max_length | integer | A string input's longest length. |
fields.min | number | A number input's lower bound. |
fields.min_length | integer | A string input's shortest length. |
fields.name | string | The input's name. |
fields.type | string | The input's type: string, int, float, bool, enum or list. |
fields.values | array of string | An 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"
}
| Field | Type | What |
error | string | bad input or not waiting. |
event | string | Always error. |
field | string | The input the bad input is about, or continue. |
id | string | The question id a not waiting answer named. |
message | string | Why a bad input was refused, or which reply was not waited for. |
step | string | The 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"
}
| Field | Type | What |
dir | string | The run folder. |
event | string | Always checkpoint. |
finished | array of string | The steps the checkpoint marks finished. |
saved | string | When 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
}
}
| Field | Type | What |
accepted | boolean | Set on a gate: whether it accepted. |
brief | string | The absolute path of an agent step's brief. |
changes | object | What 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.added | integer | Lines 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_read | integer | Distinct files the step's read tool calls named. |
changes.removed | integer | Lines the step's edits removed: the lines of a diff's oldText outside its common lines with newText. |
error | string | Why a failed step failed. |
event | string | Always step. |
feedback | string | What 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. |
files | object | Which 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.commands | array of string | The commands the step ran, in order, repeats included. |
files.commands_dropped | integer | Commands run past the first 200, not listed. Left out when none. |
files.edited | array of string | Distinct 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_dropped | integer | Files edited past the first 200, not listed. Left out when none. |
files.read | array of string | Distinct 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_dropped | integer | Files read past the first 200, not listed. Left out when none. |
finished_at | string | When the step ended, RFC 3339. Absent while it runs. |
input | string | One line on what the step is given. |
item | integer | The for_each item, from 0. Absent for a step that does not run per item. |
loops | integer | How many times the step has run, counting the one in flight. |
model | string | The harness and model of an agent step. |
outcome | string | limited for a usage limit, rejected for a gate whose rejection went ahead. Absent otherwise. |
output | string | One line on what the step produced. |
retry | integer | Which 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_changes | object | The 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.added | integer | Lines the run's edits added so far. |
run_changes.files_read | integer | Distinct files the run's agents read so far, each counted once whichever step read it. |
run_changes.removed | integer | Lines the run's edits removed so far. |
session | string | Why 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_at | string | When the step started, RFC 3339. |
status | string | The step's status: pending, running, passed, failed or skipped. |
step | string | The step's name, or <looprail step>[<item>]/<step> for a step of a looprail step. |
tokens | object | What the step's agents spent over every loop so far. |
tokens.context | integer | The context size of a turn still running. |
tokens.in | integer | Input tokens of the turns that ended, cached tokens included. |
tokens.out | integer | Output tokens of the turns that ended. |
waiting | string | What 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"
}
| Field | Type | What |
ask | string | The question, as the step asked it. |
choices | array of string | The 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. |
event | string | Always question. |
failure | object | Set when a step failed and asks whether to go on. |
failure.error | string | The step's error, without the output tail. |
failure.log | string | The 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.output | string | The 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.reply | string | What the agent's live session answered the last ask. The question is asked again with it after each ask. Absent before any. |
failure.session_error | string | Why 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.summary | string | At 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. |
id | string | The question's id, q1, q2, ... in the order the run asks. |
item | integer | The for_each item, when the step runs per item. |
step | string | The 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
}
}
}
| Field | Type | What |
event | string | Always limits. |
limits | object | One 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_use | integer | How many units hold a slot of the key. |
limits.max | integer | The cap, from the file or --limit. Absent when the key has no cap. |
limits.waiting | integer | How 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"
}
| Field | Type | What |
event | string | Always live. |
item | integer | The item of a for_each step the line comes from. Absent for any other step. |
kind | string | thought for a line of thinking, tool for a tool call. |
step | string | The step the line comes from, named as in step events. |
text | string | The 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
}
| Field | Type | What |
changes | object | What 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.added | integer | Lines the run's edits added. |
changes.files_edited | integer | Distinct files the run's agents edited. Left out when none. |
changes.files_read | integer | Distinct files the run's agents read. |
changes.removed | integer | Lines the run's edits removed. |
event | string | Always done. |
exit | integer | The 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"
}
}
| Field | Type | What |
inputs | object | Values 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
}
| Field | Type | What |
continue | boolean | True 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."
}
| Field | Type | What |
action | string | One 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. |
answer | string | The question's id, or, for older producers, a step name when no question with that id is waiting. |
text | string | The 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.