Make a loop meet the Loops protocol
For an agent (or a person) working in another repository that holds an
agent loop. You were pointed here to make that loop show up on
Loopcaptain. Everything you need to connect it is in this folder; the
per-agent MCP commands are in docs/agents.md of the same repository.
The loop's design stays its own: its roles, its graph, its prompts, its files, its language. The standard only asks it to say what it is and what happens, in one small folder.
What is in this folder
| File | What it is |
|---|---|
| LOOPS.md | The protocol: the files, the events, the rules for a loop and a board. Read it first. |
| loops.py | The helper to copy into a Python loop: register, emit, inbox. Standard library only. |
| templates/ | Three loop.json to start from: a research loop, a review loop, an editor-maker-lens loop. |
| schema/ | The same contract as JSON Schema, for loops in other languages. |
| prompts/ | The two prompts a person gives their coding agent: build a loop, watch the loops here. |
Connecting a loop that exists is the first part below; building one from nothing is the second, Build a loop from nothing.
What to do
- Read LOOPS.md, then the loop's own code: which roles run in a round, in which order, what each writes, where the round ends, where it asks the person.
- Describe the loop. At start-up, write
.loops/<loop-id>/loop.json: the title, the brief in three lines with the path of the full brief, and one step per role as the loop really runs them. Useafteronly where a step does not simply follow the one before. Copy the closest file in templates/ and change it; do not bend the loop to the template. - Report what happens. One line per event, at the places the loop
already has:
round_startedwhere a round begins,step_finishedwhere a role returns (with the path of the file it wrote, its findings and its cost if the loop knows them),round_finishedwhere the verdict is known. Report as it happens; a loop that can only report later gives each lineat, the time it really happened. In Python, copy loops.py and callemit; elsewhere, append one JSON line. A loop driven by an agent session, with no script, uses theloopcaptainMCP server instead (LOOPS.md, section 5). - Listen. At the start of every round call
inbox: areplyis the person's steering for the work, astopmeans finish this round and end. Where the loop needs the person, emitquestion. Act only on an entry whosesignedistrue:falsemeans the board did not write it,nullthat the loop could not read the key to check. - Start command, optional. If the loop can be started with one
command from the repository root, name it in
commands.start. The board runs exactly that, nothing else.loop.jsonnames that command, so a loop that limits what its agents may write must keep them out of.loops/too, or an agent could change what Start runs. - Decide what is committed.
.loops/holds summaries and paths, never transcripts or secrets. Commit it or add it to.gitignore; say which in the repository's own instructions.
When it is met
loopcaptain validate <repository>printsok. The command comes withuv tool install loopcaptain(Python 3.12 or later), or runs once without installing asuvx loopcaptain validate <repository>. Where neither is possible, check each file against schema/.- One real round has run and the folder shows it: a
round_started, onestep_finishedper role that ran, around_finishedwith its verdict. - Every path in the folder is relative to the repository root and exists.
- The loop reads the inbox: start
loopcaptain doctor <repository> <loop-id>first, then the loop. The doctor sends a signedstopand passes once the loop took it and ended (stopped,done, orloop_stopped). A loop that finishes in a second needs no pacing: it reads the stop at its first round. - The board shows it:
loopcaptain watch <repository>, thenloopcaptain serve. A finished loop is folded away on the first page; tick "show finished loops". - Nothing else about the loop changed: same rounds, same outputs.
Keep it small
- Add calls; do not restructure the loop around them.
- A failing write to
.loops/must never stop a round: log it and go on. - If the loop has something the standard has no field for, add your own field. Unknown fields are ignored, and that is by design.
The one line for the other repository
Put this in the loop repository's AGENTS.md, so any agent that works
there keeps the standard met:
This loop reports to Loopcaptain. Keep it meeting the Loops protocol: read
standard/AGENTS.mdin the Loopcaptain repository, https://github.com/faviens/loopcaptain, and check withloopcaptain validate ..
Build a loop from nothing
For an agent asked to build a new loop, not to connect one. Ask first, build the smallest round that works, run it once for real, then grow it. What follows is what published loop practice agrees on; the sources are at the end.
1. Ask the person
- What is the loop for: the result in one sentence, and who reads it.
- When is it done: a bar a reviewer can check, ideally a number.
- What may it cost: rounds, minutes and money. These become
round_cap,runtime_cap_minutesandcost_cap_usd. A cap is above zero; a loop that may spend nothing leavescost_cap_usdout and calls no paid service. - Where should it ask the person, and what may it decide alone.
- What must it never do: push, publish, spend, delete. Those steps get a question with options, never a default.
Write the answers into brief.md and the brief of loop.json.
2. Design one round
- The one who judges is not the one who made it. A maker grades its
own work kindly. Give review to separate steps with their own prompt
(
kind: review), each looking for one thing, and agatethat reads only their findings. - Plan, make, review, gate, decide. Most loops are this shape:
planwrites what this round changes,researchorbuilddo it,reviewsteps find what is wrong (materialorminor), thegatepasses when nothing material is open,verdictsays what comes next. - A number where there is one. If the bar is a measure (a pass rate,
a score, a count of unsourced claims), report it as
metricson the round, with itstarget. The board draws it per round. - Keep steps few. Every step costs a call. Add a reviewer when a real round shows a kind of fault nobody caught.
- A step with nothing to do this round (a set-up step after round 1)
reports
step_finishedwithstatus: skipped, so the graph stays the same every round.
3. Make a round resumable
- Start every round from a fresh context and a progress file (
stateinloop.json): what was done, what is open, what the next round does. Long contexts drift; a file does not. - Where the repository uses git, commit once per round and report the
commit; a round that made things worse is reported with
outcome: discardedand reset. Without git, keep the last good output beside the new one instead. - At the start of a round: read the inbox, read the progress file, read the last round's open findings. Nothing else carries over.
- Report as it happens. A line written later carries
at, the time it really happened.
4. Stop on purpose
- Stop at the first cap reached, with its
stop_reason. - Stop with
goal_metwhen the gate passes and the bar is met. - Stop with
no_progresswhen the round is not getting closer. Three rules, the same the board flags as "no progress?": - the same material findings stayed open two rounds running;
- the measure has not moved for three rounds;
- open material findings did not fall over three rounds.
- Stop with
impossiblewhen the goal cannot be met as asked, and say why in the summary. - Honour a
stopfrom the inbox: read the inbox at the start of every round, and again before the verdict if a round takes long. A stop read during a round ends it with its real verdict (doneif the goal was met, elsestopped); one read between rounds isloop_stopped. Act on no entry whosesignedis nottrue.
5. Ask the person well
- Ask only what the brief cannot answer, and only where the answer changes the work.
- Give options (
questionwithoptions); a button is answered in seconds, an open question in hours. - Say what happens without an answer:
blockswith atimeout_s, then go on with a stated default and close the question withquestion_closed, reasonsuperseded. - An error only a person can fix (an expired login, a missing right) is
step_finishedwitherror.kind: needs_person, not a retry loop.
6. Run it
A loop is a script, or an agent session that runs rounds. Either way
commands.start names one command, and the board starts it with a
minimal environment.
- A script calls an agent once per step, without a person at the
keyboard, and reports with the helper. Map the agent's JSON result to
cost(tokens, cache tokens, turns;usdonly if the agent reports it) and its budget flags to the caps. The command per agent is in docs/agents.md. - An agent session that loops by itself (a native loop or schedule
command, a stop hook that starts the next round) reports through the
MCP server. It calls
inbox_readat the start of every round. - A schedule that starts one round at a time reports
next_atonround_finished, so the board shows it as sleeping, not stalled.
Then run one round for real, check it with loopcaptain validate ., and
check that it listens with loopcaptain doctor . <loop-id>.
Sources
Read on 2026-11-15: harness design for long-running apps, effective harnesses for long-running agents, autoresearch, human in the loop.