feat: add Cursor CLI (agent) support

[covlllp]

Description

Adds Cursor CLI as a supported agent using the new centralized AgentDef registry pattern from #282.

Cursor CLI is built on Claude Code's codebase, so status detection delegates to the existing Claude detector. The binary name is agent, but it's intentionally NOT added as an alias in resolve_tool_name since it's too generic -- users should use -c cursor.

One AgentDef entry, one status detection function, documentation updates across 6 docs files.

PR Type

• New Feature
• Bug Fix
• Refactor
• Documentation
• Infrastructure / CI

Checklist

• I understand the code I am submitting
• New and existing tests pass
• Documentation was updated where necessary
• For UI changes: included screenshot or recording

AI Usage

• No AI was used
• AI was used for drafting/refactoring
• This is fully AI-generated

AI Model/Tool used: Claude Code (Claude Opus 4.6)

Any Additional AI Details you'd like to share: Implementation planned and executed via Claude Code CLI.

• I am an AI Agent filling out this form (check box if true)

[github-actions]

⚠️ PR Template Missing

This PR appears to be missing the required checklist from the PR template.

Please edit your PR description to include the checklist section. The checklist helps maintainers review your contribution.

This PR will be automatically closed in 24 hours if the template is not restored.

If you're using an AI coding tool, please ensure it preserves the PR template.

[covlllp]

@njbrake rebased and reimplemented based on the new refactor!

paper trail, initial attempt was #280

[njbrake]

