Drop-in feedback and bug-capture widget with structured issue creation, AI triage via Claude, and NTFY action notifications.
One widget, three host themes: the accent colour in each shot comes from the host app (BugPilot.init({ color }) or --bp-* overrides). Out of the box the widget is grayscale until your app supplies a colour.
Every submission becomes a structured issue: the report fields, an environment table (with a "Reporter" row when the host passes user), a machine-readable context block, and the captured screenshot, committed to a bug-report-screenshots branch in your repo and embedded in the body. Labels are applied on creation.
Moments later the triage action has classified it, assessed severity, applied labels, and drafted a reply for the reporter:
A real report, submitted through the widget and triaged end to end: see the live issue.
- Capture β a lightweight widget embeds in any web app. Users submit a bug report or feature request; the widget auto-collects viewport, browser, OS, and URL context plus an optional screenshot.
- Create β a structured GitHub issue is created with all captured data in a consistent machine-readable format. Screenshots are committed to a
bug-report-screenshotsbranch and embedded as images. - Triage β a Claude GitHub Action fires on every widget-submitted issue. Bugs are classified, severity assessed, and a proposed fix drafted. Feature requests receive a simple acknowledgement. A comment is posted and triage labels are applied automatically.
- Notify β an NTFY push notification is sent with the proposed fix summary and two action buttons: π’ Approve (triggers the apply-fix workflow) and π΄ Manual review (opens the issue).
- Fix β the apply-fix workflow runs a Claude agentic loop that reads the repo, implements the fix, and opens a PR. A follow-up NTFY is sent when the PR is ready.
Bug / Usability: what happened, expected behaviour, steps to reproduce (optional), frequency, impact.
Feature / Feedback: what would you like, why do you need it (optional), priority.
BugPilot.init({
endpoint: 'https://your-worker.workers.dev/feedback', // required
projectName: 'My Site', // issue title prefix; defaults to document.title
color: '#1c1b1a', // optional accent; sets --bp-primary and derived tokens
variant: 'pill', // 'pill' (default) or 'tab'
position: 'bottom-right', // pill only: bottom-right | bottom-left | top-right | top-left
side: 'right', // tab only: 'right' (default) or 'left'
triggerLabel: 'Feedback', // pill only: text beside the icon
icon: '<svg ...>...</svg>', // optional inline SVG replacing the trigger glyph (both variants)
user: { name: 'Ada Lovelace', login: 'ada' }, // optional reporter identity, see below
})| Option | Default | Notes |
|---|---|---|
endpoint |
required | Worker URL the widget POSTs to. |
projectName |
document.title |
Prefixes the issue title. |
color |
none | Six-digit hex. Sets --bp-primary, --bp-primary-hover, --bp-primary-shadow and --bp-primary-soft on the widget elements. |
variant |
'pill' |
'pill' is the labelled corner button. 'tab' is an icon-only 36px square (44px hit area) docked flush against a viewport edge with a small peek so it reads as a handle. |
position |
'bottom-right' |
Pill only. Ignored by the tab. |
side |
'right' |
Tab only. Which edge the tab docks to on first visit. |
triggerLabel |
'Feedback' |
Pill only. |
icon |
built-in glyph | Inline <svg> markup. Draw with currentColor so the host accent applies. Rejected (with a console warning and fallback to the default) unless it starts with <svg and contains no <script, on*= attributes, javascript: URLs, <foreignObject> or remote <use>. |
user |
none | { name, login }, both optional strings. Trimmed, angle brackets stripped, capped at 120 characters each. Sent with the report and rendered as a "Reporter" row in the issue plus a reporter key in the structured block. Leave it out and reports stay anonymous. |
Tab behaviour. The tab slides vertically along its edge by pointer drag (mouse and touch share
one Pointer Events path). Dragging it horizontally past the viewport midline and releasing swaps
it to the other edge. A tap (under 6px of movement) opens the dialog as normal. The resulting
{ side, y } is saved in localStorage under a per-origin key so it comes back where the user
left it; a missing, blocked or corrupt value falls back to side and a vertically centred tab.
Snap animations are disabled under prefers-reduced-motion.
The widget injects one stylesheet and reads every colour, radius, border, shadow and font from a
--bp-* custom property. Override them on body (or any ancestor with higher specificity than
:root, since the widget's own defaults live on :root and are injected after your stylesheet).
| Token | Default | Used for |
|---|---|---|
--bp-primary |
#262626 |
Trigger and submit background, focused input border, ghost button text |
--bp-primary-hover |
#404040 |
Hover state of the above |
--bp-primary-soft |
rgba(0, 0, 0, 0.05) |
Ghost button hover, active type-picker button |
--bp-primary-shadow |
unset | Colour used inside the default --bp-trigger-shadow; set by color |
--bp-on-primary |
#ffffff |
Text and icon colour on --bp-primary |
--bp-surface |
#ffffff |
Dialog and input background |
--bp-surface-raised |
#fafafa |
Chips, inactive type-picker buttons, close button hover |
--bp-border |
#e5e5e5 |
Dialog border, header and footer rules, inputs, chips |
--bp-border-width |
1px |
Width of the dialog and trigger borders |
--bp-text |
#171717 |
Body text and labels |
--bp-text-muted |
#737373 |
Chips, inactive buttons, close icon |
--bp-required |
#dc2626 |
"(required)" and "(optional)" label suffixes |
--bp-error |
#ef4444 |
Error status text |
--bp-error-soft |
rgba(239, 68, 68, 0.08) |
Error status background |
--bp-success |
#22c55e |
Success status text |
--bp-success-soft |
rgba(34, 197, 94, 0.08) |
Success status background |
--bp-backdrop |
rgba(0, 0, 0, 0.4) |
Page overlay while the dialog is open |
--bp-radius |
12px |
Dialog corners |
--bp-radius-sm |
6px |
Inputs, buttons, status box, screenshot preview |
--bp-radius-xs |
4px |
Context chips |
--bp-shadow |
0 10px 40px rgba(0, 0, 0, 0.15) |
Dialog shadow |
--bp-trigger-radius |
999px |
Pill trigger corners |
--bp-trigger-border-color |
transparent |
Trigger border colour (pill and tab face); set to var(--bp-border) for an ink outline |
--bp-trigger-shadow |
0 2px 10px var(--bp-primary-shadow, rgba(0, 0, 0, 0.16)) |
Trigger shadow (pill and tab face) |
--bp-tab-size |
36px |
Visible tab square |
--bp-tab-hit |
44px |
Tab hit area (WCAG 2.5.8 minimum) |
--bp-tab-peek |
0px |
How far the tab face tucks under the viewport edge at rest (0 keeps the icon centred) |
--bp-tab-radius |
0 |
Outer corners of the tab face |
--bp-z-index |
2147483647 |
Stacking of trigger, backdrop and dialog |
--bp-font |
system stack | Font family for all widget text |
A paper-and-ink look: graphite text, redline accent for required fields and errors, square corners, a 1px ink border in place of shadows, and an edge-docked tab trigger.
body {
--bp-primary: #1c1b1a;
--bp-primary-hover: #3a3835;
--bp-primary-soft: rgba(28, 27, 26, 0.06);
--bp-on-primary: #ffffff;
--bp-required: #b3401d;
--bp-error: #b3401d;
--bp-error-soft: rgba(179, 64, 29, 0.08);
--bp-surface: #fff6e5;
--bp-surface-raised: #ffffff;
--bp-border: #1c1b1a;
--bp-border-width: 1px;
--bp-trigger-border-color: #1c1b1a;
--bp-text: #1c1b1a;
--bp-text-muted: #5e5a54;
--bp-radius: 0;
--bp-radius-sm: 0;
--bp-radius-xs: 0;
--bp-trigger-radius: 0;
--bp-tab-radius: 0;
--bp-shadow: none;
--bp-trigger-shadow: none;
--bp-font: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
}BugPilot.init({ endpoint, projectName: 'Groundwork', variant: 'tab', side: 'right' })Contrast of every text/background pair in this theme (WCAG 2.x, AA needs 4.5:1 for body text):
| Pair | Ratio |
|---|---|
#1c1b1a text on #fff6e5 paper |
16.02:1 |
#5e5a54 muted on #fff6e5 paper |
6.38:1 |
#5e5a54 muted on #ffffff raised |
6.85:1 |
#ffffff on #1c1b1a primary (trigger, submit) |
17.20:1 |
#ffffff on #3a3835 hover |
11.69:1 |
#b3401d redline on #fff6e5 (required labels) |
5.33:1 |
#b3401d error text on its soft tint over paper (#f9e7d5) |
4.75:1 |
#1c1b1a on #ffffff |
17.20:1 |
- Drop-in, minimal setup. One script tag. One config object. Works.
- Theme-agnostic. CSS custom properties inherit from the host app; the widget looks native. The default palette is grayscale, so colour only appears when the host supplies it (
BugPilot.init({ color })or--bp-*overrides). - BYO credentials. The Actions are reusable GitHub Actions: consumers authenticate with workload identity federation (no stored key) or supply their own
ANTHROPIC_API_KEY. - No external CDN required. Screenshots are stored in a branch of your own repo.
- No laptop required. The full pipeline from user report to merged fix can run without touching a laptop.
The widget targets WCAG 2.2 Level AA. Consumers embedding it in a site with its own conformance obligations (ADA, EAA, DDA, depending on jurisdiction) can treat that as the baseline to test against.
Known gap: the report dialog does not yet trap focus, return it to the trigger on close, or
expose the type-picker's selected state via aria-pressed (#67).
Everything else in the dialog (labelled form controls, keyboard-operable trigger, visible focus
states) already meets the target; this is the one tracked exception.
M1, M2, and M3 complete and working end-to-end.
Widget:
cd widget && npm install
npm run dev # opens test harness at localhost:5173
npm run build # produces dist/bugpilot.es.js, .umd.js, .iife.jspnpm test runs the widget unit suite (vitest + jsdom, widget/test/*.test.js): trigger
variants, tap-versus-drag, side swap, localStorage restore and the icon and user sanitisers.
Still exercise both report paths (bug and feature) in the harness pnpm dev opens before
shipping a UI change; jsdom does not lay out CSS. CI runs pnpm test and pnpm build on
every push and PR; see .github/workflows/ci.yml.
Cloudflare Worker:
cd backend && npm install
# Create backend/.dev.vars with:
# GITHUB_TOKEN=<PAT β see secrets table below for required scopes>
# GITHUB_REPO=owner/repo
# ALLOWED_ORIGIN=http://localhost:5173
npx wrangler dev # local dev on localhost:8787
npx wrangler deploy
npm run typecheck # tsc --noEmit; CI runs this on every push and PRTriage Action (consumers):
Add to your repo's workflow:
- uses: rodlunt/bugpilot/actions/triage@v1
with:
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
ntfy-topic: ${{ secrets.NTFY_TOPIC }} # optional
webhook-secret: ${{ secrets.WEBHOOK_SECRET }} # optional, for apply-fix
bugpilot-worker-url: ${{ secrets.BUGPILOT_WORKER_URL }} # optional, for apply-fixApply-fix Action (consumers):
Add to your repo's workflow β triggered by workflow_dispatch with an issue_number input, or automatically via the NTFY π’ Approve button once the Worker is deployed:
- uses: rodlunt/bugpilot/actions/apply-fix@v1
with:
issue-number: ${{ github.event.inputs.issue_number }}
anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
ntfy-topic: ${{ secrets.NTFY_TOPIC }} # optionalAlso required: Settings β Actions β General β tick "Allow GitHub Actions to create and approve pull requests".
GitHub Actions secrets (consumer repo):
| Secret | Purpose |
|---|---|
ANTHROPIC_API_KEY |
Claude API key for triage and apply-fix. Not needed when using workload identity federation (see below) |
NTFY_TOPIC |
NTFY topic β accepts a plain slug (my-topic), a host/path (ntfy.example.com/my-topic), or a full URL (https://ntfy.sh/my-topic) |
WEBHOOK_SECRET |
Shared secret for the Worker /webhook/apply-fix endpoint. Never sent to NTFY: the triage action uses it to sign a short-lived, issue-scoped approval token, and the Worker verifies that signature. Rotating it invalidates every approval token already sitting in a phone's notification history. |
BUGPILOT_WORKER_URL |
Deployed Worker base URL β wires the π’ Approve NTFY button |
Worker secrets (set via wrangler secret put):
| Secret | Purpose | Required PAT scopes |
|---|---|---|
GITHUB_TOKEN |
Creates issues, commits screenshots, dispatches workflows | Classic PAT: repo + workflow. Fine-grained: Contents (R/W), Issues (R/W), Actions (R/W) |
GITHUB_REPO |
Target repo as owner/repo |
β |
WEBHOOK_SECRET |
Same value as the Actions secret above | β |
Upgrading past the approval-token change. The triage action and the Worker must be on
matching versions: the triage action signs the Approve token and the Worker verifies it, and an
old Worker does not understand the new x-approval-token header (nor does a new Worker accept
the old raw-secret header). Deploy the Worker and bump the triage/apply-fix action tag together.
NTFY topic exposure. The π’ Approve button's target URL, method and body are visible to
anyone who can read the NTFY topic: NTFY does not encrypt notification content from itself, and a
plain topic slug (ntfy.sh/my-topic) has no read access control at all, so treat the topic name
itself as the only thing standing between a stranger and your notifications. WEBHOOK_SECRET
itself is never put in that payload (it signs a 48-hour, issue-scoped approval token instead, so a
leaked token cannot be replayed against a different issue or reused once it expires), but the
triage detail (issue title, proposed fix, severity) still goes out unauthenticated on a public
topic. Use a hard-to-guess topic slug at minimum, and prefer a self-hosted NTFY server with
access control on the topic (ntfy-token above
authenticates the publish call to such a server; the topic's own ACL is what controls who can
read it) if the triage content itself is sensitive.
Worker env vars (set in wrangler.toml or via wrangler secret put):
| Var | Default | Purpose |
|---|---|---|
ALLOWED_ORIGIN |
* |
CORS allowed origin(s). Accepts a single origin or a comma-separated list (e.g. https://www.example.com,https://app.example.com). |
APPLY_FIX_WORKFLOW |
apply-fix.yml |
Filename of the apply-fix workflow the Worker dispatches when π’ Approve is tapped. Change this if you name your workflow differently. |
Both actions can authenticate to the Claude API with a short-lived token minted from the GitHub Actions OIDC token, so the consumer repo holds no ANTHROPIC_API_KEY at all. The action requests a GitHub OIDC token with audience https://api.anthropic.com, exchanges it at POST https://api.anthropic.com/v1/oauth/token (RFC 7523 jwt-bearer grant, done by the Anthropic SDK in-process) and uses the resulting sk-ant-oat01-... token, refreshing it before expiry. A fresh GitHub token is fetched on every exchange because Anthropic treats each jti as single-use.
Claude Console steps (Settings, Workload identity, Connect workload, GitHub Actions tile; you need the admin or owner role):
-
Federation issuer: issuer URL
https://token.actions.githubusercontent.com, JWKS sourcediscovery. -
Service account: create one (
svac_...) and add it to the workspace the Actions should bill against. -
Federation rule (
fdrl_...): pin it to the repository and the branch, not just the owner. Thesubclaim of a triage run (anissuesevent on the default branch) isrepo:<owner>/<repo>:ref:refs/heads/main, and so is an apply-fixworkflow_dispatchrun from main.{ "match": { "subject_prefix": "repo:your-org/your-repo:ref:refs/heads/main", "audience": "https://api.anthropic.com", "claims": { "repository": "your-org/your-repo", "ref": "refs/heads/main", "repository_owner": "your-org" } }, "target": { "type": "service_account", "service_account_id": "svac_..." }, "oauth_scope": "workspace:developer", "token_lifetime_seconds": 600 }A rule matching
repo:your-org/*with norefclaim would also match pull-request runs from forks, which means anyone who can open a PR could mint a token. Keep it pinned. -
Note the organisation ID (Settings, Organization), the rule ID and the service account ID. None of them is a secret; store them as repository variables.
Consumer workflow. Grant id-token: write and pass the three IDs. Leave anthropic-api-key out (or empty) once federation works; if it is set alongside the federation inputs the action still uses federation, and a partial set of federation inputs is an error rather than a silent fallback to the key.
permissions:
contents: read
issues: write
id-token: write
steps:
- uses: rodlunt/bugpilot/actions/triage@v1
with:
anthropic-federation-rule-id: ${{ vars.ANTHROPIC_FEDERATION_RULE_ID }}
anthropic-organization-id: ${{ vars.ANTHROPIC_ORGANIZATION_ID }}
anthropic-service-account-id: ${{ vars.ANTHROPIC_SERVICE_ACCOUNT_ID }}
# anthropic-workspace-id: ${{ vars.ANTHROPIC_WORKSPACE_ID }} # only if the rule spans workspacesThe apply-fix action takes the same inputs and also needs id-token: write on its job. Once BR360 and Groundwork are on federation, delete ANTHROPIC_API_KEY from each repo's secrets and then from the Console (Settings, API keys).
Troubleshooting. A denied exchange is an opaque 401 Authentication failed; the reason (usually match_subject_prefix when the sub format differs from the rule) is on the Console's authentication history page. An empty OIDC token means the job is missing id-token: write.
The worker (backend/) exposes two endpoints. Both are POST, JSON in and out, and both are
CORS-gated by ALLOWED_ORIGIN.
The widget's submission endpoint. No auth β the worker accepts anonymous POSTs by design (see Security); anything sent here becomes a GitHub issue.
Request body:
| Field | Type | Required | Notes |
|---|---|---|---|
context |
object | yes | { url, viewport: {w, h}, userAgent, browser, os, timestamp, timezone?, language?, referrer? }. Missing this returns a 400 naming the field (see CLAUDE.md gotcha 1) rather than a generic Cloudflare 1101. |
description |
string, 1β10000 chars | yes | |
type |
"bug" | "feature" |
no | Drives the issue's label: bug or enhancement. |
user |
object | no | { name?, login? }, each β€120 chars. Angle brackets stripped. Adds a **Reporter:** line to the issue if supplied. |
screenshot |
string | no | Base64 data URI, β€4MB decoded. Committed to the bug-report-screenshots branch, not sent inline. |
projectName |
string, β€200 chars | no | |
bugCategory, expectedBehavior, stepsToReproduce, frequency, impact, problemStatement, priority |
string | no | All optional context fields, β€50β10000 chars depending on field. |
Success (201):
{ "ok": true, "issueUrl": "https://github.com/owner/repo/issues/42", "issueNumber": 42 }Failure (400): { "ok": false, "error": "Invalid payload: <field>: <message>; ..." } β one message per violating field.
Fired by the ntfy "Approve" notification action, never called directly by the widget or a
consumer. Requires an x-approval-token header: a short-lived, issue-scoped signed token minted
by the triage action (see THREAT_MODEL.md), not a static secret. A missing,
forged or expired token returns 401.
Success (200): { "ok": true } β the apply-fix.yml workflow has been dispatched for the
issue bound into the token. Failure to reach GitHub's dispatch API returns 502.
SECURITY.md covers how to report a vulnerability. THREAT_MODEL.md covers the four trust boundaries this system crosses and which risks are mitigated versus knowingly accepted.
Built by Rodney Lunt. If this saved you some time, you can buy me a coffee.