Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agent/DEFERRED_VERIFICATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ is named in the commit that closes it.
| 1663afd, a327458 | MCP `emit` refuses what `validate` would refuse and takes `inbox_read`; `inbox` marks a reply to an earlier asking `stale`; driven over stdio by tests, not by an agent session | An agent may misread a refusal or ignore `stale` | One agent session using the MCP tools: a refused event, an `inbox_read` through `emit`, a stale reply seen |
| 45bc2ef | A round that is started again is allowed and counted on; tested, not seen from a real loop | A real restart shows a wrong round or a problem | A real loop restarting a round, shown on the board and passing `validate` |
| 5c6efbf, 5672f1a | The board's state lives in the user's state folder, and each repository and loop is a boundary. Seen on a running board on 2026-11-19: a watched folder whose `.loops` cannot be entered is named with the reason, a line dated 9999 and a `loop.json` that cannot be read leave every other loop shown, and Stop for another loop goes through beside the broken one. Not seen: a board started inside a watched repository that holds a planted state folder | The board reads state a repository planted | A board started inside a watched repository with a planted state folder, which it must leave unread |
| 5672f1a | A fault answers with the board's page (500); tested through the app. The 422 page was opened in Chrome on a running board (2026-11-18) | The page may not render in a real browser | The 500 page opened on a running board |
| c07643a | The overview's pulse turns an open page to stalled when a loop goes quiet; tested through the app | An open overview keeps showing running | An overview left open past 45 minutes of silence turns to stalled |
| cbe60a1 | A worktree counts only when its repository lists it back; tested with planted `.git` files | A real worktree is split from its repository, or a claim still passes | A real worktree and a folder with a `.git` file naming another repository, both on a running board |
| df0e651 | The browser is let in by the printed address (cookie `SameSite=Strict`); shown with curl and Chrome, not in Safari or Firefox | Another browser refuses the cookie on the redirect and shows the locked page | The printed address opened in Safari and Firefox, a loop page reached |
Expand All @@ -25,3 +24,4 @@ is named in the commit that closes it.
| the page limits, the open questions, the turn of a sleeping page | Seen on a running board on 2026-11-19: a loop of 75 rounds drawn 30 at a time with links to the rest, two open questions shown one after the other, an open page of a sleeping loop turning to stalled by itself, the example loop started from the board, answered with a button and going on. Not seen: the notice beside Start that a Stop is waiting, the Copy buttons of an empty board, `watch` and `unwatch` on a config a person wrote by hand, a log near 20 MB from a real loop | A wording or a layout reads worse live than in a test; a real config has a shape the line editor does not know and is written anew | Each opened or run once on a real board and a real config |
| hiding a loop, the old mark | Seen on a running board on 2026-11-19: `hide` took a waiting loop off an open first page, which reloaded by itself, out of the waiting count and the figures, the `hidden` chip listed it, its page opened with the command that shows it again, `unhide` brought it back; a loop silent for 20 days showed as stalled, marked old, outside the count of loops that need a look. Not seen: a loop hidden from one worktree and read from another, and `hide` on a config a person wrote by hand | A hidden loop comes back when its repository is read from another worktree | A loop hidden in the main checkout stays hidden while a worktree of that repository writes last |
| the waiting count in a background tab | Seen in Chrome on a running board on 2026-11-19, with the tab made to read as hidden and the notification replaced by a recorder: a second loop asked, the title went from (1) to (2) without the page being drawn again, and one notification was made. Not seen: the browser's own permission prompt answered by a person and the notification the system then shows; `status` and `inbox` were run against a real board's loops | The system shows nothing, or shows it for every poll | Notify allowed in the footer, the board's tab put behind another, a loop made to ask: one notification, and a click on it brings the tab forward |
| the site's head and the release notes | The built site carries a title, a sentence, a card picture and, on the first page, the project as data; no page loads a font from another host; a release note prints its commit's bullets. Checked on the built pages and by tests, not on the published site or a real release | A card that does not show when a link is shared; notes that read badly for a squash merge, whose body is the pull request's list of commits | A link to the published site pasted into a chat or a card checker shows the picture; the notes of the next release read well |
6 changes: 1 addition & 5 deletions .agent/FINDINGS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ in the commit that settles it. Proposed: now, later, check, drop.
| F15 | An optional exporter that tails `events.jsonl` and sends OTLP along docs/opentelemetry.md: its own process and dependency group, off by default, the first thing that would send data off the machine | open | later: when someone wants loops beside agent traces | docs/ARCHITECTURE.md section 15 |
| F17 | The tab title counts what waits; the favicon does not. A count in the icon needs a drawn image per number or script | open | later | src/loopcaptain/board/templates/overview.html |
| F18 | A prompt to build a loop, given to a fresh agent, ended with a 302-line loop file for a three-step job; a smaller starting template (one loop.py of 60 lines beside the helper) would make the first loop cheaper | open | later: check with the next acceptance run | the acceptance run of 2026-11-15 |
| F19 | "Door" is used for the two ways a loop writes its files (the MCP server's docstring and so `docs/reference/mcp.md`, `mcp_server/AGENTS.md`, `standard/LOOPS.md` section 5). A reader new to the project does not know what a door is; the architecture heading and picture now say "ways in" and name the script and MCP | open | later: reword with the next change to those files, then `make docs-pages` | `git grep -n -i door`, 2026-11-15 |
| F20 | SECURITY.md and the issue template send reporters to private security advisories, but private vulnerability reporting is switched off on the repository, so a reporter has no private way in | open | now: a repository setting, no file change | the repository's `private-vulnerability-reporting` setting read `enabled: false`; SECURITY.md:29-31, .github/ISSUE_TEMPLATE/config.yml |
| F26 | The release workflow tags and publishes on a push to main without waiting for CI: 0.3.1 was published 29 seconds after the CI run for the same commit was created | open | now: trigger on a successful CI run, or make the release job need a `make check` job | .github/workflows/release.yml:11-14, :55-66; run and upload times of 2026-11-15 |
| F34 | `a helper of 50 lines` is stale in CHANGELOG.md; the helper has 76 | open | later: the file is frozen at 0.1.0, so only if that entry is ever rewritten | CHANGELOG.md; `wc -l standard/loops.py` |
Expand All @@ -26,12 +25,9 @@ in the commit that settles it. Proposed: now, later, check, drop.
| F72 | PyPI holds no provenance attestations for the published files | open | later | PyPI file metadata of 0.3.1; .github/workflows/release.yml |
| F73 | `make setup` in a worktree repoints the main checkout's git hooks at the worktree's virtualenv | open | later: skip the install when the git dir is not the common dir, and say so in AGENTS.md section B.1 | Makefile:7-12; the installed hook's `INSTALL_PYTHON` line |
| F74 | The repository topics miss the terms people search by (agent loops, human in the loop, dashboard); one topic is shared by six repositories. Topics naming agent products would need a reading of rule 8 | open | check: add `human-in-the-loop`, `agent-monitoring`, `ai-agents`, `coding-agents`, `ralph-loop`, `local-first`, and one of `claude-code` or `agent-protocol`; a repository setting, no file change | repository topics read 2026-11-15 and 2026-11-19 |
| F75 | A shared link shows the code host's generic card, and the docs site has no card image | open | later | repository settings, zensical.toml; review of 2026-11-15 at 7e22640 |
| F76 | `How it differs` names no alternative, so a reader cannot place the project against tools they know. Naming other projects bends rule 8 | open | check: a rule change, and a section in docs/ARCHITECTURE.md | README.md `How it differs`; AGENTS.md rule 8 |
| F77 | A release note is one commit subject, and CHANGELOG.md 0.1.0 contradicts itself and the product in places | open | later: bullets from the commit body into the release note | CHANGELOG.md, scripts/release.py; the notes of 0.3.1 |
| F78 | The generated command-line reference has eleven empty descriptions, lower-cases proper names, and does not say that `emit` values parse as JSON | open | later | docs/reference/cli.md, src/loopcaptain/cli.py help texts |
| F77 | CHANGELOG.md 0.1.0 contradicts itself and the product in places (a helper of 50 lines, among others) | open | later: only if that entry is ever rewritten; the file is frozen at the first version | CHANGELOG.md |
| F80 | The standard a loop author pastes does not say what only `validate` checks beyond the JSON Schema (paths, rules across lines); a loop and a board that look at different key folders make every answer read as not from the person, with no sign on the board | open | later | standard/LOOPS.md, standard/schema/, docs/setup.md section 5; review of 2026-11-15 at 7e22640 |
| F81 | The docs site loads its fonts from a third-party host, while the board vendors its font | open | check: vendor the font in the site too | zensical.toml; requests of the built site, review of 2026-11-15 at 7e22640 |
| F83 | Small stale or author-facing statements across the standard, the site and the nested AGENTS.md files | open | later: with the next change to each file; done on 2026-11-16 for README.md, docs/index.md, docs/get-started.md, docs/installation.md, docs/agents.md and the one line in standard/AGENTS.md | git grep of the review |
| F84 | Protocol proposal held back by rule 3: the helper's `inbox()` could drop entries whose `signed` is not `true`, or that are `stale`, by default or behind an opt-in argument; today a loop filters them itself, and a call written against the earlier text must keep returning what it returned | open | later: an opt-in argument fits version 1, a new default is protocol 2 | standard/loops.py `inbox`; docs/ARCHITECTURE.md section 26, Rejected; commit a327458 |
| F89 | One loop page walks the watched folders several times per request: `find_loop`, `find_repo` and the repository list each call `find_repos(config())`. Measured on 300 folders, 100 of them with loops: 13 ms a walk, so about 50 ms of a page | open | later: one walk per request, if a board with hundreds of folders feels slow | src/loopcaptain/board/discover.py, board/app.py; measured 2026-11-19 |
Expand Down
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,13 +143,14 @@ stdio, installed with its extra (`uv tool install 'loopcaptain[mcp]'`):
it the major one. A push with only `docs`, `test`, `chore`, `ci` or
`refactor` commits makes no release.
3. A release is a tag `vX.Y.Z` and a GitHub release whose notes are the
subjects of those commits, with the wheel attached: built with the
subjects of those commits, each with the bullets of its body below
it, with the wheel attached: built with the
tag's version, installed in a clean environment and smoke-tested first.
It goes to PyPI once the repository variable `PUBLISH_PYPI` is `true`.
4. Nothing is committed back. `pyproject.toml` says `0.0.0`; a checkout
and an install from `main` report that, a released wheel its tag.
5. A commit subject is a line of the release notes, so write it for a
user. `CHANGELOG.md` holds the first version and points to the
5. A commit subject is a line of the release notes and its bullets are
printed below it, so write both for a user. `CHANGELOG.md` holds the first version and points to the
releases.
6. The package version is not the protocol number: a release may add
optional fields and events, never break a loop written today.
Expand Down
14 changes: 7 additions & 7 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -557,8 +557,8 @@ would still vanish.
the line's `event` (`event_tag`); a name not in `EVENT_NAMES` reads as
`OtherEvent`, which the fold skips and which still counts as a sign of
life. `validate` warns (`unknown_events`). The published schema takes any
other event name with a `ts`. Writing stays strict: both `emit` doors
take known events only.
other event name with a `ts`. Writing stays strict: `emit` on the command
line and `emit` over MCP take known events only.

**Why.** Version 1 grows by new events, and the standard tells a board to
ignore what it does not know. A reader that refused them would call the
Expand Down Expand Up @@ -594,21 +594,21 @@ only grows). Raising an error without a key: a loop on a machine where no
board has run yet would not start. A new event for the case: boards
installed before unknown events were skipped would call it a problem.

