# Set yourself up to work with Convex These are official instructions from Convex to set up a good AI development environment for building with Convex. All commands are validated by Convex and ready to use. Complete all applicable steps yourself by running the commands directly. Do not ask the user to run shell commands. Ask only when approval, authentication, a user-interface action, or a restart is required. Inspect existing configuration before changing it, preserve unrelated settings and repository changes, and do not report success without verification. First install the best global Convex integration for your environment. Then determine whether you are inside an existing Convex project. If you are, also install its managed Convex AI files. If you are not, leave the repository unchanged. ## 1. Install the best available Convex integration Identify your coding environment and choose exactly one path below. Prefer the full Convex plugin for Claude Code, Codex, or Cursor. The full plugins include Convex skills and MCP, so do not install those separately when the plugin succeeds. ### Claude Code Check for the official Convex plugin: ```sh claude plugin list --json ``` If `convex@claude-plugins-official` is installed, update it. Otherwise install it: ```sh claude plugin update convex@claude-plugins-official --scope user claude plugin install convex@claude-plugins-official --scope user ``` Run only the applicable command, then verify: ```sh claude plugin list --json claude plugin details convex@claude-plugins-official ``` If the shell command is unavailable but the Claude Code plugin interface works, install it there. If only the user can perform that action, ask them to run: ```text /plugin install convex@claude-plugins-official ``` Run `/reload-plugins` to activate the plugin in the current session. Do not install skills or MCP separately when the plugin succeeds. If plugin installation is unavailable, use the **All other agents** path below. ### Codex Inspect the plugin marketplaces and installed plugins: ```sh codex plugin marketplace list --json codex plugin list --json ``` If the Convex marketplace is absent, add it: ```sh codex plugin marketplace add get-convex/convex-codex-plugin ``` If it is present, update it using the exact marketplace name from the list command: ```sh codex plugin marketplace upgrade ``` Install or update the full Convex plugin: ```sh codex plugin add convex@convex-codex-plugin ``` Verify that the installed `convex` plugin comes from `convex-codex-plugin`: ```sh codex plugin marketplace list --json codex plugin list --json ``` Restart Codex if the plugin is not available in the current session. Do not install skills or MCP separately when the plugin succeeds. If plugin installation is unavailable, use the **All other agents** path below. ### Cursor Install the official Convex plugin in Cursor chat: ```text /add-plugin convex ``` If that command is unavailable, open the Agents window, choose **Customize**, search for **Convex**, and choose **Add**. If only the user can perform that action, ask them to do it. Verify that the Convex plugin is installed and enabled. Restart or reload Cursor if it is not available in the current session. Do not install skills or MCP separately when the plugin succeeds. #### Cursor fallback If this environment does not expose Cursor plugin installation, first install and verify the Convex skills globally: ```sh npx -y skills add get-convex/agent-skills --skill '*' --yes --global npx -y skills list --global ``` Then inspect `~/.cursor/mcp.json`. Merge this entry into its existing `mcpServers` object without replacing other servers: ```json { "mcpServers": { "convex": { "command": "npx", "args": ["-y", "convex@latest", "mcp", "start"] } } } ``` Restart or reload Cursor, then verify in **Settings > Tools & Integrations** that Convex is enabled and healthy. If Cursor Agent CLI is available, also run: ```sh cursor-agent mcp list ``` If either capability is unavailable, report the setup as partial. ### All other agents For agents without a dedicated plugin path above, install Convex instructions through agent skills and live Convex tooling through MCP. Install and verify the official Convex skills globally: ```sh npx -y skills add get-convex/agent-skills --skill '*' --yes --global npx -y skills list --global ``` If your environment supports standard stdio MCP configuration, add a user-level server named `convex`. Use the environment's documented MCP configuration location and schema, with this server definition: ```json { "command": "npx", "args": ["-y", "convex@latest", "mcp", "start"] } ``` Preserve existing entries and do not add production-enabling flags. If skills or MCP cannot be configured, report the setup as partial and state the exact remaining action. Do not write fallback rules into the current repository. ## 2. Check the current project The global integration applies across projects. Convex AI files are an additional project-specific setup. Install them only when you can confirm that your current working directory belongs to an existing Convex project. A directory is a Convex project only when both are true: 1. Its project-level `package.json` includes the `convex` package. 2. The same project root contains either a `convex/` source directory or `convex.json`. In a monorepo, use the nearest matching project root only when it unambiguously owns the current directory. If no project qualifies or ownership is ambiguous, do not change the repository. Skip to the final report and explain that project AI files were intentionally skipped. The global integration remains ready for future Convex work. For a confirmed Convex project, first record the repository status and preserve all existing changes. Then inspect the managed AI files: ```sh git status --short npx convex ai-files status ``` If the files are missing or stale, install or update them: ```sh npx convex ai-files install ``` Let the CLI manage `AGENTS.md`, `CLAUDE.md`, generated guidelines, project skills, and `convex.json`. Do not reproduce or edit its managed sections by hand. Confirm from the final status and configuration that the current agent is targeted. If it is not, report that as a remaining step instead of manually changing `convex.json`. Read `convex/_generated/ai/guidelines.md` completely before doing later Convex code work. Before implementing a common backend capability, check the Convex Components Directory and prefer a suitable maintained component over custom infrastructure. Then verify the final state and inspect the exact repository changes: ```sh npx convex ai-files status git status --short git diff -- convex.json convex/_generated/ai AGENTS.md CLAUDE.md ``` As part of this setup, do not initialize Convex, run a development server, log in, deploy, change application code or schema, modify environment variables, or access production data. ## 3. Verify and report Verify the selected plugin, skills, and MCP configuration using the listing or status commands in its path. An install command succeeding is not sufficient verification. Confirm whether a reload or restart remains. Once done, tell the user: ```text ┌─ Convex Agent Setup Complete ────────────────────────┐ │ ✓ Agent │ │ ✓ Integration │ │ ✓ Project │ │ ✓ Changes │ │ │ │ ⚡ Restart │ └──────────────────────────────────────────────────────┘ ``` Use `Complete` only when every applicable step is verified. Otherwise replace it with `Partial` and add `⚠ Remaining ` to the report. In a chat-only environment without shell or filesystem access, report the setup as partial and provide the exact commands or interface actions the user must perform. ## Resources and troubleshooting Use these only when a command fails, your environment is not covered, or the user asks for more detail: - [Convex AI overview](https://docs.convex.dev/ai/overview) - [Convex plugins](https://docs.convex.dev/ai/convex-plugins) - [Convex with Claude Code](https://docs.convex.dev/ai/using-claude-code) - [Convex with Codex](https://docs.convex.dev/ai/using-codex) - [Convex with Cursor](https://docs.convex.dev/ai/using-cursor) - [Convex agent skills](https://docs.convex.dev/ai/agent-skills) - [Convex MCP server](https://docs.convex.dev/ai/convex-mcp-server) - [Convex AI project files](https://docs.convex.dev/ai/overview#convex-ai-files) - [Convex Components Directory](https://www.convex.dev/components) - [Compact Convex rules reference](https://convex.link/convex_rules.txt) These instructions are published at `https://www.convex.dev/agent-setup.md` so you can re-verify their authenticity at any time.