Fix agent mode (#39000)

Make the experimental agent mode work when no anonymous dev deployments exist yet.

GitOrigin-RevId: 4b1aaf800de307bb7c4a558cf21c327c999ec2c1

Author: thomasballinger

npm-packages/convex/src/cli/lib/localDeployment/anonymous.ts

@@ -266,14 +266,8 @@ async function chooseDeployment(
       };
     }
   }
-  if (deployments.length === 0) {
-    logMessage(ctx, "Let's set up your first project.");
-    return await promptForNewDeployment(ctx, []);
-  }
-
   if (process.env.CONVEX_AGENT_MODE === "anonymous") {
     const deploymentName = "anonymous-agent";
-    logVerbose(ctx, `Deployment name: ${deploymentName}`);
     const uniqueName = await getUniqueName(
       ctx,
       deploymentName,
@@ -286,6 +280,11 @@ async function chooseDeployment(
     };
   }
 
+  if (deployments.length === 0) {
+    logMessage(ctx, "Let's set up your first project.");
+    return await promptForNewDeployment(ctx, []);
+  }
+
   if (options.chosenConfiguration === "new") {
     const deploymentName = await promptString(ctx, {
       message: "Choose a name for your new project:",

npm-packages/convex/src/cli/lib/localDeployment/run.ts

@@ -87,7 +87,7 @@ export async function runLocalBackend(
         ),
       });
     } else if (result.status !== 0) {
-      const message = `Failed to run backend binary, exit code ${result.status}, error: ${result.stderr.toString()}`;
+      const message = `Failed to run backend binary, exit code ${result.status}, error: ${result.stderr === null ? "null" : result.stderr.toString()}`;
       return ctx.crash({
         exitCode: 1,
         errorType: "fatal",

npm-packages/docs/docs/ai.mdx

@@ -13,7 +13,7 @@ description: "How to use AI code generation effectively with Convex"
 />
 
 Convex is designed around a small set of composable abstractions with strong
-guarantees that result in code that is not only faster to write, it’s easier to
+guarantees that result in code that is not only faster to write, but easier to
 read and maintain, whether written by a team member or an LLM. Key features make
 sure you get bug-free AI generated code:
 
@@ -57,6 +57,30 @@ 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](https://github.com/get-convex/convex-evals).
 
+## Using Convex with Background Agents
+
+Remote cloud-based coding agents like Jules, Devin, Codex, and Cursor background
+agents can use Convex deployments when the CLI is in
+[Agent Mode](/docs/cli/background-agents.mdx). This limits the permissions
+necessary for these remote dev environments while letting agents run codegen,
+iterate on code, run tests, run one-off functions.
+
+A good setup script for e.g. ChatGPT Codex might include
+
+```
+npm i
+CONVEX_AGENT_MODE=anonymous npx convex dev --once
+```
+
+or
+
+```
+bun i
+CONVEX_AGENT_MODE=anonymous bun x convex dev --once
+```
+
+This command requires "full" internet access to download the binary.
+
 ## Convex MCP Server
 
 [Setup the Convex MCP server](/ai/convex-mcp-server.mdx) to give your AI coding