tyrekick

# Tyrekick

**Kick the tyres before you ship it.** Get people you trust to review your
AI-built prototype — and let your coding agent act on what they say.

[![npm version](https://img.shields.io/npm/v/tyrekick?label=npm)](https://www.npmjs.com/package/tyrekick)
[![gzip size](https://img.shields.io/badge/gzip-~14%20KB-brightgreen)](README.md#how-it-works)
[![license: MIT](https://img.shields.io/npm/l/tyrekick)](LICENSE)
[![MCP server](https://img.shields.io/badge/MCP-server-8b5cf6)](mcp/)

Reviewers pin comments directly on the live page — no account, no training.
Your coding agent pulls them back over MCP with the exact element, its visible
text, the section heading, and any page errors attached, fixes what was
flagged, and marks it resolved. The reviewer's pin turns green with a note.
You never retype feedback into a prompt again.

![A reviewer pins a comment on the live demo; an agent reads it over MCP, ships the fix, resolves with a note — and the reviewer's pin turns green.](docs/demo.gif)

**▶ [Try the live demo](https://wander-demo.pages.dev/demo/)**  ·  [Quickstart](docs/QUICKSTART.md)  ·  [Docs](docs/)  ·  ["The Outer Loop" — why this exists](docs/essays/the-outer-loop.md)

*Real footage: that comment was pinned on the live demo, fixed by an agent, and the pin turned green — no retyping, no tracker, no accounts.*

## How it works

```
 reviewer's browser              destination YOU own              your coding agent
┌──────────────────┐   POST    ┌────────────────────┐    MCP    ┌─────────────────┐
│ pin a comment on │ ────────► │ Discord webhook or │ ◄───────► │ "fix the open   │
│ the live page    │           │ your CF Worker     │           │  feedback"      │
└──────────────────┘           └────────────────────┘           └─────────────────┘
```

The widget is a single ~14 KB (gzipped) script with zero dependencies, rendered in Shadow DOM so it can't fight your page. There is no Tyrekick backend, no accounts, and nothing phones home — feedback POSTs straight from the reviewer's browser to a destination **you** own. It exists for the moment an agent-built prototype needs more than one pair of eyes: instead of pasting screenshots into group chats and losing the replies, every comment arrives structured, versioned, and pinned to the exact spot.

Pins stay on the page after you leave a comment (dimmed until you interact) — hover one to see its text, click it to open the thread right there, with reply, retry, and discard actions at the pin. Reviewers also get a comment drawer (a right-hand overview listing every pin with its text — click one to jump back to that spot, or hide pins entirely), draft recovery, and full keyboard/touch support (Cmd/Ctrl+Enter sends). With `persist: true` (the default), localStorage is only used to recover unsent work across reloads — comments that couldn't be delivered come back after a reload with Retry and Discard buttons, re-pinned to the element they were about even if the window size changed.

> **Agents:** installing Tyrekick into a project? Use the [`make-reviewable` skill](skills/make-reviewable/SKILL.md) — one sentence and it hosts the page if needed, picks a destination, deploys the worker, installs the widget, wires MCP, and drafts the ask to send reviewers — or follow [`AGENTS.md`](AGENTS.md) step by step.

**Full documentation** lives in [`docs/`](docs/): [quickstart](docs/QUICKSTART.md) · [getting started](docs/getting-started.md) · [configuration](docs/configuration.md) · [the reviewer experience](docs/reviewing.md) · [destinations](docs/destinations.md) · [the agent loop](docs/agent-loop.md) · [payload reference](docs/payload.md) · [troubleshooting & FAQ](docs/troubleshooting.md)

**Sharing a prototype publicly?** Start with [taking a prototype public](docs/going-public.md), then the per-capability guides: [rate limiting](docs/rate-limiting.md) · [shared review](docs/shared-review.md) · [AI auto-reply](docs/ai-auto-reply.md).

## 60-second quickstart (Discord)

The fastest path is a Discord channel you control — the taster that proves
feedback flows somewhere you own. The full product (persistence, statuses,
your agent closing the loop over MCP) lives on the
[worker destination](#the-agent-loop-mcp) below.

**One command** (from your project folder):

```bash
npx tyrekick init
```

It asks for your webhook URL, injects the script tag, and sends a test comment.
Or by hand:

1. In Discord, open **Server Settings → Integrations → Webhooks → New Webhook**, pick a channel, and **Copy Webhook URL**.
2. Paste that URL into the snippet below and drop it before `</body>` on your prototype:

```html
<script
  src="https://cdn.jsdelivr.net/npm/tyrekick@latest/dist/tyrekick.js"
  data-webhook="https://discord.com/api/webhooks/XXXX/YYYY"
  data-app-version="v0.1"
  data-transport="discord"
  data-project-name="My Prototype"
  data-accent="#4f46e5"
  data-position="bottom-right"
  data-branding="true"
></script>
```

The IIFE build auto-initialises from its own `<script>` tag's `data-*` attributes on `DOMContentLoaded`. Reviewers get a "Give feedback" button in the corner; each comment lands in your Discord channel as a readable message.

> Only `data-webhook` and `data-app-version` are required. Everything else is optional and falls back to the defaults in the [configuration table](#configuration).

## Self-hosting / owned storage

Discord is the frictionless default, but if you want the data in storage you own, use a JSON transport (`transport: "json"`, the default) pointed at an endpoint that persists the payload.

- **Cloudflare template (TypeScript):** see [`destinations/cloudflare`](destinations/cloudflare) for a deployable Worker that receives the [v2 payload](#payload-schema-v2), validates it, and writes it to storage you control. It's a good place to add spam validation since the code is yours.
- **Same-origin Pages Function:** if your prototype is hosted on Cloudflare Pages, drop a Pages Function at the same origin (e.g. `/api/feedback`) and set `webhook` to that relative/same-origin URL. Same-origin means no CORS setup at all.

Any CORS-enabled endpoint or form backend works too — with `transport: "json"`, success is HTTP 2xx and, if a body is returned, it is not `{"ok":false}`.

## The agent loop (MCP)

The reason Tyrekick exists. With the Cloudflare Worker destination, feedback isn't just collected — your coding agent can **pull it, act on it, and resolve it**:

1. Deploy the worker and set a token (see [`destinations/cloudflare`](destinations/cloudflare)):
   ```bash
   wrangler deploy && wrangler secret put TYREKICK_TOKEN
   ```
2. Give your agent the pipeline (once — it works for every future session):
   ```bash
   claude mcp add tyrekick \
     --env TYREKICK_URL=https://tyrekick-feedback.YOUR.workers.dev \
     --env TYREKICK_TOKEN=your-token \
     -- npx tyrekick-mcp
   ```
3. Close the loop with one sentence:
   > *"List the open feedback and fix what people flagged, then resolve it."*

The agent gets five tools — `list_feedback`, `get_feedback`, `triage_feedback`, `resolve_feedback`, `feedback_stats` — and each item carries the element's visible text (greppable in your source), the nearest heading, the route, the viewport, and any uncaught page errors. A comment like *"this button does nothing"* arrives as:

```
element: <button> "Search trips"
under: "Plan your escape" · landmark: main > section#planner
page_errors: 1
> This button does nothing when I click it
```

That's a better bug report than most humans write. Full details in [`mcp/README.md`](mcp/README.md).

## Shared review (reviewers see each other)

By default a review is several private conversations: each reviewer sees their
own pins, and the comments meet at your destination. Set a **review key** and
the page itself becomes the shared surface — everyone sees everyone's pins,
read-only, with attribution. Reviewers stop reporting the same thing four times.

```bash
npx wrangler secret put TYREKICK_REVIEW_KEY   # on your worker; any long random string
```

```html
<script
  src="https://cdn.jsdelivr.net/npm/tyrekick@latest/dist/tyrekick.js"
  data-webhook="https://your-worker.workers.dev/feedback"
  data-app-version="v0.1"
  data-project-name="my-prototype"
  data-review-key="the-same-long-random-string"
></script>
```

**Read this before switching it on.** The key ships inside your page, so it is
public to anyone holding the review link: *anyone who can open the prototype can
read every comment on it, including reviewer names.* That is the right trade for
a private link you sent to five people you trust, and the wrong one for a public
URL. There is no per-reviewer identity to scope it more finely — reviewers never
log in, which is the point. Rotate the secret to revoke access.

What it does and doesn't do:

- **Read-only.** You can see and reply to another reviewer's comment; replies
  travel to your destination like any other comment, not peer-to-peer. There is
  no live presence and no on-page threading between reviewers.
- **Declining hides.** A comment you decline (via MCP or the API) disappears
  from *everyone's* page — that is how you clear spam and noise. Its author
  still sees the outcome on their own pin.
- **Project-scoped.** One worker can serve several prototypes; a review key
  only ever reads the `projectName` it was asked for. Set an explicit, stable
  `projectName` — the `document.title` fallback will fork your feedback stream
  the first time you edit the title.
- **Worker only.** Discord is write-only by design and has no shared view.
- **What other reviewers never see:** your user agent, screen or device
  fingerprint, the prototype's page errors, the full URL (share links can carry
  query-string secrets), or your session id.

## AI auto-reply (optional)

Set an Anthropic API key on your worker and each ingested comment gets one
short, friendly acknowledgement — labelled 🤖, shown only in the reviewer's
own thread — while the pin stay