shipcue: Bug Reports Your Coding Agents Can Fix

Drop-in report button  •  Queue in your own Postgres  •  Agents claim over MCP  •  One report, one agent

🌐 Website  •  ☁️ Cloud  •  📖 Docs  •  📝 Blog  •  ✉️ Contact

---

A drop-in bug report and feature request button whose inbox is a queue that people and coding agents both work from.

Someone in your app clicks the button, says what broke or what they want, pastes a screenshot, and sends. shipcue files it with the page address, browser and a snapshot of app state you choose. Then Claude Code, Codex or a teammate claims the most urgent report, gets a ready-made task prompt, fixes it, and closes it with the PR link.

user files a report  →  queue (your Postgres)  →  agent claims the top one  →  PR  →  closed as fixed

• Self-hosted. One table in your own Postgres. No third-party dashboard, no per-seat pricing.
• Agent-ready. Every report carries enough context to act on, and an MCP server lets agents pull from the queue without two of them ever taking the same report.
• No CSS setup. The button uses inline styles and takes an accent colour.

It started as the report button inside three apps (a founders dashboard, a hackathon platform and a block outliner) and was pulled out once the same five parts kept showing up: a button, a form, automatic context, storage, and somewhere for reports to go.

Use cases

• Hackathon teams running many agents. Everyone reports into one queue and each agent claims one report at a time, so two agents never fix the same bug and nobody's fix undoes someone else's.
• Founders with early users. Users report from the page where it broke, with context attached. Your agent works the queue, most urgent first, and you review the PRs.
• Internal tools and dashboards. An inline button in the header, sign-in required, new reports posted to Slack or email, and the data stays in your database.
• Beta tests and dogfooding sessions. Testers file what they hit; areas and priority keep the pile in order for the agents.
• Feature requests too. An agent can draft one as a PR, or you close it as won't fix with a reason.

More on the use cases page.

Install

npm i shipcue   # or pnpm add shipcue

Until it's on npm, install the prebuilt release (nothing builds on install, so it works with pnpm on Vercel; pick the newest from releases):

pnpm add https://github.com/edumame/shipcue/releases/download/v<version>/shipcue-<version>.tgz

Then run npx shipcue doctor in your app's repo; it says what is missing and how to fix it (see Check your setup). On shipcue Cloud, with no database of your own: npx shipcue init --cloud <pk_…>.

1. Create the table

Run sql/schema.sql on your database (Supabase, InsForge, Neon, RDS or local Postgres). Upgrading from 0.1: run it again; it adds the video column to the existing table.

2. Mount the handler

Next.js App Router, app/api/shipcue/[...path]/route.ts:

import { Pool } from 'pg';
import { createShipcueHandler, postgresStore } from 'shipcue/server';
import { resolveConfig } from 'shipcue';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const handler = createShipcueHandler({
  store: postgresStore(pool),
  config: resolveConfig({ areas: [{ value: 'editor', label: 'Editor' }, { value: 'billing', label: 'Billing' }] }),
  getReporter: async (req) => (await getSession(req))?.email ?? null, // your auth
  requireReporter: true,
  agentToken: process.env.SHIPCUE_TOKEN, // leave unset to switch the agent API off
  onReport: async (report) => {
    // email the team, post to Slack, mirror to your task board...
  },
});

export { handler as GET, handler as POST };

The handler is a plain (Request) => Promise<Response>, so it also works in Hono, Remix, Bun, Deno and Cloudflare Workers. Screenshots are stored as data URLs unless you pass saveScreenshot(file, key) to upload them to S3, Supabase Storage or similar.

Retry-safe filing. The panel sends an idempotencyKey form field with each report: one per draft, the same on every retry of it (a failed send, a timeout), new after a successful send or for a new report. A repeat key gets the report already filed (same id, status 200, replayed: true) instead of a copy, and onReport and broadcasters hear about it once. Both built-in stores do this; postgresStore needs the "Upgrading from 0.26" block of sql/schema.sql (a nullable idempotency_key column and a unique index per project), and without it reports file as before, without the protection. Custom stores get NewReport.idempotencyKey and return the first report with replayed: true on a repeat. Keys that are too long (over 100 characters) or have odd characters are ignored, never refused.

Your reports on any device. When getReporter reads a verified session, add reporterPortal: true: GET /mine returns the signed-in reporter's own reports (status, fix line, PR; never anyone else's, never diagnostics) and the panel's Yours list adds them. Not for a reporter the browser says itself (the button's reporter prop), so shipcue Cloud projects skip it.

