agent-feedbacker 0.0.0-stage → 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "feedbacker",
+  "owner": {
+    "name": "Pavel Polivka"
+  },
+  "metadata": {
+    "description": "Feedbacker: review a coding agent's changes across several git repos in a local MR-style page."
+  },
+  "plugins": [
+    {
+      "name": "feedbacker",
+      "source": "./",
+      "description": "Review an agent's changes across several git repos in a local MR-style page and send line comments back to it."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "feedbacker",
+  "version": "0.1.0",
+  "description": "Review an agent's changes across several git repos in a local MR-style page and send line comments back to it.",
+  "author": { "name": "Pavel Polivka" },
+  "repository": "https://github.com/PavlikPolivka/feedbacker",
+  "license": "MIT"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "feedbacker": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/feedbacker.mjs", "mcp"]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pavel Polivka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# Feedbacker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local, merge-request-style review page for coding agents. The agent passes the git repos it changed, a summary and optionally some questions. You see the diffs of **all of them on one page**, comment on lines, answer the questions, and click **Approve** or **Request changes**. The agent gets your feedback back as markdown it can act on.
+
+- **Multi-repo and worktrees**: any repos anywhere on disk, each with its own base; `--worktrees` pulls in every git worktree of a repo, so parallel agents' work is reviewed together.
+- **Simple**: one Node process with no runtime dependencies; nothing to install or build to use it. The page is a small React 19 app whose bundle (with highlight.js) is committed in `src/dist/`.
+- **Local**: binds to `127.0.0.1` with a random token in the URL. Nothing leaves your machine, and git is only read.
+- **Three ways in**: a Claude Code plugin (MCP tool + skill), a plain MCP server for other agents, and a CLI for anything with a shell.
+
+![Review page](docs/screenshot.png)
+
+## Install
+
+### Claude Code plugin
+
+```bash
+claude plugin marketplace add PavlikPolivka/feedbacker
+claude plugin install feedbacker@feedbacker
+```
+
+This gives Claude:
+
+- the MCP tool `request_review` (it shows up as `mcp__plugin_feedbacker_feedbacker__request_review`)
+- the skill `/feedbacker:review`, which tells Claude when and how to ask for a review
+
+Then just say "let me review it" or run `/feedbacker:review`. To try it from a checkout without installing: `claude --plugin-dir /path/to/feedbacker`.
+
+### Any MCP client
+
+```json
+{
+  "mcpServers": {
+    "feedbacker": { "command": "npx", "args": ["-y", "agent-feedbacker", "mcp"] }
+  }
+}
+```
+
+### CLI
+
+```bash
+npm install -g agent-feedbacker      # or run it once with: npx agent-feedbacker
+```
+
+The npm package is `agent-feedbacker`; the command is `feedbacker`. Node 22 or newer; git on `PATH`. From a checkout, `node bin/feedbacker.mjs` works too.
+
+## Use
+
+```bash
+feedbacker ~/Projects/api ~/Projects/web@main \
+  -m "Bind the API to localhost; document the port" \
+  -q "Should the port also be a CLI flag?"
+```
+
+- `repo` diffs the working tree (staged, unstaged and untracked files) against `HEAD`.
+- `repo@base` diffs against any commit, branch or tag, so work the agent already committed is included. With a branch, the diff starts where `HEAD` forked from it (like a merge request), so newer commits on that branch don't show up reversed.
+- A worktree path works like any repo. `-w` / `--worktrees` adds every worktree of each repo (main and linked, each labelled with its branch), all against the same base:
+
+  ```bash
+  feedbacker ~/Projects/api@main --worktrees   # main checkout + every agent's worktree
+  ```
+- The command blocks until you submit, then prints the feedback (`--json` for JSON) and exits 0. Exit 2 means there was nothing to review.
+- `feedbacker list` prints the URLs of reviews waiting for you, for when the browser didn't open (MCP clients usually hide a server's output).
+- `--no-open` only prints the URL; `--port` fixes the port.
+
+In the browser:
+
+- Click a line number to comment on that line (a highlighter "+" shows where); shift-click a second one to comment on a range. Ctrl+Enter saves, Esc cancels.
+- With several repos, the picker in the top bar switches between all of them and a single one (the summary, questions and your comments in other repos stay). The top bar also shows the size of the change and keeps **Approve** and **Request changes** in reach; files can be collapsed, and the file tree shows where your comments are.
+- Comments, answers and the general comment are kept in the browser's local storage until you submit, so a refresh loses nothing.
+- **Approve** or **Request changes** sends everything to the agent and closes the server.
+
+## MCP tool
+
+`request_review`:
+
+| Argument | Type | |
+|---|---|---|
+| `repos` | `[{ path, base?, worktrees? }]` | Required. Absolute paths; `base` defaults to `HEAD`; `worktrees: true` adds all worktrees of that repo. |
+| `summary` | string | Shown at the top of the page. |
+| `questions` | string[] | Shown with an answer box each. |
+
+It blocks until the user submits (Claude Code keeps long MCP calls open; it sends progress notifications every 30 s for clients that need them) and returns markdown like:
+
+````markdown
+# Review feedback
+
+Verdict: **changes requested**
+
+## General
+
+Almost there.
+
+## Answers
+
+**Q: Should the port also be a CLI flag?**
+
+No, env is enough.
+
+## Comments
+
+### /home/me/Projects/api
+
+**src/server.ts:6** (new side)
+
+```diff
++  server.listen(port, "127.0.0.1");
+```
+
+Make the host configurable too.
+````
+
+Each comment carries the code it refers to, so line numbers drifting doesn't lose the context. Cancelling the tool call closes the review page.
+
+## How it works
+
+```
+agent ──request_review / CLI──▶ feedbacker ──git diff per repo──▶ review in memory
+feedbacker ──opens──▶ http://127.0.0.1:PORT/?t=TOKEN ──you submit──▶ feedbacker
+feedbacker ──markdown (tool result / stdout)──▶ agent
+```
+
+| File | |
+|---|---|
+| `src/core.mjs` | Reads diffs (`git diff <base>` plus untracked files), parses them, serves the page, formats feedback. |
+| `src/page.html` | Page shell: styles, and the bundle from `src/dist/`. |
+| `src/ui/` | The review page in React 19 (JSX): diff table, inline comments, questions, submit; highlight.js for syntax, `styles.css` for the look (light and dark, colour tokens at the top). |
+| `src/dist/` | The committed bundle (JS, CSS and fonts), built from `src/ui/` by `build.mjs` (esbuild). |
+| `src/mcp.mjs` | Minimal MCP server over stdio (JSON-RPC), one tool. |
+| `bin/feedbacker.mjs` | CLI: review, `list`, `mcp`. |
+| `skills/review/SKILL.md`, `.mcp.json`, `.claude-plugin/` | The Claude Code plugin and its marketplace entry. |
+
+Open reviews write a small file (URL, repos, pid) to `$XDG_STATE_HOME/feedbacker/` (default `~/.local/state/feedbacker/`, mode 0600) and remove it when they finish; `list` reads them.
+
+## Development
+
+```bash
+pnpm install     # dev dependencies only: React, highlight.js, fonts, esbuild
+pnpm build       # after changing src/ui: rebuilds src/dist (commit it)
+pnpm test
+```
+
+Using Feedbacker needs none of this; only working on the page does. A test fails when `src/dist` doesn't match `src/ui`.
+
+The tests use real temporary git repos. They cover diff parsing, the HTTP server, the MCP protocol over stdio, and an end-to-end run that drives the page in headless Chromium (skipped when no Chromium is found; set `CHROMIUM=/path` to pick one).
+
+CI runs the tests on Node 22 and 24 for every push and pull request (`.github/workflows/ci.yml`).
+
+### Releasing
+
+Publishing to npm is done by GitHub Actions (`.github/workflows/publish.yml`) with npm trusted publishing, so no npm token is stored anywhere and each version gets a provenance statement.
+
+1. Bump `version` in `package.json` (and `.claude-plugin/plugin.json`), commit, push.
+2. Create a GitHub release with the tag `vX.Y.Z` matching that version: `gh release create v0.2.0 --generate-notes`.
+3. The workflow checks the tag, runs the tests and publishes.
+
+One-time setup: on npmjs.com, add a trusted publisher for the package (GitHub Actions, repository `PavlikPolivka/feedbacker`, workflow `publish.yml`). npm only offers that once the package exists, so the very first version is published by hand with `npm publish --access public`.
+
+Plans: [ROADMAP.md](ROADMAP.md).
+
+## Licence
+
+MIT. The bundle in `src/dist/` includes React, ReactDOM and scheduler (MIT), highlight.js (BSD-3-Clause), and the Atkinson Hyperlegible Next and JetBrains Mono fonts (OFL-1.1); their licences are in `src/dist/THIRD_PARTY_LICENSES.txt`. The fonts are served locally, so the page never loads anything from the internet.

package/bin/feedbacker.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Feedbacker CLI: `feedbacker [repos...]` opens a review page and prints the
+// feedback when the user submits; `feedbacker mcp` runs the MCP server.
+
+import { buildReview, hasChanges, listReviews, startReview, toMarkdown } from '../src/core.mjs';
+import { runMcp } from '../src/mcp.mjs';
+
+const USAGE = `Usage: feedbacker [options] [repo[@base] ...]
+       feedbacker list
+       feedbacker mcp
+
+Opens a review page for the changes in each repo (default: current directory)
+and prints the feedback to stdout when the user submits.
+
+  repo[@base]        Repo or worktree path; diff the working tree (including
+                     untracked files) against base. Default base: HEAD. With a
+                     branch as base, the diff starts where HEAD forked from it.
+  -w, --worktrees    Also review every other worktree of each repo.
+  -m, --summary TXT  What the agent changed, shown at the top.
+  -q, --question TXT A question for the user (repeatable).
+  --json             Print JSON instead of markdown.
+  --port N           Port to listen on (default: random).
+  --no-open          Don't open the browser; only print the URL to stderr.
+  -h, --help         Show this help.
+
+  list               Show the URLs of reviews that are waiting for you.
+  mcp                Run as an MCP server on stdio (tool: request_review).`;
+
+function fail(msg) {
+  console.error(`feedbacker: ${msg}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const opts = { repos: [], questions: [], summary: '', worktrees: false, json: false, port: 0, open: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      if (i + 1 >= argv.length) fail(`${a} needs a value`);
+      return argv[++i];
+    };
+    if (a === '-h' || a === '--help') { console.log(USAGE); process.exit(0); }
+    else if (a === '-m' || a === '--summary') opts.summary = next();
+    else if (a === '-q' || a === '--question') opts.questions.push(next());
+    else if (a === '-w' || a === '--worktrees') opts.worktrees = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--port') opts.port = Number(next());
+    else if (a === '--no-open') opts.open = false;
+    else if (a.startsWith('-')) fail(`unknown option ${a}\n\n${USAGE}`);
+    else opts.repos.push(a);
+  }
+  if (!opts.repos.length) opts.repos.push('.');
+  return opts;
+}
+
+// Exit cleanly on signals so open reviews remove their state files.
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => process.exit(130));
+
+const argv = process.argv.slice(2);
+if (argv[0] === 'mcp') {
+  runMcp();
+} else if (argv[0] === 'list') {
+  const reviews = listReviews();
+  if (!reviews.length) console.log('No reviews waiting.');
+  for (const r of reviews) console.log(`${r.url}\n  ${r.started}  ${r.repos.join(', ')}${r.summary ? `\n  ${r.summary}` : ''}`);
+} else {
+  const opts = parseArgs(argv);
+  const review = buildReview(opts);
+  for (const r of review.repos) if (r.error) console.error(`feedbacker: ${r.path}: ${r.error}`);
+  if (!hasChanges(review) && !review.questions.length) {
+    console.error('feedbacker: no changes to review');
+    process.exit(2);
+  }
+  const { url, feedback } = await startReview(review, { port: opts.port, open: opts.open });
+  console.error(`feedbacker: waiting for review at ${url}`);
+  const fb = await feedback;
+  process.stdout.write(opts.json ? JSON.stringify(fb, null, 2) + '\n' : toMarkdown(review, fb));
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "agent-feedbacker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A local merge-request-style review page that coding agents open to collect your line comments and answers, across several git repos.",
+  "type": "module",
+  "bin": {
+    "feedbacker": "bin/feedbacker.mjs"
+  },
+  "files": [
+    "bin",
+    "src/*.mjs",
+    "src/page.html",
+    "src/dist",
+    "skills",
+    ".claude-plugin",
+    ".mcp.json"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PavlikPolivka/feedbacker.git"
+  },
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "code-review",
+    "diff",
+    "agent"
+  ],
+  "author": "Pavel Polivka",
+  "license": "MIT",
+  "devDependencies": {
+    "@fontsource-variable/atkinson-hyperlegible-next": "^5.3.0",
+    "@fontsource-variable/jetbrains-mono": "^5.3.0",
+    "esbuild": "^0.28.2",
+    "highlight.js": "^11.12.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "homepage": "https://github.com/PavlikPolivka/feedbacker#readme",
+  "bugs": {
+    "url": "https://github.com/PavlikPolivka/feedbacker/issues"
+  }
+}

package/skills/review/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: review
+description: Ask the user to review your changes in a local merge-request-style page and get their line comments, answers and verdict back. Use when the user asks for a review ("let me review", "show me the diff", "feedbacker"), or after finishing a non-trivial change, especially one that spans several git repos, before you commit, push or call the work done.
+---
+
+# Review with Feedbacker
+
+Feedbacker opens a review page in the user's browser with the diffs of the repos you pass. The user comments on lines, answers your questions and clicks **Approve** or **Request changes**. You get their feedback back as markdown.
+
+## How
+
+1. List **every git repo and worktree you changed in this session**, as absolute paths. Include repos outside the current directory. If the work is spread over several worktrees of one repo (e.g. parallel agents), pass one of them with `"worktrees": true` instead of listing each.
+2. Pick a base per repo:
+   - Uncommitted changes only: leave `base` out (it defaults to `HEAD`).
+   - You committed during the session: use the commit the session started from (`git log` to find it) or the branch you forked from, e.g. `main`.
+3. Call the `request_review` tool of the `feedbacker` MCP server with:
+   - `repos`: `[{ "path": "/abs/path", "base": "main", "worktrees": false }, ...]`
+   - `summary`: two to five sentences on what you changed and why.
+   - `questions`: only real decisions you want the user to make (optional).
+4. Before the call, tell the user a review page is opening in their browser. If it doesn't appear, they can run `node "${CLAUDE_PLUGIN_ROOT}/bin/feedbacker.mjs" list` to get its URL. The tool returns once they submit, however long that takes.
+
+If the MCP tool isn't available, run the CLI in the background instead, so the shell timeout doesn't kill it, and read its output when it exits:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/feedbacker.mjs" /abs/repo-a /abs/repo-b@main \
+  -m "What changed" -q "A question?"
+```
+
+## After the review
+
+- **Changes requested:** address every comment. Each one names the repo, file, line range and the code it refers to. Answer comments you disagree with instead of silently skipping them. Then offer another review round.
+- **Approved:** carry on (commit, push, or whatever was next), taking any comments and answers into account.
+- Use the answers to your questions as decisions; don't ask them again.