{
  "markdown": "<h1 align=\"center\">Looper Loop</h1>\n\n<p align=\"center\">\n  <strong>Agentic loop that works and gets the job done</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://bun.sh/\"><img src=\"https://img.shields.io/badge/runtime-bun-fbf0df?style=flat-square\" alt=\"Bun\"></a>\n  <a href=\"https://www.typescriptlang.org/\"><img src=\"https://img.shields.io/badge/typescript-5.x-3178c6?style=flat-square\" alt=\"TypeScript\"></a>\n  <a href=\"https://modelcontextprotocol.io/\"><img src=\"https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square\" alt=\"MCP\"></a>\n  <a href=\"https://opensource.org/licenses/MIT\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square\" alt=\"MIT License\"></a>\n</p>\n\n`looperloop` runs a coding agent in a detached loop with observer agents. When both worker and observer agree the job is done - loop ends.\n\nEvery iteration of worker agent is a new conversation (which is actually great for token efficiency), in the end agent reports as \"done\" or \"continue\", its work is being reviewed by observer agents, to ensure nothing is missed.\nThis relentless process is repeated until worker and all observers align on completion of the task (or are blocked on it).\n\nThe agent flow is using **Memento** pattern, which makes it leave notes as handoff document for the next iteration.\n\n<p align=\"center\">\n  <img src=\"img/branches_view.jpg\" height=\"350\" alt=\"Branches view\" />&nbsp;\n  <img src=\"img/activity_view.jpg\" height=\"350\" alt=\"Activity view\" />\n</p>\n\n---\n\n## Quick Start\n\n### Install the Claude Code plugin\n\nAdd it directly from Claude Code marketplace:\n\n```text\n/plugin marketplace add Altair200333/looperloop\n/plugin install looperloop@looperloop\n/reload-plugins\n```\n\nAfter that, start a loop from Claude Code:\n\n```text\n/looperloop fix the failing snapshot tests -c \"max 5, opus agent, gpt reviewer\"\n```\n\nClaude Code will call the plugin MCP server, return a loop id, and open a small status page for that specific run. \nWhen the loop finishes, ask Claude for the result - it will present the user-facing summary first.\n\n---\n\n## Features\n\n| Feature | Details |\n|---------|---------|\n| Multi-provider | Worker and observers can each use Claude CLI or Codex CLI with configurable effort |\n| Detached runs | Loop state is file-based and survives editor restarts |\n| Multiple observers | Several reviewers can judge the same iteration |\n| Status UI | Local browser page with live status and **graph** view |\n| Notifications | Optional sound, toast, Telegram, and Slack messages on start and finish |\n\n---\n\n## How It Works\n\nEach normal iteration has two phases: the worker acts, then observers review. Their verdicts are merged into one decision: continue, done, dispute, or cancel.\n\n```text\n+----------------+      +----------------+      +----------------+      +----------------+\n| worker         | ---> | observers      | ---> | verdict merge  | ---> | next iter      |\n| Claude/Codex   |      | Claude/Codex   |      | continue/done  |      | or stop        |\n+----------------+      +----------------+      +----------------+      +----------------+\n```\n\nThe driver runs as its own process. The MCP server starts it, then reads state files from disk. If your editor session restarts, the loop directory still contains the prompts, worker logs, observer reviews, verdicts, branch graph, and final result.\n\nRun data lives under this path in the workspace where Claude spawned it:\n\n```text\n./looper/loop-runs/<loop-id>/\n```\n\n---\n\n## Usage\n\n### Slash command config\n\n```text\n/looperloop <task> -c \"<natural-language config>\"\n```\n\nExamples:\n\n```text\n-c \"max 3, opus agent, opus reviewer\"\n-c \"max 3, sonnet agent, opus reviewer\"\n-c \"max 3, gpt-5.5 agent, opus reviewer\"\n-c \"max 1, gpt-5.5 agent low effort, sonnet reviewer low effort\"\n```\n\n`agent` and `worker` mean the same thing. `reviewer`, `judge`, and `observer` mean the same thing.\n\n### Status and results\n\nDuring a run, the browser page shows:\n\n- current iteration and status\n- worker and observer activity summaries\n- graph/canvas view of the main loop and side branches\n- stop button for cancellation\n\nAfter a run completes, the important entry point is `looperloop_result`. It returns the final user-facing result, the result file path, the run directory, and pointers to detailed logs if you want to inspect what happened.\n\n### Notifications\n\nRegister notification targets once; they are stored globally on your machine, not inside each project.\n\nYou can tell Claude Code something like:\n\n```text\nUse looperloop to register Telegram notifications with this bot token and chat id: ...\n```\n\nor:\n\n```text\nUse looperloop to register Slack DM notifications for me with this bot token and my email: ...\n```\n\nThe plugin can also test, enable, or disable registered notification channels.\n",
  "bytes": 4784,
  "sha": "e728c22a022c76aa7b85c1dcbc40236b679b0df4a578c38a7bdce5f3ea9056f8",
  "repo_slug": "altair200333/looperloop",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_altair200333_looperloop_looper_loop_89682a83/readme"
}