Hi @covlllp ! I had my agent review, I think there are a few things that need to be addressed:

  ---
  PR #285 Review: feat: add Cursor CLI (agent) support

  Summary

  This PR adds Cursor CLI as a new supported agent in the Agent of Empires registry. It follows the AgentDef pattern established in #282. The binary name is agent, aliases are intentionally left empty (since agent
   is too generic), and status detection delegates to the existing Claude detector. Changes span 1 new registry entry, 1 status detection function, updated tests, and documentation updates across 6 docs files.

  Code Review

  ┌──────────────────────────────┬──────────────┬──────────────────────────────────────────────────────┐
  │             File             │  Assessment  │                        Notes                         │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ src/agents.rs                │ Issues found │ New AgentDef entry + test updates (see issues below) │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ src/tmux/status_detection.rs │ OK           │ Thin delegation wrapper + good tests                 │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ src/tui/mod.rs               │ OK           │ Adds Cursor to startup help message                  │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ src/cli/add.rs               │ OK           │ Help text update                                     │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ README.md                    │ OK           │ Listing update                                       │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ docs/cli/reference.md        │ OK           │ CLI reference update                                 │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ docs/guides/configuration.md │ OK           │ Config docs update                                   │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ docs/guides/repo-config.md   │ OK           │ Repo config docs update                              │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ docs/guides/sandbox.md       │ Has issues   │ Claims Cursor is in the sandbox image (see below)    │
  ├──────────────────────────────┼──────────────┼──────────────────────────────────────────────────────┤
  │ docs/quick-start.md          │ OK           │ Quick start example added                            │
  └──────────────────────────────┴──────────────┴──────────────────────────────────────────────────────┘

  Issues Found

  1. Wrong YOLO flag (Bug)

  yolo: Some(YoloMode::CliFlag("--yolo")),

  Cursor CLI does not have a --yolo flag. The correct flag for auto-approving commands is --force (or -f). From the https://cursor.com/docs/cli/reference/parameters:

  -f, --force -- Force allow commands unless explicitly denied

  This should be:
  yolo: Some(YoloMode::CliFlag("--force")),

  2. Missing container_env (Bug -- sandbox broken)

  The PR sets container_env: &[], but Cursor CLI uses a config directory at ~/.cursor/ and supports the CURSOR_CONFIG_DIR environment variable. Compare with Claude's entry which sets ("CLAUDE_CONFIG_DIR",
  "/root/.claude").

  3. Missing AGENT_CONFIG_MOUNTS entry (Bug -- sandbox broken)

  src/session/container_config.rs has a AGENT_CONFIG_MOUNTS array that defines config directory syncing for Docker sandboxing. Every other agent has an entry here. Cursor CLI needs one too (mounting ~/.cursor/
  into the container), otherwise sandboxed Cursor sessions won't have access to credentials or configuration. Should look something like:

  AgentConfigMount {
      host_rel: ".cursor",
      container_suffix: ".cursor",
      skip_entries: &["sandbox"],
      seed_files: &[],
      copy_dirs: &[],
      keychain_credential: None,
      home_seed_files: &[],
      preserve_files: &[],
  },

  4. instruction_flag: None -- worth verifying

  Other Claude-compatible agents have instruction injection flags. If Cursor CLI supports --append-system-prompt or similar, this should be set. If not, None is fine, but it should be a deliberate choice.

  5. docs/guides/sandbox.md claims Cursor is in the sandbox image (Inaccuracy)

  The diff updates the sandbox image description table to include "Cursor CLI" in the ghcr.io/njbrake/aoe-sandbox:latest image contents. But this PR doesn't modify the Dockerfile, so the image almost certainly
  doesn't actually include Cursor CLI. This documentation claim is incorrect unless a separate image rebuild is planned.

  6. Detection method reliability concern (Minor)

  detection: DetectionMethod::Which("agent"),

  agent is an extremely generic binary name. which agent could match unrelated binaries on some systems. Consider using DetectionMethod::RunWithArg("agent", "--version") and validating the output contains "cursor"
   or a known version string -- similar to how Vibe uses RunWithArg. The PR description acknowledges this ("it's intentionally NOT added as an alias in resolve_tool_name since it's too generic"), but the detection
   method has the same problem.

  Compliance with Project Guidelines

  - Registry pattern: Correctly follows the AgentDef registry pattern.
  - Tests: Good test coverage added for status detection and registry lookups.
  - Commit format: Conventional commit (feat:), single clean commit.
  - Documentation: Updated across all relevant docs files.
  - Settings TUI: No new config fields were added, so no FieldKey/SettingField wiring needed. OK.
  - Emdashes: Docs use double dashes (--), not emdashes. Compliant.

  Suggestions (Non-blocking)

  1. The detect_cursor_status function is a pure delegation to detect_claude_status. This is fine as a starting point, but consider adding a comment in the function body explaining why (Cursor CLI produces
  Claude-like terminal output). If Cursor CLI diverges in the future, this makes it clear the delegation was intentional.
  2. The test test_detect_cursor_status_delegates_to_claude is good -- it documents the assumption that Claude patterns work for Cursor.

  How to Review and Test

  Code review checklist:
  1. Verify the YOLO flag is correct (--force not --yolo) -- check cursor agent --help or the https://cursor.com/docs/cli/reference/parameters
  2. Confirm whether instruction_flag should be None or if Cursor supports something like --append-system-prompt
  3. Decide if the agent binary detection is reliable enough or needs RunWithArg validation

  Manual testing (requires Cursor CLI installed):
  # 1. Build and run tests
  cargo test

  # 2. Verify agent detection
  which agent           # Should find cursor's binary
  agent --version       # Should show Cursor CLI version

  # 3. Test session creation
  cargo run -- add -c cursor /path/to/project
  cargo run              # Launch TUI, verify cursor session appears

  # 4. Test status detection (if you can launch a cursor session)
  # - Launch a cursor session via AoE
  # - Verify status transitions: Idle -> Running -> Waiting -> Idle

  # 5. Test YOLO mode (after fixing the flag)
  cargo run -- add -c cursor --yolo /path/to/project
  # Verify the command launched includes --force

  # 6. Docker sandbox testing
  # - Enable sandbox mode in settings
  # - Create a cursor session
  # - Verify ~/.cursor/ config is mounted into the container
  # - Verify cursor can authenticate inside the container

  Things you can't easily test without the sandbox image rebuild:
  - The docs claim Cursor CLI is in the sandbox image, but the Dockerfile wasn't updated. You'd need to build a new image with Cursor CLI installed to validate sandboxed sessions.

  Verdict

  Request Changes

  The PR is well-structured and follows the registry pattern correctly, but has three issues that need fixing before merge:

  1. Wrong YOLO flag (--yolo should be --force) -- this will cause runtime failures when users enable YOLO mode for Cursor
  2. Missing AGENT_CONFIG_MOUNTS entry -- Docker sandbox sessions for Cursor won't have credentials/config
  3. Inaccurate sandbox image docs -- claims Cursor is in the image without updating the Dockerfile

  Issues 1 and 2 are functional bugs. Issue 3 is a documentation inaccuracy that will confuse users trying to use Cursor in sandboxed mode.

Let me know if you have any questions, thanks!

[covlllp]

Thanks for the thorough review @njbrake! All issues addressed in the latest push:

Bugs fixed:

