Cursor Agent

The Cursor agent plugin integrates with Cursor's cursor CLI to execute AI coding tasks. It supports multiple execution modes, auto-approve for autonomous operation, and model selection.

INFO

Cursor supports subagent tracing via JSONL output - Ralph TUI can show tool calls in real-time as Cursor works.

Prerequisites

Install Cursor CLI from docs.cursor.com/cli.

Verify installation:

Bash

cursor --version

Basic Usage

Run with Cursor

Use the --agent cursor flag:

Bash

ralph-tui run --prd ./prd.json --agent cursor

Select a Model

Override the model with --model:

Bash

ralph-tui run --prd ./prd.json --agent cursor --model claude-4.5-sonnet

Configure Execution Mode

Set the execution mode in config:

TOML

[agentOptions]
mode = "agent"

Configuration

Shorthand Config

The simplest configuration:

TOML

# .ralph-tui/config.toml
agent = "cursor"
 
[agentOptions]
model = "claude-4.5-sonnet"

Full Config

For advanced control:

TOML

[[agents]]
name = "my-cursor"
plugin = "cursor"
default = true
command = "cursor"
timeout = 300000
 
[agents.options]
model = "claude-4.5-sonnet"
force = true
mode = "agent"

Options Reference

Option	Type	Default	Description
`model`	string	-	Model to use (e.g., `claude-4.5-sonnet`, `gpt-5.2`)
`force`	boolean	`true`	Auto-approve file modifications for autonomous operation
`mode`	string	`"agent"`	Execution mode: `agent`, `plan`, or `ask`
`timeout`	number	`0`	Execution timeout in ms (0 = no timeout)
`command`	string	`"cursor"`	Path to Cursor CLI executable

Execution Modes

Cursor supports three execution modes:

Mode	Description	Use Case
`agent`	Full agent mode with code execution	Normal development (default)
`plan`	Planning only, no execution	Review approach before running
`ask`	Question answering mode	Code exploration, learning

Configure in your config file:

TOML

[agentOptions]
mode = "agent"

Force Mode

When force is enabled (default), Cursor will auto-approve all file modifications without prompting. This is required for Ralph TUI's autonomous operation since it cannot relay interactive prompts.

TOML

[agentOptions]
force = true

INFO

With force enabled, Cursor will make changes without confirmation. Review your PRD carefully before running.

Subagent Tracing

Cursor emits structured JSONL via --output-format stream-json (always enabled). Ralph TUI parses this to display:

Tool invocations and their output
Duration and status of each operation

Enabling Tracing

TOML

subagentTracingDetail = "full"

Or toggle in TUI:

Press t to cycle through detail levels
Press T (Shift+T) to toggle the subagent tree panel

How It Works

When Ralph TUI executes a task with Cursor:

Build command: Constructs cursor [options]
Pass prompt via stdin: Avoids shell escaping issues with special characters
Stream output: Captures stdout/stderr in real-time
Parse JSONL: Extracts structured tool call data (always enabled)
Detect completion: Watches for completion token
Handle exit: Reports success, failure, or timeout

CLI Arguments

Ralph TUI builds these arguments:

Bash

cursor \
  --print \                        # Non-interactive output mode
  --force \                        # When force enabled (default)
  --output-format stream-json \    # Always used for structured output
  --model claude-4.5-sonnet \      # If model specified
  --mode plan \                    # If mode is not 'agent'
  < prompt.txt                     # Prompt via stdin

Troubleshooting

"Cursor CLI not found"

Ensure Cursor is installed and in your PATH:

Bash

which cursor
# Should output: /path/to/cursor
 
# If not found, install from:
# https://docs.cursor.com/cli

"Execution timeout"

Increase the timeout for complex tasks:

TOML

[[agents]]
name = "cursor"
plugin = "cursor"
timeout = 600000  # 10 minutes

"Permission denied"

Ensure force mode is enabled for autonomous operation:

TOML

[agentOptions]
force = true

Next Steps

Claude Agent - Anthropic's Claude Code
Codex Agent - OpenAI's Codex CLI
Gemini Agent - Google's Gemini CLI
Configuration - Full options reference