Fix: cursor-agent Won't Run in Cursor/VS Code Terminal

Problem

When running cursor-agent in the Cursor (or VS Code) integrated terminal, it executes the cursor CLI command instead of the actual cursor-agent, showing the wrong help output and version.

$ cursor-agent --version
# Shows: Cursor 1.7.44 (wrong!)
# Should show: cursor-agent version info

$ cursor-agent --help
# Shows: Cursor CLI help (wrong!)
# Should show: cursor-agent help

Important: This only happens in Cursor/VS Code's integrated terminal. The command works fine in iTerm, Terminal.app, or other external terminals.

Root Cause

The issue is caused by the CURSOR_CLI environment variable that Cursor sets in its integrated terminal. When cursor-agent detects this variable, it forwards all commands to the cursor CLI instead of running itself.

Looking at the cursor-agent source code (index.js):

if(process.env.CURSOR_CLI){
  let w=process.argv[2],
  T=process.argv[process.argv.length-1],
  I=process.argv.some((E)=>E.startsWith("--min-version="));
  if(w==="agent")process.argv.splice(2,1);
  else if(T==="status"&&I);
  else if(w==="editor")return process.argv.splice(2,1),N8t(process.argv.slice(2));
  else return N8t(process.argv.slice(2))  // <-- This forwards to cursor command
}

When CURSOR_CLI is set, cursor-agent delegates to the cursor command by calling N8t() which spawns the cursor binary.

Solution

Unset the problematic environment variables in your Cursor settings. Edit your settings.json (Cmd+Shift+P → "Preferences: Open User Settings (JSON)"):

{
  "terminal.integrated.env.osx": {
    // Add these lines to unset Cursor CLI environment variables
    "CURSOR_CLI": null,
    "CURSOR_AGENT": null
  }
}

For Linux:

{
  "terminal.integrated.env.linux": {
    "CURSOR_CLI": null,
    "CURSOR_AGENT": null
  }
}

For Windows:

{
  "terminal.integrated.env.windows": {
    "CURSOR_CLI": null,
    "CURSOR_AGENT": null
  }
}

After Making Changes

Close all terminal tabs in Cursor
Open a new terminal (Ctrl+ or Cmd+)
Test: cursor-agent --version

Why This Happens

Cursor's integrated terminal sets CURSOR_CLI to enable the cursor CLI to work properly within the terminal
cursor-agent (which is a separate tool) checks for this variable
When found, cursor-agent assumes it should delegate to the cursor command
This is likely an unintended side effect of having both tools check the same environment variable

Alternative Workarounds

Option 1: Shell Alias (if you don't want to modify settings)

Add to your ~/.zshrc or ~/.bashrc:

cursor-agent() {
  env -u CURSOR_CLI -u CURSOR_AGENT /usr/local/bin/cursor-agent "$@"
}

Option 2: One-off Command

env -u CURSOR_CLI -u CURSOR_AGENT cursor-agent --help

Verification

To check if the environment variable is set:

echo $CURSOR_CLI
# If set, will show something like: ELECTRON_RUN_AS_NODE=1 "/Applications/Cursor.app/Contents/MacOS/Cursor" ...

To see all Cursor-related environment variables:

env | grep -i cursor

Credits

Issue discovered and debugged in collaboration with Claude (Anthropic) in October 2024.

johnlindquist/cursor-agent-fix.md