Loopmaid

Loopmaid is a rendering surface for agentic coding loops. Agents create loops from Mermaid flowcharts, then emit events with the current Mermaid node id and JSON variables. Viewer pages poll every five seconds, highlight the current step when possible, and let people click through the event timeline.

Install

bun add --global loopmaid
loopmaid server start
loopmaid agent install opencode

The server command starts Loopmaid in the background at http://localhost:9393 and is safe to run again when the server is already running. Data and logs are stored under ~/.config/loopmaid. Restart OpenCode after installing the plugin.

For local development, run bun install, bun link, and bun run dev.

Run On Tailscale

Set the host name in .env:

HOST=your-tailnet-host.example.ts.net

Build and serve the production app:

bun run serve

Then open http://$HOST:9393 from a device on the tailnet.

Storage

Loopmaid uses Drizzle with Bun SQLite. The installed server stores data at ~/.config/loopmaid/loopmaid.sqlite; the development server uses ./data/loopmaid.sqlite.

Override the database path with:

LOOPMAID_DB_PATH=/path/to/loopmaid.sqlite

API

Create a loop:

curl -X POST http://localhost:9393/api/loops \
  -H 'content-type: application/json' \
  --data '{"title":"Agent loop","mermaid":"flowchart TD\n  start[Start] --> edit[Edit] --> test[Test] --> done[Done]","variables":{"attempt":1}}'

Append a timeline event:

curl -X POST http://localhost:9393/api/loops/{id}/events \
  -H 'content-type: application/json' \
  --data '{"activeNodeId":"test","variables":{"attempt":2,"status":"running"},"message":"Running checks"}'

Read a loop snapshot:

curl http://localhost:9393/api/loops/{id}

The viewer URL for a loop is /loop/{id}.

OpenCode Plugin

The repo ships an OpenCode plugin at opencode/loopmaid-plugin.ts.

Install it globally for every project:

loopmaid agent install opencode

The install command copies the plugin into ~/.config/opencode/plugins/loopmaid-plugin.ts. Restart OpenCode after installing it.

Use loopmaid agent install opencode --project to install only in the current project's .opencode/plugins directory. Use loopmaid agent status opencode to inspect the global installation and loopmaid agent uninstall opencode to remove it. Both commands also accept --project.

Set LOOPMAID_URL if Loopmaid is not running at http://localhost:9393.

The plugin exposes:

• loopmaid_create_loop
• loopmaid_update_loop, called for every visited node. Decision nodes include their selected outcome in the timeline.

Dependencies

JavaScript dependencies are managed with Bun.