agentation-wrapper

Wrap Agentation UI annotation tool with GitHub Issues integration via Cloudflare Workers.

Flow: QA annotates bugs on dev site → selects labels → issues auto-created on GitHub → devs fix with Claude Code.

Quick Start

1. Install

npm install agentation-wrapper agentation -D

2. Initialize

npx agentation-wrapper init

Generates:

• Cloudflare Worker with domain-to-repo mapping
• .env.local with webhook URL

3. Configure Worker

Edit wrangler.toml:

[vars]
DOMAIN_MAP = "localhost:org/repo,dev.myapp.com:org/myapp"
ALLOWED_ORIGINS = "http://localhost:5173,https://dev.myapp.com"

Deploy:

cd agentation-webhook
npx wrangler secret put GITHUB_TOKEN   # Paste your GitHub PAT
npx wrangler deploy

4. Add to Your App

import { AgentationWrapper } from "agentation-wrapper";

<AgentationWrapper
  webhookUrl={import.meta.env.VITE_WEBHOOK_URL}
  labels={[
    { name: "bug", displayName: "Bug", color: "#d73a4a" },
    { name: "enhancement", displayName: "Enhancement", color: "#a2eeef" },
    { name: "urgent", displayName: "Urgent", color: "#e11d48" },
  ]}
  allowCustomLabels
  onSuccess={(data) => console.log(`Issue #${data.issueNumber}`)}
  onError={(err) => console.error(err)}
/>

# .env.local
VITE_WEBHOOK_URL=https://your-webhook.workers.dev

How It Works

1. QA opens Agentation toolbar → annotates elements → adds comments
2. A badge appears showing annotation count (bottom-right)
3. Click badge → SendPanel opens with:
   • Annotation list (preview + remove)
   • Label selector (predefined + custom)
   • Send All button
4. Worker creates GitHub Issue with annotations + selected labels

Component Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | webhookUrl | string | Yes | Cloudflare Worker endpoint | | labels | LabelOption[] | No | Predefined label options | | allowCustomLabels | boolean | No | Allow typing custom labels | | onSuccess | (data) => void | No | Called with { issueNumber, issueUrl } | | onError | (error) => void | No | Called on webhook failure | | disabled | boolean | No | Hide toolbar |

interface LabelOption {
  name: string;          // GitHub label name
  displayName?: string;  // Human-readable display
  color?: string;        // CSS color for badge, e.g. "#d73a4a"
}

Worker Configuration

All config via wrangler.toml env vars:

| Variable | Format | Example | |----------|--------|---------| | DOMAIN_MAP | domain:owner/repo,... | localhost:org/repo,dev.app.com:org/app | | ALLOWED_ORIGINS | origin,... | http://localhost:5173,https://dev.app.com | | GITHUB_TOKEN | Secret (via wrangler secret put) | ghp_... |

Adding More Projects

Update wrangler.toml and redeploy:

[vars]
DOMAIN_MAP = "dev.app1.com:org/app1,dev.app2.com:org/app2"
ALLOWED_ORIGINS = "https://dev.app1.com,https://dev.app2.com"

npx wrangler deploy

Architecture

QA Browser
├── Agentation Toolbar (annotate elements)
├── SendPanel (badge → annotation list + labels → send)
│
POST /webhook → Cloudflare Worker
├── Parse DOMAIN_MAP env var
├── Merge auto-labels + user labels
└── GitHub Issues API → create issue

Example

cd examples/vite-react
cp .env.example .env.local   # Set VITE_WEBHOOK_URL
npm install && npm run dev

Requirements

• React 18+, react-dom 18+
• Node 18+ (CLI)
• Cloudflare account (free tier)
• GitHub PAT with Issues read/write scope

License

MIT