Open what you sent. The panel keeps each report sent from this browser in full (shipcue:mine in localStorage: the text, type, priority, area, page, picked-out context, how many screenshots and files, whether a video went with it, alt texts, when it was sent; never the screenshot or video data). Each item in Yours opens a read-only view of it, with the server's status, fix line and PR merged in when the handler offers GET /mine; Back returns to the list. It works with a custom submit too. Kept to the latest 50 (MAX_MINE), text cut at 4,000 characters, the list held under about 200 KB (the oldest go first). For a page with only a custom submit, or offline, <LocalReports /> from shipcue/react shows the same list and detail from this browser's storage alone (props: text, renderContext, style).

Videos. Pass saveVideo(file, key) to turn on POST /reports/:id/video: whoever filed a report can attach one screen recording or video (WebM, MP4 or MOV, up to 40 MB) within 30 minutes. Hosts that cap request bodies (Vercel: 4.5 MB) should upload from the browser instead, with the button's uploadVideo prop and a presigned URL.

3. Add the button

import { ReportButton } from 'shipcue/react';

<ReportButton
  areas={[{ value: 'editor', label: 'Editor' }, { value: 'billing', label: 'Billing' }]}
  accentColor="#8c1515"
  diagnostics={() => ({ route: location.pathname, openDoc: store.docId, lastAction: store.lastAction })}
/>

Use variant="inline" for a header or toolbar button on phones, where a floating bubble covers the controls. Pass submit={(form) => myServerAction(form)} to send through a server action instead of fetch; the form carries idempotencyKey (one per draft, the same on a retry), so file a key once and answer a repeat with the report already filed. Pass defaultArea="billing" to start the Where on the part of your app the page is in (Other is still offered). Pass reporter={user.email} to say who is signed in on your site: it goes with each report in the x-shipcue-user header, shipcue Cloud shows it as the reporter, and your own handler can read it in getReporter.

What else the panel does:

