Skip to content
Back to search

convex-agent-plugins

An plugin for cursor to empower it to build the best apps ever.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/convex/convex-agent-plugins with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/convex/convex-agent-plugins'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/convex--convex-agent-plugins/badge.svg)](/listings/convex--convex-agent-plugins)

HTML

<a href="/listings/convex--convex-agent-plugins"><img src="/api/listings/convex--convex-agent-plugins/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install this plugin via the Cursor Marketplace or manually:

# Clone or download this plugin
cd ~/.cursor/plugins
git clone <this-repo-url> convex

# Restart Cursor

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 388 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Convex Agent Plugins
  2. Official Convex plugins for AI coding agents, providing comprehensive development tools for building reactive backends with TypeScript.
  3. **Supported Agents:** Cursor, Claude Code (more coming soon)
  4. ## Overview
  5. This plugin makes Convex development easier by providing:
  6. - **18 Best Practice Rules** — Persistent AI guidance for query optimization, security, schema design, and more
  7. - **6 Specialized Skills** — Expert agent capabilities including quickstart, schema building, function creation, authentication, and migrations
  8. - **2 Custom Agents** — Specialized advisor and code reviewer for Convex development
  9. - **MCP Integration** — Direct access to your Convex deployment data and operations
  10. - **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))
  11. ## What is Convex?
  12. [Convex](https://convex.dev) is the reactive backend-as-a-service where you build your entire backend in TypeScript. It provides:
  13. - **Reactive Database** — Real-time queries that automatically update your UI
  14. - **Serverless Functions** — Write queries, mutations, and actions in TypeScript
  15. - **Built-in Auth** — Integrate with WorkOS, Auth0, or custom JWT providers
  16. - **Type Safety** — End-to-end TypeScript with automatic type generation
  17. - **Vector Search** — Built-in vector database for AI applications
  18. ## Installation
  19. Install this plugin via the Cursor Marketplace or manually:
  20. ```bash
  21. # Clone or download this plugin
  22. cd ~/.cursor/plugins
  23. git clone <this-repo-url> convex
  24. # Restart Cursor
  25. ```
  26. ## Components
  27. ### Intelligent Assistance
  28. The 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.
  29. ### Rules (Always Active)
  30. The plugin includes 18 rules that provide persistent AI guidance:
  31. **Development Best Practices:**
  32. 1. **async-handling** — Always await promises to prevent unexpected behavior
  33. 2. **query-optimization** — Use indexes instead of `.filter()` for efficient queries
  34. 3. **argument-validation** — All public functions must validate args and returns
  35. 4. **authentication-checks** — Implement auth checks in all protected functions
  36. 5. **schema-design** — Design flat, relational schemas with proper indexes
  37. 6. **function-organization** — Keep wrappers thin, put logic in TypeScript functions
  38. 7. **scheduler-usage** — Only schedule internal functions, never api functions
  39. 8. **no-date-now-in-queries** — Avoid Date.now() in queries (breaks reactivity)
  40. 9. **use-node-for-actions** — Use "use node" directive when actions need Node.js APIs
  41. 10. **custom-functions-for-auth** — Data protection patterns (Convex's RLS alternative)
  42. 11. **use-components-for-encapsulation** — Sibling components for modularity
  43. 12. **use-eslint-always** — ESLint with @convex-dev/eslint-plugin is mandatory
  44. 13. **typescript-strict-no-any** — TypeScript strict mode, avoid 'any' type
  45. 14. **error-handling-patterns** — Proper error handling (throw vs return null)
  46. 15. **local-development-agent-mode** — Agent mode for cloud coding agents
  47. 16. **use-pagination-for-large-datasets** — Cursor-based pagination for performance
  48. Plus contextual rules for new projects, real-time features, and deployment workflows.
  49. Rules automatically guide the AI when working in your `convex/` directory.
  50. ### Skills (On-Demand Expertise)
  51. Invoke specialized agent capabilities for complex Convex tasks:
  52. #### `/convex-quickstart`
  53. Initialize a new Convex backend from scratch with schema, auth, and CRUD operations.
  54. **Use when:**
  55. - Starting a brand new project with Convex
  56. - Adding Convex to an existing React/Next.js app
  57. - Need step-by-step setup guidance
  58. **Example:**
  59. ```
  60. User: "Set up a Convex backend for my project"
  61. Assistant: [Walks through installation, schema, auth, and CRUD setup]
  62. ```
  63. #### `/schema-builder`
  64. Design and generate database schemas with proper validation, indexes, and relationships.
  65. **Use when:**
  66. - Creating `convex/schema.ts`
  67. - Adding tables or modifying structure
  68. - Converting nested data to relational design
  69. - Optimizing indexes
  70. **Example:**
  71. ```
  72. User: "Create a schema for a task management app with users, teams, and tasks"
  73. Assistant: [Generates complete schema with proper indexes and relationships]
  74. ```
  75. #### `/function-creator`
  76. Create queries, mutations, and actions with proper validation, auth, and error handling.
  77. **Use when:**
  78. - Implementing new API endpoints
  79. - Creating CRUD operations
  80. - Adding authenticated functions
  81. - Writing actions that call external APIs
  82. **Example:**
  83. ```
  84. User: "Create a mutation to update a task with ownership check"
  85. Assistant: [Generates secure mutation with auth and authorization]
  86. ```
  87. #### `/auth-setup`
  88. Set up authentication with user management, identity mapping, and access control.
  89. **Use when:**
  90. - Implementing authentication for the first time
  91. - Setting up OAuth providers (WorkOS, Auth0)
  92. - Creating auth helper functions
  93. - Implementing role-based access control
  94. **Example:**
  95. ```
  96. User: "Set up WorkOS authentication with user roles"
  97. Assistant: [Creates users table, auth helpers, and role checking functions]
  98. ```
  99. #### `/migration-helper`
  100. Plan and execute schema migrations safely without downtime.
  101. **Use when:**
  102. - Adding required fields to existing tables
  103. - Changing field types or structure
  104. - Migrating from arrays to relational tables
  105. - Renaming fields
  106. **Example:**
  107. ```
  108. User: "Migrate tags array to a separate tags table"
  109. Assistant: [Creates migration plan with dual-write pattern and batch processing]
  110. ```
  111. ### Custom Agents
  112. The plugin includes specialized agents for Convex development:
  113. #### `convex-advisor`
  114. Provides guidance on Convex architecture and development patterns.
  115. - Helps with backend architecture decisions
  116. - Explains Convex features and capabilities
  117. - Provides migration paths from other databases
  118. - Answers questions about Convex best practices
  119. #### `convex-reviewer`
  120. Code reviewer specialized in Convex best practices.
  121. - Security: Auth, validation, authorization
  122. - Performance: Indexes, query optimization
  123. - Code quality: Organization, type safety
  124. - Identifies Convex-specific anti-patterns
  125. ### MCP Server Integration
  126. The plugin includes MCP (Model Context Protocol) integration for direct access to your Convex deployment:
  127. - Query your database schema
  128. - Read deployment configuration
  129. - Access environment variables
  130. - View function definitions
  131. - Check deployment status
  132. **Configuration:**
  133. Set these environment variables:
  134. ```bash
  135. export CONVEX_DEPLOYMENT="your-deployment-name"
  136. export CONVEX_DEPLOY_KEY="your-deploy-key"
  137. ```
  138. ### Development Hooks
  139. The 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.
  140. #### Pre-Commit Checks (`beforeShellExecution`)
  141. Runs before any shell command matching `git commit`; can **deny** the commit outright.
  142. - **Checks:** `Date.now()` inside/near `query({...})` bodies, `.filter()` chained on `db.query(...)`.
  143. - **Script:** `scripts/pre-commit-checks.sh`
  144. #### End-of-Turn Verify (`stop`)
  145. Fires 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".
  146. - **Script:** `scripts/stop-verify.sh`
  147. - **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.
  148. ## Usage Examples
  149. ### Creating a New Schema
  150. ```typescript
  151. // Simply ask the AI:
  152. "Create a schema for a blog with users, posts, and comments";
  153. // The plugin's schema-builder skill will guide the creation of:
  154. // - Properly indexed tables
  155. // - Relational structure (no deep nesting)
  156. // - Correct validator types
  157. // - Compound indexes for common queries
  158. ```
  159. ### Implementing Authentication
  160. ```typescript
  161. // Ask:
  162. "Set up authentication with WorkOS and create a getCurrentUser helper";
  163. // The auth-setup skill will create:
  164. // - users table with tokenIdentifier index
  165. // - getCurrentUser helper function
  166. // - storeUser mutation for first sign-in
  167. // - Example access control patterns
  168. ```
  169. ### Building Secure CRUD Operations
  170. ```typescript
  171. // Ask:
  172. "Create CRUD operations for tasks with ownership checks";
  173. // The function-creator skill will generate:
  174. // - Properly validated functions
  175. // - Authentication checks
  176. // - Authorization (ownership) checks
  177. // - Indexed queries (no .filter())
  178. // - Error handling
  179. ```
  180. ### Migrating Schema Safely
  181. ```typescript
  182. // Ask:
  183. "I need to add a required 'status' field to existing tasks";
  184. // The migration-helper skill will:
  185. // 1. Add field as optional first
  186. // 2. Generate backfill migration code
  187. // 3. Provide verification query
  188. // 4. Guide making field required after backfill
  189. ```
  190. ## Best Practices Enforced
  191. ### Security
  192. - ✅ All public functions validate arguments
  193. - ✅ Authentication checks with `ctx.auth.getUserIdentity()`
  194. - ✅ Authorization checks for resource ownership
  195. - ✅ Only internal functions can be scheduled
  196. ### Performance
  197. - ✅ Use `.withIndex()` instead of `.filter()`
  198. - ✅ Index all foreign keys
  199. - ✅ Remove redundant indexes
  200. - ✅ Batch large operations
  201. ### Code Quality
  202. - ✅ All promises awaited (no floating promises)
  203. - ✅ Logic in plain TypeScript functions
  204. - ✅ Thin query/mutation/action wrappers
  205. - ✅ Clear error messages
  206. ### Schema Design
  207. - ✅ Flat, relational structure
  208. - ✅ IDs for relationships (not nested objects)
  209. - ✅ Arrays only for small, bounded collections
  210. - ✅ Proper validator types
  211. ## Troubleshooting
  212. ### Hooks Not Running
  213. Make sure hook scripts are executable:
  214. ```bash
  215. chmod +x scripts/*.sh
  216. ```
  217. ### MCP Server Not Connecting
  218. Verify environment variables are set:
  219. ```bash
  220. echo $CONVEX_DEPLOYMENT
  221. echo $CONVEX_DEPLOY_KEY
  222. ```
  223. Get your deploy key from the [Convex Dashboard](https://dashboard.convex.dev).
  224. ### Schema Codegen Fails
  225. Ensure you have Convex installed:
  226. ```bash
  227. npm install convex
  228. # or
  229. npm install convex@latest
  230. ```
  231. ## Cursor plugin mechanism status
  232. Convex 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:
  233. | Agent | Mechanism | Enforcement |
  234. | --- | --- | --- |
  235. | Claude Code | `Stop` hook | Can block: the hook can require the agent keep working before the turn is allowed to end. |
  236. | 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. |
  237. | **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. |
  238. This 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`).
  239. ## Learn More
  240. - [Convex Documentation](https://docs.convex.dev)
  241. - [Convex Best Practices](https://docs.convex.dev/understanding/best-practices/)
  242. - [Schema Design Guide](https://docs.convex.dev/database/schemas)
  243. - [Authentication Guide](https://docs.convex.dev/auth)
  244. - [Convex GitHub](https://github.com/convex)
  245. ## Contributing
  246. This is the official Convex plugin maintained by the Convex team. For issues or suggestions:
  247. - Report issues on [GitHub](https://github.com/convex/convex-agent-plugins)
  248. - Join the [Convex Discord](https://convex.dev/community)
  249. - Contact: support@convex.dev
  250. ## Privacy & data
  251. This plugin connects to Convex services. See the [Convex privacy policy](https://convex.dev/legal/privacy) for full details and your rights.
  252. ### Usage telemetry
  253. This plugin sends no usage telemetry.
  254. ### Adding capabilities (only when you run `/add`)
  255. The `/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.
  256. If you don't run `/add`, the plugin sends nothing to these services.
  257. ## License
  258. MIT License - See LICENSE file for details
  259. ---
  260. Built with ❤️ by the [Convex](https://convex.dev) team

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.