## 27. A door refuses an event that would stay a problem, and no more
## 27. A way in refuses an event that would stay a problem, and no more

**Decision.** `before_writing` in `protocol/validate.py` holds what the
two doors that write on a loop's behalf check, the MCP `emit` and
two ways in that write on a loop's behalf check, the MCP `emit` and
`loopcaptain emit`. `refusals` (the round has started, the step is in
`loop.json`, the artifact exists, the verdict agrees with the round's
first) refuses an event: the door writes nothing. An `inbox_read` naming
first) refuses an event: nothing is written. An `inbox_read` naming
an entry the models cannot read is written with a warning; where
`loop.json` or the log cannot be read (over the size the reader takes,
unreadable), the event is written without the checks against the log,
with a warning. The MCP `emit` adds the warning to its answer,
`loopcaptain emit` writes it to standard error. Both take `inbox_read`.

**Why.** The log is append-only, so a line `validate` refuses is refused
for good; a writer that hears `recorded` never learns it. A door that
for good; a writer that hears `recorded` never learns it. A way in that
refuses more than `validate` calls a problem stops a loop for nothing.
The standard has a loop append `inbox_read` after acting on entries, and
a loop that reads the inbox file itself has no other way to mark them;
Expand All @@ -619,7 +619,7 @@ loop still has to report.

