Skip to main content

Using Claude Code with Convex

Claude Code, Anthropic's agentic coding tool, makes it easy to write and maintain apps built with Convex. Let's walk through how to set up Claude Code for the best possible results with Convex.

Starting a new project​

From an empty directory, launch Claude Code with what you want to build:

claude "build me a todo app with Convex"

Claude Code handles the rest. It runs npm create convex@latest, npx convex ai-files install (which writes a managed Convex section into CLAUDE.md and installs Convex Agent Skills into .agents/skills/), and npx convex dev --once, which auto-provisions a local backend without prompting for login because the agent's shell is non-interactive.

After the initial setup, leave npx convex dev running in a separate terminal so Claude Code always sees up-to-date generated types. Without it the agent can get stuck in a linting loop.

If you'd rather scaffold the project yourself first and then bring in Claude Code, the manual sequence is:

npm create convex@latest my-app
cd my-app
npx convex ai-files install
claude

Adding to an existing project​

If your project already has Convex set up, run these two steps from the project root to make Claude Code Convex-aware.

Add Convex Rules​

The Convex CLI can install and maintain a managed section in your project's CLAUDE.md file that teaches Claude Code about Convex conventions and best practices.

npx convex ai-files install

This will create or update CLAUDE.md and install Convex Agent Skills into .agents/skills/ so Claude can use specialized workflows like setting up auth, designing a schema, and running migrations.

See Convex AI files for more on managing these files.

We're constantly working on improving the quality of these rules for Convex by using rigorous evals. You can help by contributing to our evals repo.

Setup the Convex MCP Server​

The Convex CLI comes with a Convex Model Context Protocol (MCP) server built in. The Convex MCP server gives Claude Code access to your Convex deployment to query and optimize your project.

Add the MCP server with:

claude mcp add-json convex '{"type":"stdio","command":"npx","args":["convex","mcp","start"]}'

You can verify it's installed by running:

claude mcp get convex

Now start asking Claude Code questions like:

  • Evaluate my convex schema and suggest improvements
  • What are this app's public endpoints?
  • Run the my_convex_function query

Running Claude Code with Convex in the cloud​

When running Claude Code in a remote environment (e.g. Claude Code on a CI runner or a cloud VM), use Convex's Agent Mode so the agent can iterate on code, run tests, and call one-off functions without needing full deployment permissions.

A good setup script:

npm i
npx convex dev --once

In non-interactive shells (the typical case for an agent's setup script), npx convex won't prompt the agent to log in. It provisions a local deployment automatically. See Agent Mode → Local backend for details.

This command requires "full" internet access to download the Convex binary.

For per-agent cloud dev deployments scoped to a single throwaway deploy key, see Cloud dev deployments per agent.