Convex

Scaffold a new Convex app from a one-sentence idea and build it live — a Next.js + shadcn app with a floating Chef panel (progress feed, todo checklist, inline refinement questions, feature-request form), dev servers and error watchers already running.

Convex backend specialist. Use this agent for any code inside a `convex/` directory — function definitions, schemas, indexes, queries, mutations, actions, HTTP endpoints, cron jobs, file storage, auth wiring, and component installation. Knows the object-form function syntax, validator patterns, resource limits, and component ecosystem that generic Claude routinely gets wrong.

Design and build reactive, type-safe, production-grade backends on Convex. Covers schema, queries/mutations/actions, indexes, auth, file storage, scheduling, real-time multiplayer, mobile backends, and LLM/agent workflows on Convex's one-platform stack.

Scaffold a brand-new Convex app from a one-sentence idea and build it live in front of the user — a Next.js + shadcn 'wow-shell' with a floating Chef panel (live progress feed, pulsing todo checklist, inline refinement questions, and a feature-request form), backed by `convex dev` + `next dev` with error watchers already armed. Use this to go from idea → running, watchable app in under a minute, then iterate.

3 hooks across 3 events

A user just submitted (or upvoted into the queue) a feature request via the Chef/ship panel in a quickstart 'wow-shell' app. This monitor polls `npx convex run featureRequests:listPending` (state==="requested", newest first) every ~12s and notifies only on request `_id`s that were NOT present in the previous poll — so each notification is a genuinely NEW request, not a replay. It exists because the wow-shell's feature-request form is the user's primary way to drive iteration after launch, and there is otherwise no push: without this the agent has to keep a turn open polling the bootstrap's feature-requests.log, and a request submitted after the agent yields sits unhandled until the user asks 'hello?'. When this fires, the playbook (same as STEP B of the quickstart skill): (1) read the full request with `npx convex run featureRequests:listPending` (or the panel) — you get its title, description, and _id; (2) `npx convex run featureRequests:setState '{"id":"<_id>","state":"inProgress"}'` so the user's badge updates; (3) build the feature (write the component file first, then wire it into app/page.tsx; never touch app/_chef-panel.tsx or the <ChefPanel/> mount); (4) `featureRequests:setState ... "completed"`. Do requests one at a time in order — the badge transitions are the user's feedback loop. Self-guards: it silently no-ops unless `.env.local` has `CONVEX_DEPLOYMENT` set and `npx` is on PATH, and `listPending` returning nothing/erroring (e.g. a non-wow-shell project that lacks the function) produces no output, so it is safe in any cwd. Unlike the OCC-insights monitor it intentionally DOES run against anonymous/local deployments, because the featureRequests table exists there too. The first poll after arming is saved as a baseline without notifying, so the requests already queued when you start don't all fire at once.

The linked Convex cloud deployment has a fresh insight in `npx convex insights`: a new OCC (optimistic concurrency control) write conflict or a read-limit issue surfaced in the last 72h of deployment health data. This monitor polls `npx convex insights` every 10 minutes, filters to substantive lines (occRetried, occFailedPermanently, documentsRead/bytesRead Limit or Threshold), and notifies only on lines that were not present in the previous snapshot — so each notification means something NEW went wrong, not a replay of old history. When this fires, the playbook is: (1) For occRetried/occFailedPermanently — identify the function and table involved, shrink the transaction (read less, write less, finish faster), move contended counters or aggregates to the @convex-dev/aggregate or @convex-dev/sharded-counter components, and avoid read-modify-write patterns on hot documents that many mutations touch concurrently. (2) For documentsRead/bytesRead Limit or Threshold — the function is scanning too much data: add a .withIndex() to narrow the scan to exactly the rows needed, or switch to .paginate() instead of .collect() on large tables. Run `npx convex insights --details` for per-event detail showing exactly which function and table are conflicting or over-reading. Caveats: `npx convex insights` only works for cloud deployments with user-level auth — it errors on local/anonymous deployments and refuses deploy keys/project keys — so this monitor hard-guards and silently no-ops in those cases (no .env.local, CONVEX_DEPLOYMENT=anonymous, missing npx, or any non-zero/empty `npx convex insights` run). The first successful poll after arming is saved as a baseline without notifying, so stale 72h-old insights never fire on startup.

The linked Convex cloud deployment has a fresh insight in `npx convex insights`: a new OCC (optimistic concurrency control) write conflict or a read-limit issue surfaced in the last 72h of deployment health data. This monitor polls `npx convex insights` every 10 minutes, filters to substantive lines (occRetried, occFailedPermanently, documentsRead/bytesRead Limit or Threshold), and notifies only on lines that were not present in the previous snapshot — so each notification means something NEW went wrong, not a replay of old history. When this fires, the playbook is: (1) For occRetried/occFailedPermanently — identify the function and table involved, shrink the transaction (read less, write less, finish faster), move contended counters or aggregates to the @convex-dev/aggregate or @convex-dev/sharded-counter components, and avoid read-modify-write patterns on hot documents that many mutations touch concurrently. (2) For documentsRead/bytesRead Limit or Threshold — the function is scanning too much data: add a .withIndex() to narrow the scan to exactly the rows needed, or switch to .paginate() instead of .collect() on large tables. Run `npx convex insights --details` for per-event detail showing exactly which function and table are conflicting or over-reading. Caveats: `npx convex insights` only works for cloud deployments with user-level auth — it errors on local/anonymous deployments and refuses deploy keys/project keys — so this monitor hard-guards and silently no-ops in those cases (no .env.local, CONVEX_DEPLOYMENT=anonymous, missing npx, or any non-zero/empty `npx convex insights` run). The first successful poll after arming is saved as a baseline without notifying, so stale 72h-old insights never fire on startup.

A Convex function in the live deployment just emitted an error or exception (useQuery/useMutation/useAction call, scheduled function, cron, or HTTP action). This monitor streams `npx convex logs` from the linked deployment and surfaces any matched line as a notification, so you find out about server-side failures the moment they happen instead of waiting for the user to report a broken UI. When this fires: read the full log line for context (function name, error class, stack), look up the cause in the Runtime Errors table inside the skill, fix the file, and let `convex dev` push the new version. The command self-guards: if there's no `.env.local` with `CONVEX_DEPLOYMENT` set, or `npx` isn't on PATH, it loops silently every 30s without producing notifications or errors — so it's safe in any cwd, including empty directories or non-Convex projects. If `npx convex logs` exits mid-session (transient auth/network issue), the loop sleeps 30s and retries automatically. If the matched line mentions an OCC conflict, also check the convex-occ-insights monitor or run `npx convex insights --details` to see which function and table are conflicting.

A Convex function in the live deployment just emitted an error or exception (useQuery/useMutation/useAction call, scheduled function, cron, or HTTP action). This monitor streams `npx convex logs` from the linked deployment and surfaces any matched line as a notification, so you find out about server-side failures the moment they happen instead of waiting for the user to report a broken UI. When this fires: read the full log line for context (function name, error class, stack), look up the cause in the Runtime Errors table inside the skill, fix the file, and let `convex dev` push the new version. The command self-guards: if there's no `.env.local` with `CONVEX_DEPLOYMENT` set, or `npx` isn't on PATH, it loops silently every 30s without producing notifications or errors — so it's safe in any cwd, including empty directories or non-Convex projects. If `npx convex logs` exits mid-session (transient auth/network issue), the loop sleeps 30s and retries automatically. If the matched line mentions an OCC conflict, also check the convex-occ-insights monitor or run `npx convex insights --details` to see which function and table are conflicting.