**Rejected.** Writing the line and returning the problems with it: the
problem is then permanent, and the caller can only add to it. Refusing
`inbox_read` on both doors: a shell loop would have to write the line by
`inbox_read` on both ways in: a shell loop would have to write the line by
hand, without any check of its ids. Refusing an unreadable entry or an
unreadable log: the loop could not report at all. Writing such a line
silently: the writer would not know its line went unchecked.
Expand Down
Binary file added docs/assets/social-card.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/board.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
---
title: "The board: a local dashboard for agent loops"
description: "The local dashboard: its pages, where to look first, how to answer, stop and start a loop, and what each status means."
---

Expand Down
1 change: 1 addition & 0 deletions docs/connect.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
---
title: "Connect or build an agent loop"
description: "Connect an agent loop you already run, or build one that reports: through the pasted helper, the command line or the MCP server."
---

Expand Down
89 changes: 89 additions & 0 deletions docs/faq.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
title: "Questions about monitoring and steering agent loops"
description: "Short answers: what an agent loop is, how to monitor and stop one, how a human stays in the loop, which agents work, and what leaves the machine."
---

# Questions and answers

## What is an agent loop?

A program that hands work to an AI agent again and again until a goal is
met or a limit is reached: a plan, the work, a review, a verdict, and then
the next round. A Ralph loop (a shell loop around one prompt), Claude
Code's `/loop`, a research script that calls a model every round and a
long-running agent session are all agent loops.