1. YOLO flag -- Changed --yolo to --force per the Cursor CLI docs
2. Missing AGENT_CONFIG_MOUNTS -- Added .cursor entry to src/session/container_config.rs so sandboxed sessions sync ~/.cursor/ credentials
3. Sandbox image docs -- Removed Cursor CLI from the image description tables (Dockerfile wasn't updated, so those claims were inaccurate)

Additional improvements based on review suggestions:

4. container_env -- Added ("CURSOR_CONFIG_DIR", "/root/.cursor") (matching Claude's pattern with CLAUDE_CONFIG_DIR)
5. instruction_flag -- Set to --append-system-prompt {} since Cursor CLI is built on Claude Code and supports the same flag
6. Detection method -- Changed from Which("agent") to RunWithArg("agent", "--version") to avoid false positives from unrelated agent binaries

All tests pass (643/643, the one test_deletion_poller_channel_communication failure is a pre-existing flaky timing test that passes on re-run).

[njbrake]

Hi @covlllp next review from Claude :)

  1. --append-system-prompt may not exist in Cursor CLI (Potential Bug)

  The instruction_flag is set to Some("--append-system-prompt {}"), matching Claude Code's flag. However, the https://cursor.com/docs/cli/reference/parameters does not document this flag. If Cursor CLI doesn't
  support it, instruction injection will fail silently or error when AoE tries to pass custom instructions. This should be verified -- if the flag doesn't exist, set to None.

  2. Minimal AgentConfigMount compared to Claude's (Sandbox Gaps)

  The .cursor config mount at src/session/container_config.rs:103-112 has all optional fields empty:

  AgentConfigMount {
      host_rel: ".cursor",
      container_suffix: ".cursor",
      skip_entries: &["sandbox"],
      seed_files: &[],          // Claude has onboarding seed
      copy_dirs: &[],           // Claude copies plugins/ and skills/
      keychain_credential: None, // Claude extracts OAuth from Keychain
      home_seed_files: &[],     // Claude seeds .claude.json
      preserve_files: &[],      // Claude preserves .credentials.json, history.jsonl
  }

  This means:
  - macOS: Keychain-stored OAuth tokens won't be extracted into the sandbox, so users will need to re-authenticate inside each container (or use API keys via environment variables).
  - First-run wizard: If Cursor has an onboarding flow, it will appear in every new sandbox since there's no seed file to skip it.
  - Credential overwrite: If Cursor stores credentials at predictable paths, they could be overwritten on sandbox resync since preserve_files is empty.

  This is acceptable as an initial implementation if these details aren't yet known for Cursor CLI, but should be documented or tracked as a follow-up.

  Suggestions (Non-blocking)

  1. Comment on detection reliability: The RunWithArg("agent", "--version") check is better than Which, but agent is still a very generic binary name. A comment noting that this could match unrelated binaries and
  that users should use -c cursor explicitly would be helpful.
  2. Comment on delegation rationale: detect_cursor_status is a one-liner delegating to detect_claude_status. A brief doc comment explaining why (Cursor CLI produces Claude-like terminal output) would help future
  maintainers understand whether this is a temporary shortcut or an intentional design choice.
  3. TUI error message: The startup error lists only claude, opencode, and cursor as required tools. The other agents (vibe, codex, gemini) are also omitted. This is pre-existing but worth noting for consistency.

  Verdict

  Needs Discussion

  The PR is well-structured, follows conventions correctly, and all previous review feedback has been addressed. The two remaining concerns are:

  1. instruction_flag: If --append-system-prompt doesn't exist in Cursor CLI, this should be None to avoid runtime errors. This needs verification against the actual binary.
  2. Sandbox config completeness: The empty keychain_credential/preserve_files/seed_files means sandbox support on macOS may require manual re-auth. This is fine if intentional and documented, but should be a
  conscious decision.

  Neither issue blocks the core functionality of adding Cursor as a supported agent for non-sandboxed use. If sandbox support is intended to be fully functional at launch, issue #2 should be addressed. If this is
  a "best-effort first pass" with sandbox refinements to follow, the PR is close to ready -- just needs the instruction_flag verified.

Have you personally run this with the cursor CLI and verified that it works ok?

[covlllp]

closing given the latest commit

[njbrake]

closing given the latest commit

I pushed to your branch because I'm doing a last cleanup before merging your branch into main :) I ran it and it's working for me 🚀

[covlllp]

ah my bad 😆 TY!