loopback

# Loopback

**Pin feedback on your live app. Any coding agent fixes it. The pin turns green.**

Loopback is the interactive feedback layer between real product usage and your
coding agents: one script tag makes any web app commentable
(Vercel-toolbar-style toolbar, element-anchored pins), every pin auto-captures
the *functional* context — failing requests **with response bodies**, console
trail, the route journey that led there, LLM run metadata, typed repro steps —
and lands in one project-tagged queue that **Claude
Code, Codex, and Gemini CLI** all work over MCP. When an agent's fix is
verified, the pin turns green on the page, live.

[![CI](https://github.com/joshidikshant/loopback/actions/workflows/ci.yml/badge.svg)](https://github.com/joshidikshant/loopback/actions/workflows/ci.yml)

![The loop, closed: a green verified pin on the form claude-code fixed (PR linked), an amber open pin on the AI answer, and the Loopback panel listing both](assets/loopback-widget-demo.png)

*Seeded demo capture (generated by `scripts/screenshot.mjs`): the contact form's
backend bug pinned, claimed by claude-code, marked fixed with a linked change,
verified — pin and badge green. The wrong AI answer is still amber/open.*

## Why

Coding agents can fix anything you can describe — but the loop back from real
usage is missing. You notice a broken flow, screenshot it, re-describe it in a
prompt, paste console output, explain which project it belongs to. Every time,
for every agent. Vercel's comments have no public API; Claude Design's
anchored comments are artifact-scoped; error trackers don't know your queue.

Loopback is that missing loop, built as a **hub**:

- **One instance, all projects.** Every item is tagged with a `project` slug in
  one shared SQLite DB (`~/.loopback/loopback.db`). Agents registered once per
  machine; consuming repos add only a widget tag and a slug.
- **One queue, all agents.** MCP is the interface, so Claude Code, Codex, and
  Gemini CLI are peers — same tools, same playbook, same audit trail.
- **A pin is an anchor, not a scope.** Pin a "broken" contact form and the
  agent gets the failing `POST` with its 500 response body — a frontend pin
  carries the backend root cause. Pin an AI answer and the run metadata
  (`run_id`, `model`, `trace_url`) rides along.

```
            CAPTURE                          THE HUB                            AGENTS
 ┌───────────────────────────┐   ┌─────────────────────────────┐   ┌─────────────────────────┐
 │ widget pin on any app     │──►│  loopback-mcp-server        │◄──│ Claude Code             │
 │  · console + network ride │   │   one shared SQLite DB      │   │ Codex          (peers)  │
 │  · 500 bodies captured    │   │   ~/.loopback/loopback.db   │   │ Gemini CLI              │
 │  · AI run context         │   │                             │   └────────────┬────────────┘
 ├───────────────────────────┤   │  stdio (per-agent spawn)    │                │
 │ POST /ingest              │──►│  --http on 127.0.0.1:7077   │     list → claim → fix →
 │  · CI hooks, cron,        │   │   (required for widgets)    │     link change → fixed →
 │    Sentry/PostHog pollers │   │                             │     verify → resolve
 └───────────────────────────┘   └──────────────┬──────────────┘                │
                                                │                               │
              pins turn green on the page ◄─────┴───── status write-back ◄──────┘
```

Run it per-invocation over **stdio** (each agent spawns it; same DB = same
queue) or as one long-running **`--http`** service on `127.0.0.1:7077`
(required for widgets — keep it alive with pm2/launchd/systemd:
[integrations/keep-alive.md](integrations/keep-alive.md)).

## Quickstart (see the whole loop in 2 minutes)

Requires Node **≥ 22.13** (built-in `node:sqlite` — zero native deps).

```bash
git clone https://github.com/joshidikshant/loopback && cd loopback
npm install                    # prepare script builds dist/
node dist/index.js --http      # the hub, on 127.0.0.1:7077
node demo/serve.mjs            # demo app on 127.0.0.1:5173 (broken backend + wrong AI answer)
```

Open http://127.0.0.1:5173 → submit the form (it fails politely) → **✦
Loopback → Pin feedback on an element** → click the submit button → Send. The
form shows the captured failed request. Then tell any connected agent *"work
the feedback queue for acme-demo"* — or watch the item at
http://127.0.0.1:7077/queue and be the agent yourself over MCP. When it's
resolved, the open page announces it and the pin goes green.

## Install once per machine

Register the MCP server + instructions once per agent; after this, new projects
are a two-minute `init`. All three are equal citizens — full per-agent pages in
[`integrations/`](integrations/):

| Agent | MCP registration | Instructions/skill channel |
|---|---|---|
| **Claude Code** | `claude mcp add --scope user loopback -- npx -y loopback-mcp-server` — or the plugin: `claude plugin marketplace add joshidikshant/loopback && claude plugin install loopback@loopback` | `@AGENTS.md` import in CLAUDE.md + skill at `.claude/skills/loopback/` → [claude.md](integrations/claude.md) |
| **Codex** | `~/.codex/config.toml`: `[mcp_servers.loopback]` `command`/`args` (or project-scoped `.codex/config.toml`) | AGENTS.md read natively + native SKILL.md at `.agents/skills/loopback/` → [codex.md](integrations/codex.md) |
| **Gemini CLI** | `~/.gemini/settings.json` → `mcpServers.loopback` | AGENTS.md via `context.fileName` + `@AGENTS.md` in GEMINI.md + `/loopback` command → [gemini.md](integrations/gemini.md) |

All three also accept the long-running instance over streamable HTTP
(`http://127.0.0.1:7077/mcp`) instead of spawning — see the per-agent pages.

## Integrate a new project (2 minutes)

1. **Central instance running** (once per machine): `loopback-mcp-server
   --http`, kept alive per [keep-alive.md](integrations/keep-alive.md).
2. **Paste the widget tag** into the app, with your slug
   ([template](integrations/widget-embed.html)):
   ```html
   <script src="http://127.0.0.1:7077/widget.js"
           data-project="my-app" data-endpoint="http://127.0.0.1:7077"></script>
   ```
3. **From the repo root:**
   ```bash
   npx loopback-mcp-server init --project my-app --write
   ```
   One canonical playbook
   ([integrations/instructions-src.md](integrations/instructions-src.md)) is
   rendered into every agent's native mechanism: the **AGENTS.md** queue
   section (canonical; Codex + Gemini read it natively), `@AGENTS.md` imports
   in CLAUDE.md and GEMINI.md, the **same SKILL.md** installed for Claude
   (`.claude/skills/`) and Codex (`.agents/skills/`), MCP registration for all
   three (`.mcp.json`, `.gemini/settings.json`, `.codex/config.toml`), and a
   `/loopback` Gemini command. Merges are non-destructive and idempotent —
   re-run it anytime.
4. **In any of the three agents, say:** *"work the feedback queue for
   my-app"* — or say nothing: the skill descriptions and AGENTS.md section make
   feedback-ish requests trigger the loop on their own.

## Using it day to day

With the hub running (`loopback-mcp-server --http`), everything happens on two
surfaces and one sentence to an agent:

| I want to… | Do this |
|---|---|
| **Report something** on a page with the widget | Click **✦ Loopback → Pin feedback on an element**, click the thing, describe it. Failing requests, console, and AI run context attach themselves. |
| **See the queue** | `http://127.0.0.1:7077/queue` — filter with `?project=<slug>`, click a row for a quick read |
| **Read everything on one item** | Click its id → `http://127.0.0.1:7077/queue/<id>`. Deep-linkable: paste it to a teammate or an agent. |
| **Comment or change status myself** | On the item view — plain forms, no agent needed |
| **Get it fixed** | In the repo, tell any agent: *"work the feedback queue for `<slug>`"* |
| **Watch it close** | The pin on your page turns green and announces itself; the item shows the commit/PR |
| **File from a script or CI** | `POST /ingest` with `{"project","type","title","body"}` |

Writes that change an item (comment, status) are **same-origin only** — see
[Security](#http-surface---http-port-7077--loopback_http_port---port) below.

## Giving feedback *about* Loopback

Loopback is its own reference integration — it eats its own dog food, and so
can you. Four ways in, from most to least convenient:

1. **Pin it on the queue page.** With the hub running, open
   `http://127.0.0.1:7077/queue` — the capture widget is embedded there with
   `data-project=loopback`. Click **✦ Loopback → Pin feedback on an element**,
   click whatever is wrong, describe it. Same loop as any other project.
2. **Tell an agent.** In this repo (self-onboarded with its own `init`), say
   *"file feedback for loopback: <what's wrong>"* — the skill and AGENTS.md
   section are already installed for Claude, Codex, and Gemini.
3. **`curl` it** from anywhere:
   ```bash
   curl -X POST http://127.0.0.1:7077/ingest -H 'Content-Type: application/json' \
     -d '{"project":"loopback","type":"ux","severity":"p2",
          "title":"…","body":"what happened / what you expected"}'
   ```
4. **GitHub issues** for anything a stranger should see:
   <https://github.com/joshidikshant/loopback/issues>.

Then work it like any queue: *"work the feedback queue for loopback"*. Every
Loopback defect in this repo's history was filed and closed exactly this way.

## The dashboard

`/queue` is a **React + shadcn app** (`dashboard/`, built with the real `shadcn`
CLI). Filter by clicking status tiles or any project / severity / type cell —
filters compose and live in the URL, so every view is linkable. Open an item to
read everything captured, **edit** it (title, body, severity, type — every change
lands on the audit trail), comment, change status, and **attach files**.

Attachments declare *why* they exist, because that decides what an agent does:

| Intent | Meaning |
|---|---|