feat: add Cursor CLI (agent) support (#285)

covlllp · claude · njbrake · web-flow · commit 85e907558169 · 2026-02-24T15:51:37.000-05:00
* feat: add Cursor CLI (agent) support

Add Cursor as a supported agent using the new centralized registry.
Cursor CLI is built on Claude Code's codebase, so status detection
delegates to the existing Claude detector.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

* fix: address PR review feedback for Cursor CLI support

- Fix YOLO flag: --yolo -&gt; --force (per Cursor CLI docs)
- Add instruction_flag: --append-system-prompt (Claude Code compatible)
- Use RunWithArg detection: agent --version instead of which agent
- Add container_env: CURSOR_CONFIG_DIR for sandbox support
- Add AGENT_CONFIG_MOUNTS entry for ~/.cursor/ sandbox syncing
- Remove Cursor from sandbox image descriptions (Dockerfile not updated)

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

* add cursor cli

---------

Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
Co-authored-by: Nathan Brake &lt;33383515+njbrake@users.noreply.github.com&gt;
Co-authored-by: njbrake &lt;njbrake@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -22,7 +22,7 @@ Run multiple AI agents in parallel across different branches of your codebase, e
 
 ## Features
 
-- **Multi-agent support** -- Claude Code, OpenCode, Mistral Vibe, Codex CLI, and Gemini CLI
+- **Multi-agent support** -- Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, and Cursor CLI
 - **TUI dashboard** -- visual interface to create, monitor, and manage sessions
 - **Agent + terminal views** -- toggle between your AI agents and paired shell terminals with `t`
 - **Status detection** -- see which agents are running, waiting for input, or idle
@@ -96,7 +96,7 @@ Nothing. Sessions are tmux sessions running in the background. Open and close `a
 
 ### Which AI tools are supported?
 
-Claude Code, OpenCode, Mistral Vibe, Codex CLI, and Gemini CLI. AoE auto-detects which are installed on your system.
+Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, and Cursor CLI. AoE auto-detects which are installed on your system.
 
 ## Troubleshooting
 
diff --git a/docker/Dockerfile b/docker/Dockerfile
@@ -1,5 +1,5 @@
 # aoe-sandbox: Docker image for Agent of Empires sandbox sessions
-# This image provides Claude Code, OpenCode, Mistral Vibe, Codex CLI, and Gemini CLI in an isolated environment
+# This image provides Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, and Cursor CLI in an isolated environment
 
 FROM ubuntu:24.04
 
@@ -47,13 +47,17 @@ RUN npm install -g @google/gemini-cli
 RUN curl -LsSf https://mistral.ai/vibe/install.sh | bash
 ENV PATH="/root/.vibe/bin:${PATH}"
 
+# Install Cursor CLI
+RUN curl -fsSL https://cursor.com/install | bash
+
 # Create directories for credential mounts
 RUN mkdir -p /root/.claude \
     /root/.config/opencode \
     /root/.local/share/opencode \
     /root/.vibe \
     /root/.codex \
     /root/.gemini \
+    /root/.cursor \
     /root/.ssh
 
 # Allow Claude Code to use --dangerously-skip-permissions as root
diff --git a/docs/cli/reference.md b/docs/cli/reference.md
@@ -43,7 +43,7 @@ This document contains the help content for the `aoe` command-line program.
 
 ## `aoe`
 
-Agent of Empires (aoe) is a terminal session manager that uses tmux to help you manage and monitor AI coding agents like Claude Code and OpenCode.
+Agent of Empires (aoe) is a terminal session manager that uses tmux to help you manage and monitor AI coding agents like Claude Code, OpenCode, and Cursor CLI.
 
 Run without arguments to launch the TUI dashboard.
 
@@ -87,7 +87,7 @@ Add a new session
 
 * `-t`, `--title <TITLE>` — Session title (defaults to folder name)
 * `-g`, `--group <GROUP>` — Group path (defaults to parent folder)
-* `-c`, `--cmd <COMMAND>` — Command to run (e.g., 'claude', 'opencode', 'vibe', 'codex', 'gemini')
+* `-c`, `--cmd <COMMAND>` — Command to run (e.g., 'claude', 'opencode', 'vibe', 'codex', 'gemini', 'cursor')
 * `-P`, `--parent <PARENT>` — Parent session (creates sub-session, inherits group)
 * `-l`, `--launch` — Launch the session immediately after creating
 * `-w`, `--worktree <WORKTREE_BRANCH>` — Create session in a git worktree for the specified branch
diff --git a/docs/guides/configuration.md b/docs/guides/configuration.md
@@ -52,7 +52,7 @@ name = "phosphor"   # phosphor, tokyo-night-storm, catppuccin-latte
 
 ```toml
 [session]
-default_tool = "claude"   # claude, opencode, vibe, codex, gemini
+default_tool = "claude"   # claude, opencode, vibe, codex, gemini, cursor
 yolo_mode_default = false
 ```
 
diff --git a/docs/guides/repo-config.md b/docs/guides/repo-config.md
@@ -40,7 +40,7 @@ For sandboxed sessions, hooks run inside the Docker container.
 default_tool = "opencode"   # Override the default agent for this repo
 ```
 
-Available tools: `claude`, `opencode`, `vibe`, `codex`, `gemini`.
+Available tools: `claude`, `opencode`, `vibe`, `codex`, `gemini`, `cursor`.
 
 ### Sandbox
 
diff --git a/docs/guides/sandbox.md b/docs/guides/sandbox.md
@@ -2,7 +2,7 @@
 
 ## Overview
 
-Docker sandboxing runs your AI coding agents (Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI) inside isolated Docker containers while maintaining access to your project files and credentials.
+Docker sandboxing runs your AI coding agents (Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI) inside isolated Docker containers while maintaining access to your project files and credentials.
 
 **Key Features:**
 - One container per session
@@ -84,11 +84,11 @@ environment = ["ANTHROPIC_API_KEY"]
 
 ### Shared Agent Config Directories
 
-AOE shares your host agent credentials with sandboxed containers so agents can authenticate without re-login. This works for all supported agents: Claude Code, OpenCode, Codex, Gemini, and Vibe.
+AOE shares your host agent credentials with sandboxed containers so agents can authenticate without re-login. This works for all supported agents: Claude Code, OpenCode, Codex, Gemini, Vibe, and Cursor.
 
 Rather than bind-mounting your actual host config directories (which would let container writes modify your host files), AOE creates a **shared sandbox directory** per agent:
 
-1. For each agent whose host config directory exists (e.g. `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.local/share/opencode/`, `~/.vibe/`), AOE syncs credential files into a shared sandbox directory.
+1. For each agent whose host config directory exists (e.g. `~/.claude/`, `~/.codex/`, `~/.gemini/`, `~/.local/share/opencode/`, `~/.vibe/`, `~/.cursor/`), AOE syncs credential files into a shared sandbox directory.
 2. The sandbox directory is mounted read-write into **all** containers that use that agent.
 3. Containers can read credentials and write runtime state freely without affecting your host config.
 4. In-container changes (e.g. permission approvals, settings tweaks) persist across sessions since all containers share the same directory.
@@ -117,6 +117,7 @@ If an agent's config directory doesn't exist on the host (e.g. you haven't insta
 ~/.gemini/sandbox/                    # Gemini (shared by all containers)
 ~/.local/share/opencode/sandbox/      # OpenCode (shared by all containers)
 ~/.vibe/sandbox/                      # Vibe (shared by all containers)
+~/.cursor/sandbox/                    # Cursor (shared by all containers)
 ```
 
 Deleting an agent's config directory (e.g. `rm -rf ~/.codex/`) removes everything related to that agent, including the sandbox directory. To reset just the sandbox state for an agent, delete its `sandbox/` subdirectory (e.g. `rm -rf ~/.claude/sandbox/`) -- it will be re-created on the next session start.
@@ -137,7 +138,7 @@ Example: `aoe-sandbox-a1b2c3d4`
 
 1. **Session Creation:** When you add a sandboxed session, aoe records the sandbox configuration
 2. **Container Start:** When you start the session, aoe creates/starts the Docker container with appropriate volume mounts
-3. **tmux + docker exec:** Host tmux runs `docker exec -it <container> <tool>` (claude, opencode, vibe, codex, or gemini)
+3. **tmux + docker exec:** Host tmux runs `docker exec -it <container> <tool>` (claude, opencode, vibe, codex, gemini, or cursor)
 4. **Cleanup:** When you remove the session, the container is automatically deleted
 
 
@@ -187,7 +188,7 @@ AOE provides two official sandbox images:
 
 | Image | Description |
 |-------|-------------|
-| `ghcr.io/njbrake/aoe-sandbox:latest` | Base image with Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, git, ripgrep, fzf |
+| `ghcr.io/njbrake/aoe-sandbox:latest` | Base image with Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI, git, ripgrep, fzf |
 | `ghcr.io/njbrake/aoe-dev-sandbox:latest` | Extended image with additional dev tools |
 
 ### Dev Sandbox Tools
@@ -212,7 +213,7 @@ default_image = "ghcr.io/njbrake/aoe-dev-sandbox:latest"
 
 ## Custom Docker Images
 
-The default sandbox image includes Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, git, and basic development tools. For projects requiring additional dependencies beyond what the dev sandbox provides, you can extend either base image.
+The default sandbox image includes Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, Cursor CLI, git, and basic development tools. For projects requiring additional dependencies beyond what the dev sandbox provides, you can extend either base image.
 
 ### Step 1: Create a Dockerfile
 
diff --git a/docs/index.md b/docs/index.md
@@ -10,7 +10,7 @@ AoE lets you run multiple AI agents in parallel -- each in its own tmux session,
 
 ## Why AoE?
 
-**The problem:** You're working with AI coding agents (Claude Code, OpenCode, Codex, etc.) and want to run several in parallel across different tasks or branches. Managing multiple terminal windows, git branches, and container lifecycles by hand gets tedious fast.
+**The problem:** You're working with AI coding agents (Claude Code, OpenCode, Cursor, Codex, etc.) and want to run several in parallel across different tasks or branches. Managing multiple terminal windows, git branches, and container lifecycles by hand gets tedious fast.
 
 **AoE handles it for you:**
 
@@ -22,7 +22,7 @@ AoE lets you run multiple AI agents in parallel -- each in its own tmux session,
 
 ## Supported Agents
 
-Claude Code, OpenCode, Mistral Vibe, Codex CLI, and Gemini CLI. AoE auto-detects which are installed.
+Claude Code, OpenCode, Mistral Vibe, Codex CLI, Gemini CLI, and Cursor CLI. AoE auto-detects which are installed.
 
 <div class="cta-box">
 <p><strong>Ready to get started?</strong></p>
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -68,6 +68,7 @@ aoe add -c opencode .
 aoe add -c vibe .
 aoe add -c codex .
 aoe add -c gemini .
+aoe add -c cursor .
 ```
 
 In the TUI, select the tool from the dropdown in the new session dialog.
diff --git a/src/agents.rs b/src/agents.rs
@@ -110,6 +110,18 @@ pub const AGENTS: &[AgentDef] = &[
         detect_status: status_detection::detect_gemini_status,
         container_env: &[],
     },
+    AgentDef {
+        name: "cursor",
+        binary: "agent",
+        aliases: &["agent"],
+        detection: DetectionMethod::Which("agent"),
+        yolo: Some(YoloMode::CliFlag("--yolo")),
+        instruction_flag: None,
+        set_default_command: false,
+        supports_host_launch: true,
+        detect_status: status_detection::detect_cursor_status,
+        container_env: &[("CURSOR_CONFIG_DIR", "/root/.cursor")],
+    },
 ];
 
 /// Look up an agent by canonical name.
@@ -174,6 +186,7 @@ mod tests {
         assert_eq!(get_agent("vibe").unwrap().binary, "vibe");
         assert_eq!(get_agent("codex").unwrap().binary, "codex");
         assert_eq!(get_agent("gemini").unwrap().binary, "gemini");
+        assert_eq!(get_agent("cursor").unwrap().binary, "agent");
     }
 
     #[test]
@@ -184,7 +197,10 @@ mod tests {
     #[test]
     fn test_agent_names() {
         let names = agent_names();
-        assert_eq!(names, vec!["claude", "opencode", "vibe", "codex", "gemini"]);
+        assert_eq!(
+            names,
+            vec!["claude", "opencode", "vibe", "codex", "gemini", "cursor"]
+        );
     }
 
     #[test]
@@ -194,7 +210,9 @@ mod tests {
         assert_eq!(resolve_tool_name("mistral-vibe"), Some("vibe"));
         assert_eq!(resolve_tool_name("codex"), Some("codex"));
         assert_eq!(resolve_tool_name("gemini"), Some("gemini"));
+        assert_eq!(resolve_tool_name("cursor"), Some("cursor"));
         assert_eq!(resolve_tool_name(""), Some("claude"));
+        assert_eq!(resolve_tool_name("agent"), Some("cursor"));
         assert_eq!(resolve_tool_name("unknown-tool"), None);
     }
 
@@ -203,10 +221,12 @@ mod tests {
         assert_eq!(settings_index_from_name(None), 0);
         assert_eq!(settings_index_from_name(Some("claude")), 1);
         assert_eq!(settings_index_from_name(Some("gemini")), 5);
+        assert_eq!(settings_index_from_name(Some("cursor")), 6);
 
         assert_eq!(name_from_settings_index(0), None);
         assert_eq!(name_from_settings_index(1), Some("claude"));
         assert_eq!(name_from_settings_index(5), Some("gemini"));
+        assert_eq!(name_from_settings_index(6), Some("cursor"));
         assert_eq!(name_from_settings_index(99), None);
     }
 
diff --git a/src/cli/add.rs b/src/cli/add.rs
@@ -22,7 +22,7 @@ pub struct AddArgs {
     #[arg(short = 'g', long)]
     group: Option<String>,
 
-    /// Command to run (e.g., 'claude', 'opencode', 'vibe', 'codex', 'gemini')
+    /// Command to run (e.g., 'claude', 'opencode', 'vibe', 'codex', 'gemini', 'cursor')
     #[arg(short = 'c', long = "cmd")]
     command: Option<String>,
 
@@ -167,8 +167,14 @@ pub async fn run(profile: &str, args: AddArgs) -> Result<()> {
     }
 
     if let Some(cmd) = &args.command {
-        instance.command = cmd.clone();
-        instance.tool = detect_tool(cmd)?;
+        let tool_name = detect_tool(cmd)?;
+        instance.tool = tool_name;
+        // Only store a custom command when the user passed extra args
+        // (e.g. "claude --resume xyz"). A bare tool name/alias should resolve
+        // through the agent definition so the correct binary is used.
+        if cmd.trim().contains(' ') {
+            instance.command = cmd.clone();
+        }
     }
 
     if let Some(worktree_info) = worktree_info_opt {
diff --git a/src/session/container_config.rs b/src/session/container_config.rs
@@ -100,6 +100,16 @@ const AGENT_CONFIG_MOUNTS: &[AgentConfigMount] = &[
         home_seed_files: &[],
         preserve_files: &[],
     },
+    AgentConfigMount {
+        host_rel: ".cursor",
+        container_suffix: ".cursor",
+        skip_entries: &["sandbox"],
+        seed_files: &[],
+        copy_dirs: &[],
+        keychain_credential: None,
+        home_seed_files: &[],
+        preserve_files: &[],
+    },
 ];
 
 /// Sync host agent config into the shared sandbox directory. Copies top-level files
diff --git a/src/tmux/status_detection.rs b/src/tmux/status_detection.rs
@@ -403,6 +403,10 @@ pub fn detect_codex_status(raw_content: &str) -> Status {
     Status::Idle
 }
 
+pub fn detect_cursor_status(content: &str) -> Status {
+    detect_claude_status(content)
+}
+
 pub fn detect_gemini_status(raw_content: &str) -> Status {
     let content = raw_content.to_lowercase();
     let lines: Vec<&str> = content.lines().collect();
@@ -704,6 +708,44 @@ mod tests {
         assert_eq!(detect_codex_status("random output text"), Status::Idle);
     }
 
+    #[test]
+    fn test_detect_cursor_status_running() {
+        assert_eq!(
+            detect_cursor_status("Working on your request (esc to interrupt)"),
+            Status::Running
+        );
+        assert_eq!(detect_cursor_status("Processing ⠋"), Status::Running);
+    }
+
+    #[test]
+    fn test_detect_cursor_status_waiting() {
+        assert_eq!(detect_cursor_status("Yes, allow once"), Status::Waiting);
+        assert_eq!(detect_cursor_status("Task complete.\n>"), Status::Waiting);
+    }
+
+    #[test]
+    fn test_detect_cursor_status_idle() {
+        assert_eq!(detect_cursor_status("some random output"), Status::Idle);
+    }
+
+    #[test]
+    fn test_detect_cursor_status_delegates_to_claude() {
+        // Cursor CLI is built on Claude Code, so all Claude patterns should work
+        let test_cases = vec![
+            ("Thinking... · esc to interrupt", Status::Running),
+            ("Do you trust the files in this folder?", Status::Waiting),
+            ("completed the task", Status::Idle),
+        ];
+        for (content, expected) in test_cases {
+            assert_eq!(
+                detect_cursor_status(content),
+                expected,
+                "Failed for: {}",
+                content
+            );
+        }
+    }
+
     #[test]
     fn test_detect_gemini_status_running() {
         assert_eq!(
diff --git a/src/tui/mod.rs b/src/tui/mod.rs
@@ -70,6 +70,7 @@ pub async fn run(profile: &str) -> Result<()> {
         eprintln!("Agent of Empires requires at least one of:");
         eprintln!("  claude    - Anthropic's Claude CLI");
         eprintln!("  opencode  - OpenCode CLI");
+        eprintln!("  cursor    - Cursor's Agent CLI");
         eprintln!();
         eprintln!("Install one of these tools and ensure it's in your PATH.");
         std::process::exit(1);
diff --git a/website/src/pages/docs/cli/reference.md b/website/src/pages/docs/cli/reference.md
@@ -47,7 +47,7 @@ This document contains the help content for the `aoe` command-line program.
 
 ## `aoe`
 
-Agent of Empires (aoe) is a terminal session manager that uses tmux to help you manage and monitor AI coding agents like Claude Code and OpenCode.
+Agent of Empires (aoe) is a terminal session manager that uses tmux to help you manage and monitor AI coding agents like Claude Code, OpenCode, and Cursor CLI.
 
 Run without arguments to launch the TUI dashboard.
 
@@ -91,7 +91,7 @@ Add a new session
 
 * `-t`, `--title <TITLE>` -- Session title (defaults to folder name)
 * `-g`, `--group <GROUP>` -- Group path (defaults to parent folder)
-* `-c`, `--cmd <COMMAND>` -- Command to run (e.g., 'claude', 'opencode', 'vibe', 'codex', 'gemini')
+* `-c`, `--cmd <COMMAND>` -- Command to run (e.g., 'claude', 'opencode', 'vibe', 'codex', 'gemini', 'cursor')
 * `-P`, `--parent <PARENT>` -- Parent session (creates sub-session, inherits group)
 * `-l`, `--launch` -- Launch the session immediately after creating
 * `-w`, `--worktree <WORKTREE_BRANCH>` -- Create session in a git worktree for the specified branch
diff --git a/website/src/pages/docs/guides/configuration.md b/website/src/pages/docs/guides/configuration.md
@@ -45,7 +45,7 @@ All settings below can also be edited from the TUI settings screen (press `s` or
 
 ```toml
 [session]
-default_tool = "claude"   # claude, opencode, vibe, codex, gemini
+default_tool = "claude"   # claude, opencode, vibe, codex, gemini, cursor
 yolo_mode_default = false
 ```
 
diff --git a/website/src/pages/docs/guides/repo-config.md b/website/src/pages/docs/guides/repo-config.md
@@ -44,7 +44,7 @@ For sandboxed sessions, hooks run inside the Docker container.
 default_tool = "opencode"   # Override the default agent for this repo
 ```
 
-Available tools: `claude`, `opencode`, `vibe`, `codex`, `gemini`.
+Available tools: `claude`, `opencode`, `vibe`, `codex`, `gemini`, `cursor`.
 
 ### Sandbox
 
diff --git a/website/src/pages/docs/guides/sandbox.md b/website/src/pages/docs/guides/sandbox.md
diff --git a/website/src/pages/docs/index.md b/website/src/pages/docs/index.md
diff --git a/website/src/pages/docs/quick-start.md b/website/src/pages/docs/quick-start.md
