--- name: cursor-dispatch description: "Orchestrate Cursor Agent CLI for coding tasks with concurrency control, timeout recovery, and multi-task coordination. Use when: (1) dispatching coding tasks to cursor agent via CLI, (2) analyzing code before modifying (plan mode), (3) running parallel batch coding tasks with concurrency limits, (4) coordinating multi-step code changes with review gates, (5) recovering from stuck/timeout cursor processes. Triggers: cursor dispatch, plan then execute, code analysis pipeline, batch coding tasks, cursor agent orchestration, parallel coding, concurrent tasks." --- # Cursor Agent CLI Dispatch Orchestrate `cursor agent` CLI with concurrency control, timeout recovery, and retry. ## Hard Constraints (from testing) | Constraint | Value | Source | |-----------|-------|--------| | PTY required | `pty: true` mandatory | No output without PTY | | Max safe concurrency | 6 parallel tasks | Tested 8 OK, 6 is safe margin | | Plan timeout (single file) | 60-120s | Tested on .gd files | | Plan timeout (multi-file) | >180s, WILL timeout | Don't attempt | | Execute timeout | 60-90s typical | Up to 180s for complex | | `--output-format json` | BROKEN in PTY | Use text format only | | Empty output = failure | Check output size > 20 bytes | Retry if empty | ## Command Template ``` exec( command: "cd && cursor agent -p --trust [FLAGS] --model auto --workspace . ''", pty: true, timeout: ) ``` | Mode | Flags | Timeout | Use | |------|-------|---------|-----| | Plan | `--plan` | 180s | Read-only analysis | | Execute | `--yolo` | 180s | Auto-approve changes | | Ask | `--mode ask` | 120s | Q&A, no changes | ## Concurrency Control Protocol ### State Tracking Before launching cursor tasks, track them via `process(action=list)`. Each running exec session with cursor agent counts toward the limit. ### Launch Rules ``` 1. Check: process(action=list) → count sessions with "cursor agent" in command 2. If count >= MAX_CONCURRENT (default 4, max 6): WAIT or QUEUE 3. Launch: exec(command=..., pty=true, timeout=T, background=true) 4. Record: sessionId + taskId + startTime 5. Poll: process(action=poll, sessionId=X, timeout=T*1000) ``` ### Concurrency Limits by Task Type | Scenario | Max Concurrent | Why | |----------|---------------|-----| | Plan-only (read) | 6 | No file conflicts | | Execute (write) | 3 | Avoid git/file conflicts | | Mixed plan+execute | 4 | Balance safety and speed | | Same-file tasks | 1 (serial only) | NEVER parallel on same file | ## Timeout & Recovery Protocol ### Detection A task is stuck when: - `process(action=poll, timeout=T)` returns with process still running after timeout - Exit code 143 (SIGTERM) or 137 (SIGKILL) = was killed by timeout - Output is empty (< 20 bytes) after completion = silent failure ### Recovery Steps ``` 1. DETECT: poll returns "still running" or exit 143/137 or empty output 2. KILL: process(action=kill, sessionId=X) 3. WAIT: 3 seconds cooldown (avoid API rate limits) 4. SIMPLIFY: reduce prompt scope (fewer files, simpler question) 5. RETRY: relaunch with simplified prompt, same or higher timeout 6. MAX RETRIES: 2 attempts total. After 2 failures → report to user ``` ### Simplification Strategy When a task times out, simplify before retrying: | Original | Simplified | |----------|-----------| | "Scan all dungeon scripts for bugs" | "Scan dungeon_manager.gd for null refs" | | "Fix 5 issues in this file" | "Fix issue #1 and #2 only" | | "Analyze architecture of combat system" | "List all functions in arpg_monster.gd" | ## Cleanup Protocol ### When to Clean Up - Before starting a new batch of tasks - After any task failure - On session start (check for orphans) ### How to Clean Up ``` 1. process(action=list) → find all cursor-related sessions 2. For each: check if still running 3. If running > 10 minutes: process(action=kill, sessionId=X) 4. Verify: ps aux | grep "cursor agent -p" | grep -v grep 5. Nuclear option: pkill -f "cursor agent -p" (kills ALL cursor CLI agents) ``` ### Orphan Detection Cursor agent processes that outlive their exec session become orphans: ```bash # Find orphan cursor agent processes ps aux | grep "cursor agent -p" | grep -v grep # Kill specific orphan kill ``` ## Four Dispatch Chains ### Chain A: Direct Execute For simple tasks (1-3 files, clear logic). Single exec call. ``` exec( command: "cd && cursor agent -p --trust --yolo --model auto --workspace . ''", pty: true, timeout: 180 ) → poll → verify output not empty → done ``` ### Chain B: Plan → Review → Execute ⭐ For complex tasks. Most reliable chain. ``` Step 1 — PLAN (pty:true, timeout:180): "检查中会导致运行时崩溃的问题。重点：。只列会崩溃的。" Step 2 — REVIEW (agent decides): Parse output → grade 🔴🟠🟡🟢 → select fixes for this round Step 3 — EXECUTE (pty:true, timeout:180): "修复中 N 个问题：[paste selected items with line numbers and fix code]。修复后运行：。确认无错误后 git commit。" Step 4 — VERIFY: Run headless build/test to confirm ``` ### Chain C: Parallel Batch For independent tasks across different files. Use background exec. ``` # Launch (respect concurrency limit) exec(cmd="cursor agent ... task1", pty:true, background:true) → session1 exec(cmd="cursor agent ... task2", pty:true, background:true) → session2 exec(cmd="cursor agent ... task3", pty:true, background:true) → session3 # Monitor process(action=poll, sessionId=session1, timeout=180000) process(action=poll, sessionId=session2, timeout=180000) process(action=poll, sessionId=session3, timeout=180000) # Verify all Run headless build/test ``` Rules: - Max 4 parallel execute tasks (6 for plan-only) - NEVER parallel on same file - Check for git conflicts after all complete - If any fails: kill remaining → fix conflict → retry failed ones ### Chain D: Plan Global → Serial Execute For large refactors with dependencies. ``` 1. Plan pass on each file (can parallel, up to 6) 2. Collect all findings → sort by dependency 3. Execute in dependency order (serial) 4. Verify after each execute before next 5. If verify fails: stop, fix, re-plan remaining ``` ## Prompt Engineering for Cursor Agent ### Plan Prompts (what works) Good: "检查 scripts/dungeon/dungeon_manager.gd 中所有可能返回 null 的函数调用，以及调用方是否有 null 检查" Good: "列出中所有 func 的名字" Bad: "扫描所有文件找出所有问题" (too broad, will timeout) ### Execute Prompts (what works) Good: Include exact line numbers + expected code change + verify command + git commit Bad: Vague "fix the bugs" without specifics ### Template ``` Plan: "检查中。只列会崩溃/卡死的问题，给出行号和修复方案。" Execute: "修复中 N 个问题： 1. 第 X 行： → 2. 第 Y 行： → 修复后运行：确认无错误后 git commit -m ''。" ``` ## Model Selection | Task | Model | Timeout | |------|-------|---------| | Default | `auto` | — | | Simple edits | `auto` | 120s | | Complex analysis | `auto` + `--plan` | 180s | | Code review | `auto` + `--mode ask` | 120s | `auto` routes to best available model (typically opus-4.6-thinking). Don't override unless needed. ## Session Resume ```bash cursor agent ls # List past sessions cursor agent -p --trust --continue "..." # Continue last cursor agent -p --trust --resume "..." # Resume specific ``` ## Timing Benchmarks ### v2.6.12 (tested 2026-03-06 evening, cursor 2.6.12) | Task Type | Time | Concurrency Tested | |-----------|------|--------------------| | List functions (small file <50 lines) | 8-14s | 6/6 parallel ✅ | | List functions (medium file ~600 lines) | 17s | single ✅ | | List functions (large file ~1000 lines) | 40s | single ✅ | | Simple execute (add comment, 1 file) | 16-19s | 3/3 parallel ✅ | | Ask mode (simple Q&A) | 8s | single ✅ | | Complex analysis (null-check scan, 660 lines) | 84s | single ✅ | | Long complex prompt (3+ concerns, multi-file ref) | >180s | TIMEOUT ⚠️ | | Execute with broad prompt (3 bugs, multi-concern) | >180s | TIMEOUT ⚠️ | ### Key Findings (v2.6.12) - **Simple tasks (list/comment/ask) are MUCH faster** than v2026.02.27 (8-40s vs 55-120s) - **Complex analysis still takes 60-120s** — similar to old version - **Broad prompts (3+ separate concerns) STILL timeout** — must split into 1-concern-per-task - **Silent failures (empty output) reduced** but still occur on timeout - **6 parallel plan = all pass** in ~53s wall clock (individual 8-14s each) - **3 parallel execute = all pass** in ~25s wall clock (individual 16-19s each) ### Failure Mode: Prompt Complexity (NOT concurrency) Timeouts correlate with **prompt complexity**, not concurrency: - 6 simple tasks parallel → all pass in <20s each - 1 complex task with 3+ concerns → timeout at 180s - **Solution**: ALWAYS split multi-concern prompts. One concern per cursor task. ### Previous version (v2026.02.27, tested 2026-03-06 morning) | Task Type | Time | Concurrency Tested | |-----------|------|--------------------| | List functions (1 file) | 15s | 8/8 passed | | Null-check scan (1 file) | 80-120s | 4/4 parallel ✅ | | Execute fix (1 file, 1-4 issues) | 55-90s | 3/3 parallel ✅ | | Multi-file analysis | >180s | TIMEOUT | ## Validated Workflows ### Workflow 1: Parallel Plan → Review → Parallel Execute (2026-03-06) ``` Round 1 (Chain B serial): 3 files × plan→execute = 9 fixes, 3 commits Round 2 (Chain C parallel): 4 files × plan (parallel) → review → 3 files × execute (parallel) = 3 fixes, 3 commits Total: 12 runtime crash risks fixed, 6 commits, Godot headless zero errors ``` ### Workflow 2: Skip Plan, Direct Execute (2026-03-06 evening) When you already know exactly what to change, skip Plan and go straight to Execute: ``` 3 parallel Execute (different files) = all pass, 16-19s each Pre-requisite: dispatcher already analyzed the code and wrote precise prompts ``` Key insight: Plan can always be parallelized (read-only). Execute can be parallelized only when tasks touch different files. Review is always serial (agent decides). **Critical**: Keep prompts focused — 1 file, 1 concern, specific line numbers. For model list and CLI parameters, see [references/models-and-params.md](references/models-and-params.md).

Cursor Dispatch

Description

Latest Changes

Install Cursor Dispatch with One Click