Skip to content

feat(cli): show every loop in the terminal, and let a shell loop read its inbox - #35

Merged
danielvogler merged 4 commits into
mainfrom
feat/terminal-commands
Nov 19, 2026
Merged

danielvogler merged 4 commits into
mainfrom
feat/terminal-commands

Conversation

@faviens-agent-daniel

Copy link
Copy Markdown
Contributor

What changes for a user

  1. loopcaptain status prints one line per watched loop in the terminal, what needs the person first: status, round, last line, what the loop asks.
  2. loopcaptain inbox <loop> lets a loop written in shell read what the person sent: one line per entry, marked read. Only lines the board signed for this loop that answer the present asking are printed; --json shows every entry with signed and stale.
  3. A new page, "Monitor a Ralph loop or any shell loop", holds a worked loop.sh built on emit and inbox.
  4. A tab in the background shows how many loops wait in its title and, where allowed through the button in the footer, in a browser notification.
  5. The MCP server is an extra: uv tool install 'loopcaptain[mcp]'. A plain install is 21 packages and 12 MB, with the extra 36 packages and 28 MB.

Why

These are the four items of docs/BACKLOG.md. What waits was seen only on the board; a shell loop could report with emit and could not read its inbox, so the shell route the README names was half a route; a tab that was not in front was never drawn again, so its count stayed stale; and the MCP SDK came with every install though only a loop driven by an agent session uses it.

What it costs

loopcaptain mcp on an install without the extra ends with one line naming the install command. An agent session set up against a plain install has to be reinstalled with the extra: the commit is marked breaking.

Done when

  • A test fails without this change, and make check is green (697 tests). One test runs the loop.sh of the docs as printed: two rounds, a note handed to the agent, a stop taken.
  • Looked at for real: status against a board's loops; in Chrome, with the tab made to read as hidden, a second loop asked, the title went from (1) to (2) without the page being drawn again and one notification was made; the wheel installed into clean environments with and without the extra, loopcaptain mcp answering with the one line without it. The browser's own permission prompt and the system's notification are listed in .agent/DEFERRED_VERIFICATION.md.
  • Text, models and schema of the standard agree (make schema), if the protocol changed. It did not.
  • feat, fix and perf subjects read as lines of release notes; a decision has its section in docs/ARCHITECTURE.md. No new decision: the commands read what the board reads, and the notification is made by the page's own script.
  • Nothing names a company, a client or a real loop.
  • The title and this text describe the change, not the conversation that led to it.

… its inbox

- What waits for a person was seen only on the board. `loopcaptain
  status` prints one line per watched loop, what needs the person
  first: status, round, last line and what the loop asks.
- A loop in shell could report with `emit` and had no way to read what
  the person sent. `loopcaptain inbox <loop>` prints it, one line each,
  and marks it read. It prints only lines the board signed for this
  loop that answer the present asking, so a script cannot take a
  forged stop by mistake; `--json` shows every entry.
- The docs gain a worked `loop.sh` for a Ralph loop, which a test runs
  as printed: it reports two rounds, hands a note to the agent and
  takes a stop.
- A tab that is not in front was never drawn again, so the count in
  its title stayed as it was and a loop could wait unseen for hours.
- The pulse the page polls now carries how many loops wait. A tab in
  the background puts that count in its title, and shows a browser
  notification when it rises, where the person allowed one through
  the button in the footer.
- A tab that comes back in front draws what changed at once.
- Everything stays on this machine: the notification is made by the
  page's own script, and no page loads anything from another origin.
- The MCP SDK came with every install though only a loop driven by an
  agent session uses it: a plain install is 21 packages and 12 MB
  without it, 36 packages and 28 MB with it.
- `loopcaptain mcp` on an install without the extra ends with one line
  that names the install command, and `mcp-config` says the same
  beside the block it prints. The board, the helper, `emit`, `inbox`
  and every other command need nothing more than before.

BREAKING CHANGE: `loopcaptain mcp` needs the package installed as
`loopcaptain[mcp]`. An agent session set up against a plain install
gets the one-line message until it is reinstalled with the extra.
…ure (#36)

* docs(site): give a search result and a shared link a title, a sentence and a picture

- The site's pages carried no card data, so a shared link showed the
  host's generic card, and most page titles were one or two words
  ("Setup", "The board") that say nothing in a search result. Every
  page now has a title that names what it is about, Open Graph and
  card tags, and a picture; the first page also says what the project
  is as structured data.
- The site loaded its fonts from another host, while the board vendors
  its font and loads nothing from anywhere. The site now uses the
  reader's own fonts.
- A page of questions and answers puts into words what people search
  for: what an agent loop is, how to monitor, stop and steer one, which
  agents work, what leaves the machine.

* docs(cli): describe every argument, and say server where it said door

- The generated command reference had eleven arguments without a
  description, wrote "Mcp" for MCP, and did not list the events `emit`
  takes. Every argument has one now, the first letter alone is
  capitalised, and `emit` names its events.
- "Door" stood for the two ways a loop writes its files. A reader new
  to the project met it in the MCP reference and the standard with
  nothing to say what a door is. Those texts now say script, session
  and MCP server.

* feat(release): print a commit's reasons below its line of the release notes

- A release note was one subject per commit: what changed, never why,
  though every commit says why in its bullets.
- The notes now print up to six bullets of a commit's body below its
  subject. Check boxes and text that is no bullet are left out.

---------

Co-authored-by: danielvogler <danielvogler@users.noreply.github.com>
@danielvogler
danielvogler merged commit 1099c2c into main Nov 19, 2026
8 checks passed
@danielvogler
danielvogler deleted the feat/terminal-commands branch November 19, 2026 16:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant