Loops protocol, version 1
How an agent loop says what it is and what happens in it, so that a board can show it and a person can steer it. This file is the whole interface: paste it into the repository of a loop, or hand it to the agent that writes the loop. Nothing else is needed.
A loop keeps one small folder in its own repository. It says once what it is, then appends one line for each thing that happens. A board reads that folder and writes the person's answers into it. No server, no dependency, no network: a loop in any language that can write a file can do this. The protocol names no tool, vendor or model.
<repository>/.loops/<loop-id>/
loop.json what the loop is written by the loop
events.jsonl what happened, line by line appended by the loop
inbox.jsonl what the person sends appended by the board
<loop-id> is lowercase letters, digits, ., -, _. A repository may
hold several loops, one folder each. A run that counts its rounds from 1
again (a new branch, a fresh start) is a loop of its own, with its own id
such as review-run-3, so the rounds of two runs never mix. Whether .loops/ is committed or
ignored is the repository's choice.
A board reads an events.jsonl of up to 20 MB and refuses a larger one
whole, so a loop that would outgrow that goes on under a new id before it
does: its earlier rounds stay readable under the old one. loopcaptain
validate warns from 10 MB on.
1. loop.json: what the loop is
Written when the loop starts; writing it again replaces it. A loop.json
that is not valid JSON is still a loop: a board lists it as unreadable and
says what the parser said.
{
"protocol": 1,
"id": "market-scan",
"title": "Market scan of field service tools",
"brief": {
"goal": "Which three tools should the client try first?",
"audience": "The head of operations",
"bar": "She can name the three and say why",
"path": "brief/brief.md"
},
"steps": [
{"id": "plan", "kind": "plan", "name": "Editor plans", "backend": "agent-cli", "model": "large"},
{"id": "research", "kind": "research", "purpose": "One agent per angle", "backend": "another-agent-cli"},
{"id": "build", "kind": "build", "prompt": "prompts/build.md"},
{"id": "facts", "kind": "review", "after": ["build"], "purpose": "Every number has a source"},
{"id": "reader", "kind": "review", "after": ["build"], "purpose": "Reads as the audience"},
{"id": "gate", "kind": "gate", "after": ["facts", "reader"]},
{"id": "verdict", "kind": "verdict"}
],
"round_cap": 12,
"cost_cap_usd": 60,
"pace": "stops when it needs the person",
"commands": {"start": "make loop ROUNDS=3"},
"outputs": [{"name": "memo", "path": "out/memo.md"}],
"workspace": {"branch": "loop/market-scan", "worktree": "../market-scan-loop"},
"state": [{"name": "progress", "path": "work/progress.md"}]
}
Only protocol and id are required. The rest:
brief: the goal, the audience and the bar for done in a line each, and the path of the full brief.steps: the roles of one round, in order. This is the graph the board draws.kindis one ofplan,research,analyse,build,review,gate,verdict,other. A step follows the one listed before it; giveafteronly where that is not so (two reviewers that both followbuild, a gate that waits for both).name,purpose,prompt(a path),backendandmodelare shown as given.backendis whatever runs the step: the name of an agent's command line, a script, a person. The protocol knows no vendor.round_cap,runtime_cap_minutes,cost_cap_usd: the loop's own limits. It stops at whichever comes first; the board shows them.commands.start: the one command the board may run, in the repository root, when the person presses Start. Leave it out and the board has no Start button for this loop.outputs: what the loop makes, by path.workspace: the branch and worktree the loop runs in, andstate: the files one round hands to the next (a progress note, a feature list). Both are shown as text to copy, so a person can pick the loop up by hand; the board runs neither.
Every path in the protocol is relative to the repository root.
2. events.jsonl: what happened
One JSON object per line, appended, never rewritten. A line ends at the
newline character (\n) and at nothing else: split on that alone, since a
text may hold other characters that some languages also call a line break
(U+2028, U+2029, U+0085). Every line has ts
(UTC, 2026-11-14T21:03:00Z, fractions of a second allowed:
2026-11-14T21:03:00.250Z), the time the line was written, and
event. Any line may carry at: the time the thing really happened, for
a loop that reports later than it works. Durations are measured on at
where it is given, so a round written after the fact keeps its real
times. A time without a zone is read as UTC. Any year is read, 9999
for "never" included; a next_at holds at most a week after its line.
A number that is not finite (Infinity; NaN where the field has no
lower bound) is read too, and counted as absent: a cost of it adds nothing, a measure of it is not
drawn, a cost cap of it is no cap. validate warns of both. A line
stamped more than a few minutes ahead of the reader's clock is read, but
is no sign that the loop is alive, and its next_at no promise, until
its time has come.
event |
Fields | When |
|---|---|---|
round_started |
round, plan, artifact, mode |
A round begins. plan is a few lines. |
step_started |
round, step, label |
Optional: shows the step as running. |
step_finished |
round, step, label, status, passed, summary, artifact, findings, cost, metrics, attempt, error, session, model |
A step ends. |
finding_closed |
round, step, id, label, resolution, reason |
A finding of this round is settled. |
round_finished |
round, verdict, stop_reason, summary, next, commit, artifact, cost, metrics, outcome, next_at |
A round ends. |
question |
text, round, blocks, timeout_s, id, options, default |
The loop needs the person. |
question_closed |
question, reason, answer |
The loop ends its own question. |
loop_started |
rounds |
The loop's process starts. |
loop_stopped |
stop_reason, summary |
The loop ends between rounds. |
heartbeat |
text, next_at |
Alive; when to expect the next line. |
check |
item, kind, result, who, finding, evidence, round |
One check of one thing the loop evaluates. |
inbox_read |
ids |
The loop has taken these inbox entries. |
A reader skips a line whose event it does not know and reads on: later
releases add events to this table, and a loop may write its own. Such a
line still needs ts, and still shows that the loop is alive.
roundcounts from 1.stepis a step id fromloop.json. Around_startedfor a round that already ran starts that round again, clean; what its earlier try spent still counts in the round's cost.modenames the kind of round, for a loop that alternates (breadthanddepth,researchandwrite): the board shows it, and reads a step such a round skips, or leaves out, as meant.labeltells runs of one step apart within a round: a research step with eight agents sends eightstep_finished, each with its angle aslabel.status:ok,failedorskipped. Left out, it isok.failedmeans the step broke. A gate that ran and said no did not fail: sendstatusokandpassedfalse, andpassedtruewhere it let the work through.summary: one or two sentences.artifact: the path of the file the step wrote (the plan, the review, the gate report). The board links to it and never copies it.findings: what a reviewer or a gate found, each{"id": "1", "text": "...", "severity": "material"};severityismaterialorminor. Reviews are fresh each round: what is open is what the last round's reviews found and nobody closed. A step that reports again in the same round replaces what it reported before. Infinding_closed,labelnames the run of a fan-out step; left out, the finding is closed in every run of the step.resolutionsays how it was settled:fixed,accepted(it stands, on purpose),wontfix,false_positiveorduplicate;reasonis a sentence.cost:{"usd": 0.34, "tokens_in": 162113, "tokens_out": 4784}, any part of it, andtokens_cache_read,tokens_cache_write,turns, andestimated: truewhere the figures are the loop's guess.usdis optional: an agent on a subscription reports none, and the board then shows tokens. Acostonround_finishedis the round's whole cost, for a loop that knows only the sum; the steps' costs are then not added.verdict: what happens next.continue(another round follows),done(the goal is met),wait(the loop needs the person before it goes on),stopped(it ended without meeting the goal) orfailed(the round broke).stop_reasonsays why where the verdict does not:goal_met,round_cap,cost_cap,runtime_cap,person,no_progress,errororimpossible(the goal cannot be met as asked).nextis the brief for the following round,committhe commit of this one.outcomeiskeptordiscarded: a round whose work was thrown away, an experiment that made things worse.next_atis when the next round starts, for a loop that sleeps between rounds: the board shows it as sleeping, not stalled, until then, and at most a week ahead. A new round spends the promise.question:blocksistruewhen the loop stands still until the answer comes,timeout_show long it waits before it goes on without one. Left out, the loop goes on and reads the answer at its next round. A question is open until the person replies. A blocking question is also over once itstimeout_shas passed or the loop starts another round: it went on. Several questions may be open at once: give each anid, since a reply answers the one question it names, and a question without anidtakes the place of the last one without; the board shows the earliest one the loop stands still for first, and the next after each answer.idnames the question;options,[{"id": "a", "label": "Forty people"}], become buttons, and the reply carriesquestionandchoice.defaultis what the loop goes on with if no answer comes: theidof one of the options, or a sentence; the board shows it beside the question, with the time the loop stops waiting.question_closedends a question the loop settled itself:reasonisanswered(elsewhere,answersays how),superseded(it went on with a default) orwithdrawn;questionis the id, left out the last open question.check: for loops that evaluate a list of things (use cases, skills, features).kindis free text such asdesk research,own trial,workshop,automated test;resultispass,partly,failorblocked. A kind nobody ran for an item shows as an empty cell.metrics: the numbers a loop optimises, on a step or a round,[{"name": "pass rate", "value": 0.82, "target": 0.95, "better": "higher", "unit": ""}]. The board draws each per round. Optional, so a person can tell what a number counts:label, the name as it should read ("Topics covered");about, one sentence on what is counted;file, a path in the repository to a file that lists it.attemptcounts tries of a step within a round from 1;error,{"kind": "transient" | "needs_person" | "limit", "text": "..."}, says why it did not succeed.needs_personwaits for the person like a blocking question, until they reply.limitsays a limit stopped the step, a budget, a usage or rate limit or a turn cap, and not that its work went wrong: the board shows it apart from a failure.sessionis the agent session the step ran in, shown as text so a person can resume it by hand.modelis the model the step really ran on, where it is not the oneloop.jsonnames for the step: a fallback after the first one refused.loop_stopped: the loop ended between rounds, say after a stop that came when no round was open. The last round's verdict stays as it was. While a round is open it ends nothing: finish the round first.heartbeat: a loop that works quietly or sleeps says it is alive and, withnext_at, when its next line comes. Until then it is not stalled. Without one, the board shows a round under way as stalled once 45 minutes have passed since the loop's last line, and a loop past itsnext_at45 minutes after that time: a step that runs longer without writing a line sends aheartbeat.loop_started: optional, for a loop whose process runs a number of rounds and ends, and is started again.roundsis how many rounds this start may run. The board counts the starts and the rounds of the latest one, and a start that has finished itsroundsreads as capped, not as a loop that went quiet. It ends no round and changes no count: rounds still count on from the last one.
A round of the example above, as lines:
{"ts": "2026-11-14T21:00:00Z", "event": "round_started", "round": 3, "plan": "Close the two fact findings; add pricing."}
{"ts": "2026-11-14T21:04:10Z", "event": "step_finished", "round": 3, "step": "plan", "artifact": "work/rounds/3-plan.md", "cost": {"usd": 0.31}}
{"ts": "2026-11-14T21:09:40Z", "event": "step_finished", "round": 3, "step": "research", "label": "pricing", "summary": "List prices for five of six tools."}
{"ts": "2026-11-14T21:15:02Z", "event": "step_finished", "round": 3, "step": "facts", "artifact": "work/rounds/3-review-facts.md", "findings": [{"id": "1", "text": "The 40 percent figure has no source."}]}
{"ts": "2026-11-14T21:16:30Z", "event": "question", "round": 3, "text": "Is the budget per seat or per site?"}
{"ts": "2026-11-14T21:17:00Z", "event": "round_finished", "round": 3, "verdict": "continue", "summary": "Pricing is in; one fact is open.", "commit": "3fa3487"}
3. inbox.jsonl: what the person sends
The board appends; the loop only reads. Read it at the start of every round, wherever the loop waits for the person, and once more before the loop ends. That last read takes a stop sent during the final round: left unread, it would be the first thing the next start reads, and that start would end at once. A reply read that late is steering for the next start; keep it in a file of the loop's own.
{"id": "20261114T211900-a3f1", "ts": "2026-11-14T21:19:00Z", "kind": "reply", "text": "Per seat.", "round": 3, "loop": "market-scan", "loop_sig": "9c1e..."}
{"id": "20261114T213000-09bc", "ts": "2026-11-14T21:30:00Z", "kind": "stop"}
{"id": "20261114T214500-5d20", "ts": "2026-11-14T21:45:00Z", "kind": "reply", "text": "Won't fix: No source for the price.", "round": 3, "finding": {"step": "review", "id": "2", "resolution": "wontfix", "reason": "The price is quoted on request only."}, "sig": "1f7a..."}
reply: text for the loop. It answers the open question if there is one; without one it is steering for the next round. A reply to a question with anidcarriesquestion, andchoice, the id of the option the person picked, where the question offered options. A reply that settles a finding carriesfinding: itsstep,idandlabel(the run of a fan-out step), theresolutionthe person chose (accepted,wontfixorfalse_positive) and, if they gave one, areason. It answers no question. The loop SHOULD close that finding withfinding_closed, that resolution and that reason, and keep it closed in later reviews.stop: end. A stop read during a round: finish the round and sendround_finishedwith its real verdict,doneif the goal was met, elsestoppedwithstop_reasonperson. A stop read between rounds, or in the last read before the loop ends: sendloop_stoppedand start no round, withstop_reasongoal_metwhere the last round wasdone.
After acting on entries, append inbox_read with their ids so the board
shows them as read.
Every line the board writes carries loop_sig, an HMAC-SHA256 in hex over
the line without sig and loop_sig (keys sorted, no spaces, as
json.dumps(..., sort_keys=True, separators=(",", ":"),
ensure_ascii=False) writes it). The line names its loop in loop, signed
with the rest, so a line copied into another loop's inbox does not verify
there. The key is this loop's alone. The board makes one for each loop
folder and puts it in a file of its own in its config folder, outside
every repository: ~/.config/loopcaptain/keys/<name>.key, where <name>
is the first 32 hex characters of the SHA-256 of the loop folder's
resolved path. Where LOOPCAPTAIN_INBOX_KEY names a file elsewhere,
keys/ lies beside that file. A loop that holds its key can sign for its
own inbox and for no other loop's.
A line also carries sig, an HMAC under the one key every loop read
before each had its own (inbox.key in the same folder), over the line
without sig. A helper pasted from that earlier text checks it and keeps
working; the helper below does not read it, and the board does not trust
it. The helper and the MCP tool add signed to each entry:
true: the board wrote it for this loop.false: anything else did. A loop whose agents can write files SHOULD NOT act on it: it is not from the person.null: nothing was checked, because the loop cannot read its key. No board has seen this loop yet, or the loop runs somewhere the config folder is not visible (a container), orLOOPCAPTAIN_INBOX_KEYnames another place than the board's.nullis nottrue: a line from the person and a line from anyone else who can write the file look the same.
A loop SHOULD act only on entries whose signed is true. Where the key
cannot be read, make it readable to the loop (mount the loop's key file,
or set LOOPCAPTAIN_INBOX_KEY) rather than accept null; a loop that accepts
null anyway does so knowing that its inbox is then only as safe as its
repository. The helper writes a line to standard error whenever it hands
out an entry it could not check, so the case does not pass unseen.
A signature says who wrote a line, not when it still applies. The helper
and the MCP tool therefore add stale to each entry: true for a reply
that names a question (question) and was written before the loop last
asked that question. It answers an earlier asking, and a loop SHOULD NOT
take it as the answer to the present one.
4. The helper to paste
Standard library only, for Python 3.9 and later. Copy it into the loop as
loops.py; the same text is the file loops.py beside this one.
"""Loops protocol 1: say what a loop is, what happened, and read the person's answers."""
import hashlib
import hmac
import json
import os
import sys
import time
from datetime import datetime, timezone
from pathlib import Path
def folder(loop_id, repo="."):
path = Path(repo) / ".loops" / loop_id
path.mkdir(parents=True, exist_ok=True)
return path
def register(loop_id, manifest, repo="."):
"""Write loop.json. `manifest` holds title, brief, steps and so on; id and protocol are set here."""
target = folder(loop_id, repo) / "loop.json"
tmp = target.with_suffix(".tmp")
tmp.write_text(json.dumps({**manifest, "protocol": 1, "id": loop_id}, indent=2) + "\n", encoding="utf-8")
tmp.replace(target)
def emit(loop_id, event, fields=None, repo=".", at=None):
"""Append one event line, stamped now; `at` (a datetime or text) is when it really happened."""
if {"ts", "event", "at"} & set(fields or {}):
raise ValueError("emit sets `ts` and `event`; pass when it happened as `at=`, not a field")
now = time.time()
ts = time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(now)) + f".{int(now % 1 * 1000):03d}Z"
line = {"ts": ts, "event": event}
stamp = at.astimezone(timezone.utc).isoformat() if isinstance(at, datetime) else at
line.update({key: value for key, value in {"at": stamp, **(fields or {})}.items() if value is not None})
with open(folder(loop_id, repo) / "events.jsonl", "a", encoding="utf-8") as log:
log.write(json.dumps(line) + "\n")
def lines(path):
"""The JSON objects of a file, one per complete line; a line that is not JSON is skipped."""
found = []
if path.exists():
complete = path.read_text(encoding="utf-8", errors="replace").rpartition("\n")[0]
for line in complete.split("\n"): # a line ends at "\n" only, whatever else the text holds
try:
found.append(json.loads(line))
except (ValueError, RecursionError):
continue
return [entry for entry in found if isinstance(entry, dict)]
def last_round(loop_id, repo="."):
"""The highest round the loop has finished, 0 before the first: a new start counts on from it."""
events = lines(folder(loop_id, repo) / "events.jsonl")
rounds = [event.get("round") for event in events if event.get("event") == "round_finished"]
return max([number for number in rounds if isinstance(number, int)], default=0)
def signed(entry, loop_id, repo="."):
"""True if the board wrote this entry for this loop, False if not, None where there is no key."""
home = Path(os.environ.get("LOOPCAPTAIN_INBOX_KEY") or "~/.config/loopcaptain/inbox.key").expanduser()
place = str(folder(loop_id, repo).resolve()).encode() # this loop's own key, named after its folder
key = home.parent / "keys" / (hashlib.sha256(place).hexdigest()[:32] + ".key")
if not key.is_file():
return None
if entry.get("loop") != loop_id:
return False
body = {key: value for key, value in entry.items() if key not in ("sig", "loop_sig")}
text = json.dumps(body, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
try:
secret = bytes.fromhex(key.read_text(encoding="utf-8").strip())
except ValueError:
return None # a key the board would not use either: nothing can be told apart
mark = hmac.new(secret, text.encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(mark, str(entry.get("loop_sig", "")))
def moment(stamp):
"""A `ts` as seconds to compare, or None where it cannot be read. No zone means UTC."""
try:
parsed = datetime.fromisoformat(str(stamp).replace("Z", "+00:00"))
except ValueError:
return None
return (parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)).timestamp()
def stale(entry, asked):
"""True for a reply written before the question it names was last asked: it answers an earlier asking."""
then, sent = asked.get(str(entry.get("question"))), moment(entry.get("ts"))
return then is not None and sent is not None and sent < then
def inbox(loop_id, repo="."):
"""What the person sent since the last call, oldest first, with `signed` and `stale`; marks it read."""
base = folder(loop_id, repo)
seen, asked = set(), {}
for event in lines(base / "events.jsonl"):
if event.get("event") == "inbox_read":
seen.update(event.get("ids", []))
elif event.get("event") == "question" and event.get("id"):
asked[str(event["id"])] = moment(event.get("ts"))
fresh = [entry for entry in lines(base / "inbox.jsonl") if entry.get("id") and entry["id"] not in seen]
if fresh:
emit(loop_id, "inbox_read", {"ids": [entry["id"] for entry in fresh]}, repo)
taken = [{**e, "signed": signed(e, loop_id, repo), "stale": stale(e, asked)} for e in fresh]
if any(entry["signed"] is None for entry in taken):
sys.stderr.write("loops: no board key to read, so `signed` is None: these entries are unchecked\n")
return taken
A loop then needs about one call per step. last_round is what lets the
same command run twice: the second run goes on from the round after the
last one that finished, where a count from 1 would start the old rounds
again.
import loops as board
board.register("market-scan", {"title": "Market scan", "steps": STEPS, "commands": {"start": "make loop"}})
first = board.last_round("market-scan") + 1 # a second start counts on; it never begins at 1 again
board.emit("market-scan", "loop_started", {"rounds": ROUNDS})
for n in range(first, first + ROUNDS):
messages = board.inbox("market-scan")
if any(m["kind"] == "stop" and m["signed"] is True for m in messages):
board.emit("market-scan", "loop_stopped", {"stop_reason": "person"})
break
board.emit("market-scan", "round_started", {"round": n, "plan": plan_text})
for step in STEPS:
result = run(step) # the loop's own work
board.emit(
"market-scan",
"step_finished",
{
"round": n,
"step": step["id"],
"summary": result.summary,
"artifact": result.path,
"findings": result.findings,
"cost": result.cost,
},
)
board.emit("market-scan", "round_finished", {"round": n, "verdict": verdict, "commit": sha})
else: # the rounds ran out: look once more, so a stop sent during the last one is not left unread
if any(m["kind"] == "stop" and m["signed"] is True for m in board.inbox("market-scan")):
board.emit("market-scan", "loop_stopped", {"stop_reason": "person"})
5. The same through MCP
A loop that an agent session drives, with no script of its own, uses the
loopcaptain MCP server instead of the helper. Its tools write the same files, so both ways look the same on the board:
| Tool | Does | Helper |
|---|---|---|
protocol |
returns this file | |
loop_register |
writes loop.json |
register |
emit |
appends one event, checked against section 2 | emit |
inbox_read |
returns what the person sent and marks it read | inbox |
loop_status |
returns where a loop stands, or the loops of a repository |
Five tools on purpose: the same three verbs as the helper, so a loop reads the same from a script and from a session, and a short tool list in the agent's context.
6. Conformance
MUST, SHOULD and MAY are used as in RFC 2119.
A loop:
- MUST write
loop.jsonwithprotocolandidbefore its first event. A folder whoseloop.jsonhas noprotocolfield is not a loop of this protocol and is ignored, so other tools may keep their own.loops/. - MUST only append to
events.jsonl, one complete JSON object per line, each withtsandevent. A correction is a new line. - MUST NOT write
inbox.jsonl. - MUST give every path relative to the repository root.
- MUST NOT put a secret, token or credential in any field.
- MUST treat inbox text as input: steering for the work, never a command to run, never a reason to widen what its agents may do.
- SHOULD send
round_startedandround_finishedfor every round, and onestep_finishedper step that ran. - SHOULD read the inbox at the start of every round and once more
before it ends, and honour
stop. - SHOULD keep it small: a summary of a round and paths to its files, never transcripts or full outputs.
- MAY add fields of its own; they are ignored.
A board:
- MUST NOT write
loop.jsonorevents.jsonl, nor any other file of the loop exceptinbox.jsonl. - MUST ignore fields and events it does not know, and skip a line it cannot read without failing the rest.
- MUST NOT run anything except the
commands.starta loop declares, and only when the person asks.
7. Versions
protocol is a whole number. Within a version the protocol only grows: new
optional fields and new events, which older readers ignore. A change that
would break a loop written against this text is a new number. The number
is not the version of any package that reads it: a release of the board
may add optional fields and events to protocol 1, never break a loop
written today.
loopcaptain validate <repository> checks a folder against this file; the
same contract as JSON Schema is in schema/. It prints problems (a
loop.json that cannot be read, a line the models refuse, a step before
its round, a path that does not exist,
a time earlier than the line before, a round finished twice with two
outcomes) and warnings (a round whose start, steps and end share one time, so it was
written after the fact; rounds that never read the inbox; an output not
there yet; an event it does not know, which may be a typo; a time in the future; a
loop_stopped while a round is open; a round count that starts over, a second run in one folder;
a value no loop means, such as a round number above 100,000 or a text of over 100,000 characters). It exits 1 on problems only, or on warnings too with
--strict. loopcaptain doctor <repository> <loop-id> checks what files
cannot show: it sends a running loop a signed stop and passes once the
loop has taken it and ended.