What problem does it solve? Delegating coding work to the Cursor CLI (cursor-agent) in headless mode requires knowing its exact flags, session model, and failure modes, which vary across versions and are easy to get wrong in automated pipelines. ## Core Features & Use Cases - Headless invocation: Run cursor-agent with -p --force for non-interactive execution, with --output-format json or stream-json for parseable results and completion detection. - Session and model management: Resume sessions by UUID, list available models, and pin explicit model IDs to avoid failures with default/auto on some plans. - Isolation and safety controls: Use timeouts, isolated git worktrees (-w/--worktree), and strict auth-abort rules when credentials errors appear. - Use Case: An orchestrator needs a bug fixed in src/login.ts without human interaction; it invokes cursor-agent in a dedicated worktree with a scoped prompt, a 900-second timeout, and JSON output to capture the modified files. ## Quick Start Ask the agent to run cursor-agent headlessly with a scoped prompt, a timeout, forced edit mode, and JSON output to implement a small coding change in a specific file.
