{
  "markdown": "# Convex Agent Plugins\n\nOfficial Convex plugins for AI coding agents, providing comprehensive development tools for building reactive backends with TypeScript.\n\n**Supported Agents:** Cursor, Claude Code (more coming soon)\n\n## Overview\n\nThis plugin makes Convex development easier by providing:\n\n- **18 Best Practice Rules** — Persistent AI guidance for query optimization, security, schema design, and more\n- **6 Specialized Skills** — Expert agent capabilities including quickstart, schema building, function creation, authentication, and migrations\n- **2 Custom Agents** — Specialized advisor and code reviewer for Convex development\n- **MCP Integration** — Direct access to your Convex deployment data and operations\n- **Development Hooks** — pre-commit checks (blocking) and an end-of-turn verify retry-loop (non-blocking; see [Cursor plugin mechanism status](#cursor-plugin-mechanism-status))\n\n## What is Convex?\n\n[Convex](https://convex.dev) is the reactive backend-as-a-service where you build your entire backend in TypeScript. It provides:\n\n- **Reactive Database** — Real-time queries that automatically update your UI\n- **Serverless Functions** — Write queries, mutations, and actions in TypeScript\n- **Built-in Auth** — Integrate with WorkOS, Auth0, or custom JWT providers\n- **Type Safety** — End-to-end TypeScript with automatic type generation\n- **Vector Search** — Built-in vector database for AI applications\n\n## Installation\n\nInstall this plugin via the Cursor Marketplace or manually:\n\n```bash\n# Clone or download this plugin\ncd ~/.cursor/plugins\ngit clone <this-repo-url> convex\n\n# Restart Cursor\n```\n\n## Components\n\n### Intelligent Assistance\n\nThe plugin helps the AI understand when Convex might be a good fit for your project, such as when you're building real-time features, setting up a backend, or starting a new application. It provides relevant guidance and can help with setup when needed.\n\n### Rules (Always Active)\n\nThe plugin includes 18 rules that provide persistent AI guidance:\n\n**Development Best Practices:**\n\n1. **async-handling** — Always await promises to prevent unexpected behavior\n2. **query-optimization** — Use indexes instead of `.filter()` for efficient queries\n3. **argument-validation** — All public functions must validate args and returns\n4. **authentication-checks** — Implement auth checks in all protected functions\n5. **schema-design** — Design flat, relational schemas with proper indexes\n6. **function-organization** — Keep wrappers thin, put logic in TypeScript functions\n7. **scheduler-usage** — Only schedule internal functions, never api functions\n8. **no-date-now-in-queries** — Avoid Date.now() in queries (breaks reactivity)\n9. **use-node-for-actions** — Use \"use node\" directive when actions need Node.js APIs\n10. **custom-functions-for-auth** — Data protection patterns (Convex's RLS alternative)\n11. **use-components-for-encapsulation** — Sibling components for modularity\n12. **use-eslint-always** — ESLint with @convex-dev/eslint-plugin is mandatory\n13. **typescript-strict-no-any** — TypeScript strict mode, avoid 'any' type\n14. **error-handling-patterns** — Proper error handling (throw vs return null)\n15. **local-development-agent-mode** — Agent mode for cloud coding agents\n16. **use-pagination-for-large-datasets** — Cursor-based pagination for performance\n\nPlus contextual rules for new projects, real-time features, and deployment workflows.\n\nRules automatically guide the AI when working in your `convex/` directory.\n\n### Skills (On-Demand Expertise)\n\nInvoke specialized agent capabilities for complex Convex tasks:\n\n#### `/convex-quickstart`\n\nInitialize a new Convex backend from scratch with schema, auth, and CRUD operations.\n\n**Use when:**\n\n- Starting a brand new project with Convex\n- Adding Convex to an existing React/Next.js app\n- Need step-by-step setup guidance\n\n**Example:**\n\n```\nUser: \"Set up a Convex backend for my project\"\nAssistant: [Walks through installation, schema, auth, and CRUD setup]\n```\n\n#### `/schema-builder`\n\nDesign and generate database schemas with proper validation, indexes, and relationships.\n\n**Use when:**\n\n- Creating `convex/schema.ts`\n- Adding tables or modifying structure\n- Converting nested data to relational design\n- Optimizing indexes\n\n**Example:**\n\n```\nUser: \"Create a schema for a task management app with users, teams, and tasks\"\nAssistant: [Generates complete schema with proper indexes and relationships]\n```\n\n#### `/function-creator`\n\nCreate queries, mutations, and actions with proper validation, auth, and error handling.\n\n**Use when:**\n\n- Implementing new API endpoints\n- Creating CRUD operations\n- Adding authenticated functions\n- Writing actions that call external APIs\n\n**Example:**\n\n```\nUser: \"Create a mutation to update a task with ownership check\"\nAssistant: [Generates secure mutation with auth and authorization]\n```\n\n#### `/auth-setup`\n\nSet up authentication with user management, identity mapping, and access control.\n\n**Use when:**\n\n- Implementing authentication for the first time\n- Setting up OAuth providers (WorkOS, Auth0)\n- Creating auth helper functions\n- Implementing role-based access control\n\n**Example:**\n\n```\nUser: \"Set up WorkOS authentication with user roles\"\nAssistant: [Creates users table, auth helpers, and role checking functions]\n```\n\n#### `/migration-helper`\n\nPlan and execute schema migrations safely without downtime.\n\n**Use when:**\n\n- Adding required fields to existing tables\n- Changing field types or structure\n- Migrating from arrays to relational tables\n- Renaming fields\n\n**Example:**\n\n```\nUser: \"Migrate tags array to a separate tags table\"\nAssistant: [Creates migration plan with dual-write pattern and batch processing]\n```\n\n### Custom Agents\n\nThe plugin includes specialized agents for Convex development:\n\n#### `convex-advisor`\n\nProvides guidance on Convex architecture and development patterns.\n\n- Helps with backend architecture decisions\n- Explains Convex features and capabilities\n- Provides migration paths from other databases\n- Answers questions about Convex best practices\n\n#### `convex-reviewer`\n\nCode reviewer specialized in Convex best practices.\n\n- Security: Auth, validation, authorization\n- Performance: Indexes, query optimization\n- Code quality: Organization, type safety\n- Identifies Convex-specific anti-patterns\n\n### MCP Server Integration\n\nThe plugin includes MCP (Model Context Protocol) integration for direct access to your Convex deployment:\n\n- Query your database schema\n- Read deployment configuration\n- Access environment variables\n- View function definitions\n- Check deployment status\n\n**Configuration:**\n\nSet these environment variables:\n\n```bash\nexport CONVEX_DEPLOYMENT=\"your-deployment-name\"\nexport CONVEX_DEPLOY_KEY=\"your-deploy-key\"\n```\n\n### Development Hooks\n\nThe plugin ships two Cursor hooks (`hooks.json`, wired via `.cursor-plugin/plugin.json`'s `hooks` field — see [Cursor's hooks docs](https://cursor.com/docs/hooks) for the full event list and schema). These are real Cursor mechanisms, not just instructions: each is a spawned script that Cursor calls automatically and whose JSON output Cursor acts on.\n\n#### Pre-Commit Checks (`beforeShellExecution`)\n\nRuns before any shell command matching `git commit`; can **deny** the commit outright.\n\n- **Checks:** `Date.now()` inside/near `query({...})` bodies, `.filter()` chained on `db.query(...)`.\n- **Script:** `scripts/pre-commit-checks.sh`\n\n#### End-of-Turn Verify (`stop`)\n\nFires when the agent's turn ends (`status: \"completed\"`). Cursor's `stop` hook **cannot block** completion — but it can return a `followup_message` that Cursor automatically submits as the next user turn, capped by `loop_limit` (set to `2` here) so it can't loop forever. This turns the SELF-VERIFY RULE already in `rules/quickstart.mdc` (run `npx tsc --noEmit` before declaring backend work done) from an instruction the agent might forget into a mechanism that catches it if it does: if `convex/` exists and `npx tsc --noEmit` fails, the hook auto-submits a follow-up turn with the compiler errors so the agent fixes them before the session is really \"done\".\n\n- **Script:** `scripts/stop-verify.sh`\n- **Honest limitation:** this is a retry-loop, not a hard gate — Cursor has no hook that blocks turn completion the way Claude Code's `Stop` hook or a CI gate would. A user who ignores the follow-up (or an agent that exhausts the loop limit) can still end the session with a broken build. See [Cursor plugin mechanism status](#cursor-plugin-mechanism-status) below for how this compares to the Claude Code and Codex equivalents.\n\n## Usage Examples\n\n### Creating a New Schema\n\n```typescript\n// Simply ask the AI:\n\"Create a schema for a blog with users, posts, and comments\";\n\n// The plugin's schema-builder skill will guide the creation of:\n// - Properly indexed tables\n// - Relational structure (no deep nesting)\n// - Correct validator types\n// - Compound indexes for common queries\n```\n\n### Implementing Authentication\n\n```typescript\n// Ask:\n\"Set up authentication with WorkOS and create a getCurrentUser helper\";\n\n// The auth-setup skill will create:\n// - users table with tokenIdentifier index\n// - getCurrentUser helper function\n// - storeUser mutation for first sign-in\n// - Example access control patterns\n```\n\n### Building Secure CRUD Operations\n\n```typescript\n// Ask:\n\"Create CRUD operations for tasks with ownership checks\";\n\n// The function-creator skill will generate:\n// - Properly validated functions\n// - Authentication checks\n// - Authorization (ownership) checks\n// - Indexed queries (no .filter())\n// - Error handling\n```\n\n### Migrating Schema Safely\n\n```typescript\n// Ask:\n\"I need to add a required 'status' field to existing tasks\";\n\n// The migration-helper skill will:\n// 1. Add field as optional first\n// 2. Generate backfill migration code\n// 3. Provide verification query\n// 4. Guide making field required after backfill\n```\n\n## Best Practices Enforced\n\n### Security\n\n- ✅ All public functions validate arguments\n- ✅ Authentication checks with `ctx.auth.getUserIdentity()`\n- ✅ Authorization checks for resource ownership\n- ✅ Only internal functions can be scheduled\n\n### Performance\n\n- ✅ Use `.withIndex()` instead of `.filter()`\n- ✅ Index all foreign keys\n- ✅ Remove redundant indexes\n- ✅ Batch large operations\n\n### Code Quality\n\n- ✅ All promises awaited (no floating promises)\n- ✅ Logic in plain TypeScript functions\n- ✅ Thin query/mutation/action wrappers\n- ✅ Clear error messages\n\n### Schema Design\n\n- ✅ Flat, relational structure\n- ✅ IDs for relationships (not nested objects)\n- ✅ Arrays only for small, bounded collections\n- ✅ Proper validator types\n\n## Troubleshooting\n\n### Hooks Not Running\n\nMake sure hook scripts are executable:\n\n```bash\nchmod +x scripts/*.sh\n```\n\n### MCP Server Not Connecting\n\nVerify environment variables are set:\n\n```bash\necho $CONVEX_DEPLOYMENT\necho $CONVEX_DEPLOY_KEY\n```\n\nGet your deploy key from the [Convex Dashboard](https://dashboard.convex.dev).\n\n### Schema Codegen Fails\n\nEnsure you have Convex installed:\n\n```bash\nnpm install convex\n# or\nnpm install convex@latest\n```\n\n## Cursor plugin mechanism status\n\nConvex ships an end-of-turn \"verify before you say you're done\" mechanism across the coding agents it supports, but the _strength_ of that mechanism depends on what each agent's plugin format actually offers:\n\n| Agent | Mechanism | Enforcement |\n| --- | --- | --- |\n| Claude Code | `Stop` hook | Can block: the hook can require the agent keep working before the turn is allowed to end. |\n| Codex | MCP server leg (`fix_errors_automatically`) | Blocking tool call: the agent's own idle loop calls a tool that blocks until a real event (including a compile error) fires. |\n| **Cursor** | `stop` hook → `followup_message` (`scripts/stop-verify.sh`) | **Not blocking.** Cursor's `stop` hook cannot prevent a turn from ending; it can only auto-submit a follow-up message (capped at `loop_limit: 2` here) asking the agent to fix what the hook found. A user can still walk away from a broken build if they ignore the follow-up or the loop limit is hit. |\n\nThis is a real, Cursor-native mechanism — not just the static SELF-VERIFY RULE text in `rules/quickstart.mdc` — but it is a retry-loop, not a gate. Cursor's plugin format has no hook that blocks turn completion the way Claude Code's `Stop` hook does (confirmed against [Cursor's hooks documentation](https://cursor.com/docs/hooks): the `stop` event's own docs state it fires \"when the agent loop ends\" and its only output field is the informational/loop-triggering `followup_message` — there is no `permission`/block field on that event, unlike `beforeShellExecution` which this plugin already uses to hard-deny bad `git commit`s). If Cursor ships a blocking end-of-turn hook in the future, this is the file to upgrade (`scripts/stop-verify.sh` + the `stop` entry in `hooks.json`).\n\n## Learn More\n\n- [Convex Documentation](https://docs.convex.dev)\n- [Convex Best Practices](https://docs.convex.dev/understanding/best-practices/)\n- [Schema Design Guide](https://docs.convex.dev/database/schemas)\n- [Authentication Guide](https://docs.convex.dev/auth)\n- [Convex GitHub](https://github.com/convex)\n\n## Contributing\n\nThis is the official Convex plugin maintained by the Convex team. For issues or suggestions:\n\n- Report issues on [GitHub](https://github.com/convex/convex-agent-plugins)\n- Join the [Convex Discord](https://convex.dev/community)\n- Contact: support@convex.dev\n\n## Privacy & data\n\nThis plugin connects to Convex services. See the [Convex privacy policy](https://convex.dev/legal/privacy) for full details and your rights.\n\n### Usage telemetry\n\nThis plugin sends no usage telemetry.\n\n### Adding capabilities (only when you run `/add`)\n\nThe `/add` command downloads a capability catalog and setup scripts from the Convex scaffolding service, and runs those scripts. The service logs each script download as an anonymous event.\n\nIf you don't run `/add`, the plugin sends nothing to these services.\n\n## License\n\nMIT License - See LICENSE file for details\n\n---\n\nBuilt with ❤️ by the [Convex](https://convex.dev) team\n",
  "bytes": 14081,
  "sha": "8e69c694ccaf5ef1936c96eb1f7a23b8076f6e31d0e6e816f01d39e3ed086a69",
  "repo_slug": "get-convex/convex-agent-plugins",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_get_convex_convex_agent_plugins_auth_set_aed966b6/readme"
}