• Record screen or attach a video. Recordings stop at 60 seconds. The video uploads after the report is filed; if it fails, the report is still filed and the panel says so. Pass uploadVideo={(reportId, blob) => …} to upload it yourself; otherwise it goes to the handler. With submit and no uploadVideo, video is hidden.
• Recent errors. Page errors, unhandled rejections and console.error calls from before the report are added to the snapshot as recentErrors. Turn off with captureErrors={false}.
• The page. The panel shows which page it will attach, with a "don't attach" link.
• Move it. People can drag the floating button anywhere, by the button or by the panel's title; the two move together, the panel stays on screen (it opens above or below the button, whichever has room, settled when you let go), and the spot is kept in their browser. Reset position (⌃⇧H / Alt+Shift+H, or Display) puts it back; movable={false} keeps it bottom-right.
• Resize it. Drag the small grip on the panel's free corner (the one away from the button) to make it wider and taller; the text box takes the extra height, so there is more room to write. It never gets smaller than the default or leaves the screen, works with every text size, and arrow keys resize it once the grip is focused (Shift for bigger steps). The size is kept in the browser; Reset position puts it back too. resizable={false} keeps the default size; the inline variant has no grip.
• Copy prompt for my agent. A small link in the panel's footer copies a prompt for Claude Code or Codex with the app, the page, the form's choices (type, priority, your areas), what the person typed, any picked-out context and the snapshot shipcue would attach. The agent asks for anything missing, then files it with the MCP tool file_report or a ready curl to your endpoint. Hidden when you send reports with submit and no endpoint.
• Your own mark. The button shows shipcue's hard hat; icon="ship" brings back the sailboat, and launcherIcon={<YourLogo />} draws your own logo.
• Your own description editor. renderDescription={({ value, onChange, submit, textarea }) => …} draws the description in place of the text box, e.g. your app's outline editor; textarea is shipcue's own box on the same text, for a "Raw text" switch.
• Your own fields. formExtras={<label><input type="checkbox" /> Pin it</label>} draws a small control under the text box in the Bug and Feature request forms, and adds them to the report when it is sent (never over shipcue's own fields). With , read them from the FormData; with an endpoint, they arrive as form fields.

The panel has three tabs: Bug, Feature request and Agent task (a direct instruction for an agent; limit them with types={['bug', 'feature']} on a public page). The panel ends with a small "Powered by shipcue · ★ Star it on GitHub" line. If shipcue helps you, a star really helps; watermark={false} turns it off.

Keyboard shortcuts

	Mac	Windows / Linux
Agent task	⌘J	Alt+Shift+J
Bug	⌃B	Alt+Shift+B
Feature request	⌃F	Alt+Shift+F
Send	⌘↵	Ctrl+↵

Text highlighted on the page comes along in an editable, removable Context box (an outline opens as a Preview with bullets and [[links]]; Raw is the text; renderContext draws the Preview with your app's own renderer) (or pass getContext to supply your app's selected rows or blocks), and agents get it as its own section of the task prompt. Change the keys with hotkeys={{ task: ['Mod+J'] }} ("Mod" is ⌘ on a Mac, Ctrl elsewhere), turn them off with hotkeys={false}, or open the panel from your own menu with openReport('task'), and start Select area from a command palette with selectArea() (it fires the shipcue:select-area window event). People can also change their own keys from the panel's small Shortcuts link; their choice is kept in their browser and wins over yours. If your app's own keymap opens shipcue (hotkeys={false}), pass onEditShortcuts={openYourKeymapEditor} and the link opens that instead.

Your own tabs

An app with its own flow (say an agent-task composer backed by its API) can draw it as a tab in the same panel: extraTabs={[{ id: 'agent', label: 'Agent task', render: ({ text, context, close }) => <TaskComposer … /> }]}. Give it a hotkey with hotkeys={{ agent: ['Mod+J'] }} or open it with openReport('agent'); onOpenChange and closeReport() let the app follow and close the panel. openReport(tab, { keepDraft: true }) reopens a half-written report instead of starting fresh (on an extra tab, it opens that tab and keeps the report behind it), and persistDraft keeps it across reloads (a phone dropping the tab). If the app already has a help button, trigger={false} hides shipcue's own and the app opens the panel with openReport('bug').

4. Let agents work the queue

claude mcp add shipcue \
  -e SHIPCUE_URL=https://your.app/api/shipcue \
  -e SHIPCUE_TOKEN=... \
  -- npx shipcue-mcp

Tools: file_report, list_reports, claim_next_report, get_report, claim_report, release_report, close_report, submit_for_review, heartbeat_report, add_note, merge_report, list_my_reports, set_report_scope, list_conflicts.

Filing for a person. file_report files a bug, feature request or agent task with the same fields the panel sends (type, description, priority, area, page URL, context, diagnostics), as a multipart POST from the agent's machine to {SHIPCUE_URL}/reports, so your browser CORS rules do not get in the way (sign-in and anonymous limits still apply). It needs no token: SHIPCUE_URL alone is enough for it. The panel's Copy prompt for my agent link hands the agent everything it needs to call it. It tells the app it can answer a close match (canConfirm=1), so an app that dedupes (answers 409 { "error": "LIKELY_DUPLICATE", "duplicateOf", "match", "hint" }) files nothing yet: the tool returns the match, and the agent calls it again with if_duplicate: addAsNote (add it to that report as a note), reopen (the same, and reopen it if closed) or fileAnyway (a different report; force=1 is sent too). In code, createAgentClient().file() throws LikelyDuplicateError and takes ifDuplicate.

One token per agent. Pass agents: async (token) => ({ id, name, pull?, types?, leaseSeconds? }) | null to the handler and each agent claims under its own name, can only release or close what it holds, and (with pull: false) only takes what someone assigned to it. leaseSeconds gives agent claims a lease: an agent that stops calling heartbeat_report loses the report back to the queue. submit_for_review puts the report in review with the PR link, with no lease, until it is closed.

claim_next_report hands back a prompt like this:

# Bug [Blocking] Editor: Enter at the end of a heading deletes it

Enter at the end of a heading deletes it

## Where
Report id: a44f5541-…
Page: https://your.app/page/42
Filed: 2026-10-01T23:01:08Z by [email protected]

## App snapshot
```json
{ "blocks": 7, "lastAction": "split-block" }
```

## What to do
Reproduce it, write a failing test, fix it, and close the report with the PR link.

Claims are atomic (FOR UPDATE SKIP LOCKED), so several agents can drain the queue at once.

Work areas. When several agents (or sessions) work one repo, a claim can say what it touches: { areas?, paths?, migration?, branch? } as scope on claim_report / claim_next_report (or POST reports/:id/claim { scope }), changed later with set_report_scope (POST reports/:id/scope). paths are globs (src/server/**; a folder covers what is under it). Two active claims (claimed or in review) that share an area, a file, a migration slot or a branch get a warning in the claim's response, a small "overlaps #id8" badge in the CueLog, and a line in list_conflicts (GET reports/conflicts, or team/conflicts for members), which also says free: true when nothing is claimed or in review. It never blocks, and the scope lives in the report's history, so there is no schema change. Design and what comes next: docs/swarm.md.

Check your setup

npx shipcue doctor                                         # files, env, lockfile
npx shipcue doctor --url https://your-app.com/api/shipcue  # plus the live endpoint, token and tables

One ✓ or ✗ line per check, with the exact fix under each ✗ (exit code 1 if any fail):

• shipcue is installed, and which version (and the newest release, unless --offline)
• no signed release-assets.githubusercontent.com URL in pnpm-lock.yaml, package-lock.json or package.json (it expires in an hour and breaks later deploys); prints the swap to the stable URL
• the handler route exists (app/api/shipcue/[...path]/route.ts, or --route <file>)
• the env vars the route reads (default DATABASE_URL, SHIPCUE_TOKEN) are in .env*, your shell, and on Vercel when the project is linked (vercel env ls); values are never printed
• with --url: GET /capabilities answers 200, the agent API answers 200 with SHIPCUE_TOKEN, and (with DATABASE_URL and the app's pg) shipcue_reports and shipcue_report_events exist with RLS on, every column in sql/schema.sql and the current history actions; a gap prints the "Upgrading from …" block to run

shipcue Cloud. npx shipcue init --cloud pk_… prints the env line (NEXT_PUBLIC_SHIPCUE_ENDPOINT) and a small ShipcueButton client component for a Next.js app; --write adds both, never overwriting.

HTTP API

Method	Path	Who
POST	/reports	the button (multipart form)
POST	/reports/:id/video	the button, the reporter only (multipart, field video; needs saveVideo)
GET	/reports?status=open	agent, bearer token
GET	/reports/:id	agent
POST	/reports/next/claim	agent
POST	/reports/:id/claim	agent
POST	/reports/:id/release	agent
POST	/reports/:id/close	agent, { status: "fixed" | "wontfix", resolution, prUrl? }
POST	/reports/:id/heartbeat	agent: renew its lease
POST	/reports/:id/review	agent, { prUrl }: a PR is up, the report is in review
GET	/reports/:id/events	agent: the report's history
GET	/reports?mine=1	agent: what it holds or has queued
POST	/reports/:id/note	agent, { text }: a note on the report's history
POST	/reports/:id/merge	agent, { into }: close it as a duplicate of another report, with a note on both
POST/PUT	/reports/:id/scope	agent holding it, { scope } (null clears): what its claim touches
GET	/reports/conflicts	agent: active claims whose work areas overlap, and

Queue and changelog pages

Switch on board in the handler (true, or (req) => boolean to limit who sees it), then render <ShipcueBoard endpoint="/api/shipcue" /> (or <ShipcueQueue /> / <ShipcueChangelog />) from shipcue/react. It lists open and in-progress reports, most urgent first, and fixed ones with their resolution, latest first. No reporter, page, diagnostics or attachments ever leave the server. Close reports with a one-line, user-facing resolution and the changelog writes itself. With both lists it shows Open / Fixed / All / Changelog pills with counts, and a small View control lets each viewer switch to tabs or a compact list (tabStyle, layout, viewPicker) (initialView sets where it starts). Add boardScreenshots: true to show each report's screenshots too: off by default, since screenshots can show private things. The board is live: it checks a tiny /board/version every 5 seconds while the page is in view and re-reads as soon as a report is filed or changes (liveMs, 0 turns it off). The Changelog is grouped by the day each fix shipped. Two opt-ins: filters adds a search box and a type picker, and syncUrl keeps the tab in the URL (?view=changelog) so it can be linked.

The CueLog table

For the team: every report in full, claimed and worked by people and agents together. Give the handler a team option, { getMember: (req) => ({ id, name, role: 'owner' | 'member' | 'viewer' }) | null, claimants: (req) => [{ kind: 'person' | 'agent', id, name }] }, and render <CueLogTable endpoint="/api/shipcue" /> from shipcue/react on a signed-in page. It has Open / Mine / In review / Fixed / All pills, filters (type, priority, who has it, search), sorting (queue order, longest waiting, recently updated, claimant), a List and a Board view (drag between columns), inline priority and assignee, bulk actions, and a side panel with screenshots, the app snapshot, the agent prompt and the report's history. Unowned work says "Nobody yet" in amber, and the "Claimed by" filter's Nobody has looked keeps open reports nobody holds and nothing has happened to since they were filed; an agent's lease and a stale claim show as badges. Assigning to an agent queues the report for it: its claim_next_report returns that report first. Every change is kept in shipcue_report_events. Members can Edit a filed report from the drawer (text, type, area, and once it is closed, what changed), checked against your config and logged as edited (store.edit, POST /team/reports/:id/edit); Edit offers the handler's areas, so the areas prop is optional. Context drawn as an outline has a Preview / Raw switch, a report's PR shows on its row, and the list leaves diagnostics out (the drawer reads them with the report). Merge folds a duplicate into the original (POST /team/reports/:id/merge { into }, members only): the duplicate closes as won't fix with "Duplicate of #", both reports get a note, and the original's note counts the duplicate's reporters (never who they are); into must be a report the same store can see, so a Cloud project can't merge into another's. A note can carry suggestions in its detail (store.note(id, text, by, { suggest: { priority?, area?, duplicateOf? } }), as Cloud's hosted agent does): the drawer shows them as small Apply priority, Apply area and Merge into #id8 chips, each a normal team API call under the member, logged in the history; nothing is applied without a click. Opt-ins: syncUrl keeps the tab and the open report in the URL (?tab=fixed&report=<id>) and adds Copy link; hotkeys turns on / search, j/k move, Enter opens, p pins.

Or use shipcue Cloud: the same table, hosted, with projects, invites and agent tokens.

Admin page

Projects, team, invites, agent tokens and the CueLog on one route, on your Postgres (sql/schema.sql and sql/cloud.sql), with no Cloud account. It reads your app's signed-in user, so it has no sign-in of its own:

// app/admin/[[...path]]/route.ts (Next.js); any server that speaks Request/Response works the same way
import { createAdminHandler } from 'shipcue/admin';

const handler = createAdminHandler({
  db: pool,                           // node-postgres Pool, Neon, PGlite: anything with query()
  base: '/admin',
  page: true,                         // serves the admin page at /admin and its script at /admin/app.js
  getUser: async (req) => {           // your session; a non-uuid id is fine
    const u = await getSession(req);
    return u ? { id: u.id, email: u.email, name: u.name } : null;
  },
  signInUrl: '/login',                // where the page sends someone signed out
  beta: ['[email protected]'],          // who may create projects; everyone else joins by invite
});
export { handler as GET, handler as POST };

Buttons file to /admin/p/<publicKey> and agents use the tokens it hands out. Try it with no database or sign-in: pnpm build && node examples/admin-demo.mjs, then open http://localhost:4546/admin. shipcue Cloud runs the same handler with its own sign-in (auth: insforgeAuth(...) instead of getUser).

Chrome extension

Report what you see on any page, even sites you do not run: the extension in extension/ sends your words with a screenshot of the tab, the element you click (selector, text, position, HTML), the text you selected, and the time, time zone, window size and, if you tick it, your location, to any shipcue endpoint. Download it from shipcue.ibuildathing.com/extension, unzip, and load it at chrome://extensions → Developer mode → Load unpacked. Set your app's endpoint under ⚙ (it sends to shipcue's own CueLog until then).

Broadcast and listen

Tell people or agents when something happens to a report. Each broadcaster gets the events it lists (report.filed, report.claimed, report.released, report.closed, report.video), after the change is saved; one that fails or is slow is logged and never fails the request.

import { createShipcueHandler, slack, webhook } from 'shipcue/server';

createShipcueHandler({
  // ...
  broadcasters: [
    slack({ webhookUrl: process.env.SLACK_WEBHOOK!, link: 'https://app.example.com/reports' }),
    // Zapier, n8n, an email or SMS bridge, or an agent on a VPS, Mac mini or Tailscale address.
    // Signed: check x-shipcue-signature with signBody(secret, rawBody).
    webhook({ url: 'https://mac-mini.tailnet.ts.net/shipcue', secret: process.env.HOOK_SECRET, events: ['report.filed'] }),
    // Or anything: { name: 'sms', events: ['report.filed'], send: async (e) => sendText(describeEvent(e)) }
  ],
});

An agent that would rather not open a port listens instead: shipcue-listen polls the queue with the agent token and runs a command per event, with the event as JSON on stdin and SHIPCUE_EVENT / SHIPCUE_REPORT_ID in its environment, one at a time.

SHIPCUE_URL=https://app.example.com/api/shipcue SHIPCUE_TOKEN=... \
  npx shipcue-listen --on filed -- claude -p "Fix the newest report in the shipcue queue"
# --on filed,assigned,claimed,released,closed,video   --every 15 (seconds)   --backlog   --once
# --scope '{"paths":["src/server/**"]}'   the work area this agent's claims declare (SHIPCUE_SCOPE for shipcue-mcp)
# No command: prints one JSON line per event.

assigned fires when someone queues a report for this agent in the CueLog. To keep a listener running as a daemon, shipcue Cloud's Setup tab writes it out for you (Run a listener): the one-line command, a macOS launchd agent (KeepAlive, logs in ~/Library/Logs) or a Linux systemd --user unit, with the agent's token filled in.

A Claude Code session per report. shipcue dispatch claims each unclaimed open report and starts a background Claude Code session (claude --bg) on it in your repo, up to --max (10) at once, while your Claude plan has usage left (otherwise it waits for the 5-hour or weekly window to reset). The session gets the report's task prompt and the shipcue MCP tools as the same agent, so it holds the claim: it works in its own worktree, opens a PR and submits it for review. A report it has in review whose PR has sat untouched for 15 minutes gets one takeover session (two at most). Install it once and launchd runs a pass every minute:

# with shipcue installed in the repo (see Install), so launchd has a stable path to it
npx shipcue dispatch --dry-run --url https://app.example.com/api/shipcue --token sca_…   # what it would start
npx shipcue dispatch --install --url https://app.example.com/api/shipcue --token sca_… --agent mac-mini \
  --instructions "Follow the work-queues skill."   # --types bug,task  --max 4  --permission-mode auto
npx shipcue dispatch --status      # what this machine started;  --uninstall removes the launchd agent

Sessions run with --permission-mode auto by default, since report text comes from whoever filed it; --permission-mode bypassPermissions skips Claude Code's checks. Log: ~/.local/state/shipcue-dispatch/<repo>/dispatch.log.

One digest instead of a message per event. Turn on digest and a cron (Vercel Cron, GitHub Actions, launchd) calls POST {base}/digest with the agent token every hour or day. It builds one summary of the last period from the report history: filed, fixed (with the fix line and PR), reopened, claims stuck past their lease, how many are still open and the oldest waiting, and sends it with slackDigest({ webhookUrl }), emailDigest({ to, send }) (the same send as emailReporter) or your own { name, format, send }. Without send it returns the digest as Markdown, for a daily note or an outliner log. Quiet periods send nothing unless sendEmpty. It never includes who filed a report, the page, diagnostics or attachments. digest(store, { since, until, format: 'slack' | 'email' | 'markdown' }) builds one anywhere.

createShipcueHandler({ /* ... */ digest: { every: 'day', send: slackDigest({ webhookUrl: process.env.SLACK_WEBHOOK! }), link: 'https://app.example.com/reports' } });
// curl -X POST https://app.example.com/api/shipcue/digest -H "Authorization: Bearer $SHIPCUE_TOKEN"   (body: { since?, until?, every? })

