convex-advisor

Diagnose Convex deployment performance and cost issues from 72-hour runtime insights.

Updated Sep 17, 2026
One-click install
npx skills add https://github.com/Tehzeeb07/CodeRush --skill convex-advisor-tehzeeb07
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: convex-advisor
Source: https://github.com/Tehzeeb07/CodeRush/tree/main/.agents/skills/convex-advisor
Command: npx skills add https://github.com/Tehzeeb07/CodeRush --skill convex-advisor-tehzeeb07

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Static code review can only guess at performance problems, while a live Convex deployment already knows which functions hit read limits, scan too many bytes, or suffer OCC write contention. This Skill reads the deployment's own 72-hour insight events and turns each one into an evidence-backed, root-caused finding with a concrete fix. ## Core Features & Use Cases - Runtime insight analysis: Reads typed 72h health events (documentsReadLimit, bytesReadThreshold, occRetried, occFailedPermanently) via the official Convex MCP tools. - Code-level root cause: Traces each event to the exact function and line, identifying unindexed filters, missing pagination, or read-modify-write hotspots. - Structured findings: Emits findings with severity, evidence, and fix capability on a findings bus so fixers can be dispatched. - Use Case: Your messages:list query read 4.2MB from the messages table 31 times yesterday. The advisor pinpoints the missing index, recommends .withIndex or .paginate, and applies the fix on confirmation. ## Quick Start Ask the advisor to check my Convex deployment's recent insights and root-cause any performance or contention issues it finds.

Frequently Asked Questions about convex-advisor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find performance problems in my Convex deployment?▼

Use the Convex MCP insights tool to read typed 72-hour health events per function, covering read limits, byte thresholds, and OCC contention. The advisor then reads the flagged function's code to root-cause each event and propose a fix.

How to fix OCC contention and failed mutations in Convex?▼

OCC failures come from read-modify-write hotspots on a shared document, such as counters or status toggles. Fixes include the @convex-dev/sharded-counter component, narrowing the read set, or moving contention to a workpool.

Why does my Convex query hit the documents read limit?▼

Read limit hits usually come from .collect() on large tables, unindexed .filter() calls, or missing pagination. The fix is adding an index with .withIndex, bounding results with .take(n), or switching to .paginate.

Does the Convex insights tool work on all deployments?▼

The insights tool is only available on cloud dev and prod deployments when logged in as a user, not on previews or deploy-key-scoped contexts. It also needs roughly 72 hours of traffic before events appear.

Can the advisor modify my production Convex deployment?▼

No. An advisory pass is strictly read-only and never enables mutating prod access. Fixes are only applied after explicit user confirmation, and insight trends are re-checked afterward to verify improvement.