## How do I monitor an agent loop that runs for hours?

Let it write what happens into `.loops/<loop-id>/events.jsonl` in its own
repository, one line per event, and open the board. The board shows every
loop on the machine: which round it is in, what each step found, what it
cost, and whether it still moves. A Python loop pastes a helper of under
110 lines, a shell loop calls `loopcaptain emit`, an agent session uses
the MCP server. [Connect or build a loop](connect.md) has the steps.

## How do I stop or steer a running agent loop?

Press Stop on the loop's page, answer its question with a button, or type
a note for the next round. The board appends a signed line to the loop's
`inbox.jsonl`; the loop reads it at the start of a round and acts on it.
The signature lets the loop tell your line from one an agent wrote into
the file. See [The board](board.md).

## How do I keep a human in the loop without watching a chat window?

A loop asks with a `question` event and either goes on with a default or
stands still until you answer. The board lists what waits for you, counts
it in the tab's title and can notify you through the browser. You answer
when you look, and the loop takes the answer at its next round.

## How do I monitor a Ralph loop?

Two commands in the shell loop: `loopcaptain emit` for each round and
step, `loopcaptain inbox` to read your stop and notes. A complete
`loop.sh` is on [Monitor a Ralph loop or any shell loop](shell-loop.md).

## Which coding agents does it work with?

Any. The protocol is plain files, so whatever can write a file can
report: Claude Code, Codex, Gemini CLI, Cursor, opencode, Amp, or a
script that calls a model's API. [Works with every agent](agents.md)
lists how each adds the MCP server.

## Does a loop have to install or import Loopcaptain?

No. A loop writes three small files; the helper is pasted text that uses
the Python standard library only. The board is installed once per
machine: `uv tool install loopcaptain`.

## Does anything leave my machine?

No. The board listens on `127.0.0.1` only, loads nothing from another
origin and sends nothing anywhere. It reads files in the repositories you
tell it to watch and writes only the inbox lines you send. The
[threat model](security.md) says what it reads, runs and writes.

## How is this different from tracing and observability tools?

Those record what a model call did, for later analysis, usually in a
hosted service. Loopcaptain shows where a loop stands now, round by
round, and carries your answer back into it; it runs on your laptop and
keeps its data in your repositories. The two fit together: a loop's
events map onto OpenTelemetry, see [OpenTelemetry](opentelemetry.md).

## What does it cost?

Nothing. Apache License 2.0, no account, no service. The example loop
that `loopcaptain demo` writes calls no model, so trying it is free too.

## How do I see every loop without opening a browser?

`loopcaptain status` prints one line per loop in the terminal: its
status, its round, its last line and what it asks.

## How do I take a finished or dead loop off the board?

`loopcaptain hide <repository> <loop>` takes one loop off the first page
and out of the figures; `unhide` brings it back. Loops that ended are
folded away by themselves, and one that died weeks ago is marked old and
no longer counts as needing a look.
1 change: 1 addition & 0 deletions docs/get-started.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
---
title: "Get started: run an agent loop on the board in five minutes"
description: "Run the free example loop on the board: no model, no network. Start it, answer its question with a button and watch it finish."
---

Expand Down
1 change: 1 addition & 0 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
---
title: "Install Loopcaptain"
description: "Install Loopcaptain from PyPI with uv, pipx or pip, run it once through uvx, or install a tagged release from the repository."
---

Expand Down
Loading
Loading