Close the loop with GitHub

Let pull requests move reports instead of calling review and close by hand. Give the handler a secret:

createShipcueHandler({
  // ...
  github: {
    secret: process.env.SHIPCUE_GITHUB_SECRET!,
    // Optional: close only once production serves the merge commit.
    liveCheck: { url: 'https://app.example.com/api/version' },
  },
});

Then in the repository: Settings → Webhooks → Add webhook, Payload URL https://your.app/api/shipcue/github, Content type application/json, the same Secret, and Let me select individual events → Pull requests only. Name the report in the PR's title, body or branch, by its full id or its first 8 characters (fix/919f5ca2-github-loop); ids that are not reports in this store are ignored.

Pull request	Report
opened, reopened, edited, synchronize, ready for review	open or claimed → In review with the PR link (a claimant keeps it)
merged	→ Fixed, "Merged in #N", with the PR link (closed reports stay as they are)
merged, with liveCheck	stays In review until url serves the merge sha (its first 7 characters, or your match(body, sha)), then Fixed, "Merged in #N, live in abc1234"
closed without merging	In review under this PR → back in the queue, unassigned

The history names github (@login) as an agent. shipcue runs no timers: liveCheck is checked when the board, the CueLog or an agent reads the queue (at most once per everyMs, a minute by default), or call handler.checkLive() from a cron. On shipcue Cloud, Setup → Close the loop with GitHub gives the project's webhook URL (/api/cloud/p/<key>/github) and its secret, shown once.

Try it locally

pnpm install && pnpm build
SHIPCUE_TOKEN=dev node examples/demo-server.mjs

Development

pnpm test        # vitest; the Postgres store runs against real Postgres via PGlite
pnpm typecheck
pnpm build

Publishing

Maintainers publish from a clean main (the build runs on prepublishOnly, so installing shipcue never builds anything):

npm login
npm publish --access public

Release tarballs for GitHub: npm run pack:release (builds, then npm pack).

Changelog

• 0.39.0: openReport(extraTab, { keepDraft: true }) opens that extra tab and keeps a Bug or Feature request not sent yet behind it, text, context and screenshots as they were (Habitect report 64ba8b31), so an app can open its own tab (a chat) without losing what was being written; the draft comes back with the next keepDraft open of a report tab. Before, it opened on the draft's tab instead. Plain openReport(extraTab) still starts the form fresh. No text or schema change.

• 0.38.0: reportKey on createAdminHandler: the admin page shows a report button (Bug and Feature request) filing into that project, so shipcue Cloud's own reports go through shipcue. A project now takes reports from the admin's own page without listing it, and someone signed in to the admin files as their account rather than whoever the site says. No schema change.

• 0.37.0: Cloud Setup opens with Set it all up with one prompt: pick an agent and the repo's folder, and paste it into Claude Code (or Codex) on the machine. It adds the report button to the app in a PR, connects Claude to the project with the shipcue MCP server as that agent, and keeps a workflow working the queue there (shipcue dispatch on macOS, the listener as a systemd --user unit on Linux). This prompt and the listener's both now say how to remove it all again (projectPrompt, dispatchUninstall, launchdUninstall, systemdUninstall in the admin page's listener.mjs). No schema change.

• 0.36.0: shipcue/admin and shipcue dispatch. The Cloud dashboard's server is now a package entry, createAdminHandler (projects, team, invites, agent tokens, settings, digests, the CueLog), so it self-hosts on your Postgres (sql/schema.sql + sql/cloud.sql): getUser reads your app's signed-in user instead of a sign-in of its own, page: true serves the admin page from the handler (its script is its own chunk), and examples/admin-demo.mjs runs it with PGlite. Also new on it: Forgot password by code (AdminAuth.sendReset / resetPassword; insforgeAuth has both), invite emails through sendEmail, rate limits kept in Postgres (rateLimits, the new cloud_rate_limits table), openSignup, saveScreenshot, cookieDomain, , and a hook for limits and billing routes (shipcue Cloud's billing lives in its own repo). starts a background Claude Code session per unclaimed report, up to at once while the Claude plan has usage left, claims each report before its session starts, takes over this agent's PRs that stopped moving, and installs itself as a launchd agent (); Setup → Run your agents writes the command. shipcue Cloud moves to , and the site proxies the old URLs there. run again for .

Staying small

shipcue is a report button, a queue, and the tools to work it. A new feature earns a place only if it:

1. Solves something people already do by hand, and the report says what that is.
2. Ships as its smallest useful version first. Every backlog item names that version and what is out of scope.
3. Is opt-in when it costs anything: a prop, a handler option or a project setting, off unless it is the obvious default. The core button, handler and store stay as they are.
4. Never runs code or hosts runners itself. Agents do the work over the agent API and listeners; shipcue coordinates.
5. Adds no runtime dependency unless it truly can't be done without one.

If an idea fails these, it belongs in your app (through formExtras, fields, broadcasters or onReport) rather than in shipcue.

Roadmap

The backlog lives on shipcue's own CueLog as low-priority reports, each with its smallest version and what it leaves out:

• Publish to npm (the package is ready; shipcue doctor shipped in 0.25.0)
• Swarm mode: work-area claims are in (docs/swarm.md); "Work this queue" is next

License

MIT