Investigate underlying CLI swap (Claude Code → Codex / OpenCode / Cursor)

[dgershman]

Question

How challenging is it to swap out the underlying CLI driving Crow sessions (i.e. instead of Claude Code, use Codex, OpenCode, or Cursor)? Are the commands an interface somewhere that is hot-swappable, or are they baked in across the codebase?

What to investigate

1. Inventory CLI coupling points. Find every place Crow assumes the CLI is claude:

   • Terminal launch commands (crow new-terminal --command "claude ...")
   • The send command's input format (e.g., trailing newline semantics, slash-command syntax like /crow-workspace, /crow-create-ticket)
   • Skill resolution paths (.claude/skills/..., .claude/CLAUDE.md, .claude/config.json)
   • Permission/sandbox model assumptions (e.g., dangerouslyDisableSandbox)
   • Hook integration points
   • Attribution trailers / footers

2. Identify the interface boundary (if any). Is there a single "CLI adapter" type/protocol, or is claude-specific logic scattered across:

   • The Swift app (terminal spawning, env, args)
   • The setup.sh / preflight scripts
   • The slash-command skill files (which only make sense in Claude Code)
   • The auto-pickup queue / job runner

3. Compare CLI capabilities. For each candidate (Codex CLI, OpenCode, Cursor CLI/agent), map the equivalent of:

   • Non-interactive prompt invocation
   • Skill/slash-command equivalents (custom commands, agent modes)
   • Hook/automation surface
   • Sandbox/permission model
   • Memory / persistent context
   • Tool-call output format Crow can scrape

4. Define a swap strategy. Output one of:

   • Plug-in: small adapter behind a CLIBackend protocol; skills/commands become per-backend.
   • Fork: Crow becomes CLI-specific; another backend means a parallel app.
   • Hybrid: core orchestration stays, but Crow's skill library is owned by the user per-backend.

5. Effort estimate. Rough T-shirt sizing (S/M/L/XL) per candidate CLI, and which one is the realistic next backend if we pursue this.

Deliverable

A written analysis (issue comment or short doc under docs/) covering items 1–5 above. No implementation — the goal is to know whether a swap is a weekend hack, a quarter-long project, or architecturally infeasible without a rewrite.

🐦‍⬛ Created with Crow via Claude Code

[dgershman]

TL;DR — verdict

Swappable, but not free. Crow's CLI control plane (Unix-socket RPC, tmux backend, worktree management, GitHub/GitLab integration) is already CLI-agnostic. The Claude Code coupling is concentrated in five thin layers: binary discovery, launch-arg construction, the hook event schema, the .claude/ directory conventions, and the --continue resume semantics. After verifying each candidate's actual surface area:

Candidate	Realistic effort	Recommendation
Codex CLI	S–M (~1–3 weeks for parity)	Realistic next backend
OpenCode	M–L (~4–6 weeks)	Possible second
Cursor (agent)	L (~6–10 weeks for parity; M for a degraded "good enough" mode)	Useful but capability gaps

None are weekend hacks, none are full rewrites. The right strategy is a Hybrid adapter behind a Swift CLIBackend protocol, with per-backend skill libraries (skills don't port symmetrically).

1. Coupling-point inventory

Hard lock-in:

• Binary discovery & launch args — Sources/Crow/App/SessionService.swift:1639-1654 hardcodes ~/.local/bin/claude, /usr/local/bin/claude, /opt/homebrew/bin/claude. Fallback to string "claude" at lines 413, 463, 593. Launch string at line 463: "\(envPrefix)\(claudePath)\(rcArgs) \"$(cat \(promptPath))\"\n" (or ... --continue\n).
• Launch flags — Packages/CrowCore/Sources/CrowCore/ClaudeLaunchArgs.swift:7-43 is the single helper that emits --rc, --name, --permission-mode auto. --continue is composed at SessionService.swift:463. Centralized — good seam.
• Hook schema — Sources/Crow/App/HookConfigGenerator.swift:7-13 enumerates 17 event names (SessionStart, Stop, PreToolUse, PostToolUse, PermissionRequest, PermissionDenied, UserPromptSubmit, TaskCreated, SubagentStart, TaskCompleted, PreCompact, PostCompact, …) and writes .claude/settings.local.json with Claude Code's hook schema (lines 28-90).
• Scaffolding — Sources/Crow/App/Scaffolder.swift:20-32, 65-88 bundles .claude/CLAUDE.md and four .claude/skills/{crow-workspace, crow-review-pr, crow-batch-workspace, crow-create-ticket}/{SKILL.md, setup.sh}. AllowListService.swift:22-42 reads ~/.claude/settings.json and per-worktree .claude/settings.local.json.
• Slash-command dispatch — AppDelegate.swift:513, 525 sends /crow-workspace <url>\n and /crow-batch-workspace <urls>\n into the terminal, relying on Claude Code interpreting /foo as a skill trigger.
• setup.sh launch line — skills/crow-workspace/setup.sh:589: cd $WORKTREE_PATH && $claude_bin --permission-mode plan$rc_args "$(cat $prompt_path)"\n. Hardcoded Claude flags.
• Attribution trailer — setup.sh:356-397 writes attribution.commit override to inject Crow-Session: <uuid> alongside Co-Authored-By: Claude.
• OTEL env var name — SessionService.swift:430-437 exports CLAUDE_CODE_ENABLE_TELEMETRY=1 (Claude-Code-specific).
• Terminal detection heuristic — AppDelegate.swift:84-98 uses contains("claude") string matching.

Already generic:

• IPC (Packages/CrowIPC, ADR 0002) — Unix-socket RPC is CLI-neutral.
• tmux backend (ADR 0001) — TmuxBackend.sendText is raw bytes + Enter; no Claude semantics.
• Worktree creation, gh/glab integration, job scheduler loop, OAuth flow — all CLI-neutral.

2. Interface boundary today

There is no CLIBackend adapter. Claude-specific logic is spread across the four files above (SessionService, ClaudeLaunchArgs, HookConfigGenerator, Scaffolder) plus setup.sh. The IPC layer and tmux are clean of it, which is the saving grace — those don't need touching.

3. Candidate CLI comparison (verified against current docs)

Capability	Claude Code (today)	Codex CLI	OpenCode	Cursor (agent)
Non-interactive prompt	claude "<prompt>"	codex exec "<prompt>", codex exec - (stdin)	TUI-first; opencode run not surfaced on docs (verify --help)	agent -p "<prompt>" --model …
Resume / continue	--continue	codex exec resume --last, resume <SESSION_ID>	session IDs surfaced in TUI; CLI flag undocumented in public docs	agent --continue, agent --resume="<chat-id>", agent ls
Skill / command extension	.claude/skills/<n>/SKILL.md (markdown + frontmatter; /<name> slash trigger)	.agents/skills/<n>/SKILL.md (open agentskills.io standard; markdown + frontmatter; /skills or $skill trigger). Near-identical layout.	Agents at .opencode/agents/<n>.md (markdown + frontmatter); custom commands at .opencode/commands/<n>.md → /<n> slash trigger; supports $ARGUMENTS, ! shell injection, @file refs	.cursor/rules/*.mdc (rules, not commands); built-in slashes (/plan, /ask, /sandbox, /max-mode); no custom slash commands documented
Hooks	17 events in .claude/settings.local.json, type: command	Same event names (SessionStart, PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, Stop, Sub­agent­Start/Stop, PreCompact, PostCompact); .codex/hooks.json or [hooks] in config.toml; payload includes session_id/hook_event_name/tool_name/tool_input — drop-in compatible with Crow's crow hook-event --session … --event … handler	JS/TS plugin runtime at .opencode/plugins/ exposing tool.execute.before, tool.execute.after, session.created, session.idle, permission.asked, file.edited, etc. No shell-command hooks; events fire inside an in-process JS plugin.	Not documented in published CLI/agent docs
Sandbox / permission	dangerouslyDisableSandbox, --permission-mode auto|plan	--sandbox read-only|workspace-write|danger-full-access, --ask-for-approval untrusted|on-request|never	Per-agent permission: { edit, bash, … } → allow|ask|deny	--sandbox enabled|disabled, runtime /sandbox
Memory file	CLAUDE.md	AGENTS.md + .codex/	AGENTS.md (created by /init) + .opencode/	AGENTS.md (project root + nested) + .cursor/rules/*.mdc
Scrape-able output	tmux capture + hook events	codex exec --json (JSONL stream of thread.*, turn.*, item.* events) + --output-schema for structured JSON	session events via in-process plugin; no documented JSON stream flag	--output-format text; no JSONL documented

Per-CLI adapter shape:

• Codex — the surface map is uncannily close. Hook event names, the SKILL.md open standard, sandbox concepts, and even the payload field names overlap. HookConfigGenerator can write a Codex .codex/hooks.json with a different filename and ~3 renamed fields; the crow hook-event callback works as-is. --continue maps to codex exec resume --last. --json gives Crow a structured event stream as a bonus.
• OpenCode — capable, but its hook surface is a JS/TS plugin runtime, not shell commands. Crow would need to ship a bundled @crow/opencode-plugin package that forwards tool.execute.before/after, session.idle, etc. to crow hook-event over the existing socket. Commands map cleanly (.opencode/commands/<n>.md). Non-interactive single-shot mode isn't well-surfaced in the public docs — verify against opencode --help.
• Cursor (agent) — CLI is more real than I expected: agent -p, --continue, --resume, --sandbox, --mode=plan. But there is no documented custom-command surface and no hook system — Crow loses status tracking and per-event hooks unless it falls back to tmux scraping. Skills don't have a .cursor/ equivalent; the closest is .cursor/rules/*.mdc, which are passive context, not triggers.

4. Swap strategy

Three options:

• Plug-in adapter — single CLIBackend protocol. Tempting, but breaks down because each CLI's extensibility differs (skills ≠ agents ≠ rules; hook shell ≠ plugin JS ≠ none). The protocol works for binary/args/resume/sandbox; skills must be per-backend.
• Fork — second Crow build per CLI. Wasteful given how much is already CLI-neutral.
• Hybrid ✅ — introduce a CLIBackend Swift protocol covering: binary discovery, launch-args assembly, resume command, hook-config writer (path + event-name table + payload mapper), settings-file path, attribution trailer line, and OTEL env-var name. Bundle one ClaudeCodeBackend and one CodexBackend. Skills/prompts move to a per-backend, user-owned ~/.crow/skills/<backend>/ tree — accepting that /crow-workspace-style triggers may need a different launcher recipe on backends without custom slash commands.

5. Effort estimate

• Codex — S–M, ~1–3 weeks for full parity. Hook compatibility is the unlocker. The biggest item is renaming the eight or so .claude/... paths and porting four skill bodies (which already use gh/glab and tmux — both CLI-neutral). Realistic next backend.
• OpenCode — M–L, ~4–6 weeks. Hook adapter is a JS plugin, not a config file rewrite; Crow gains a second dependency runtime. Commands port cleanly. Worth doing once Codex proves the adapter shape.
• Cursor — L, ~6–10 weeks for parity, or M for a degraded "fire-and-forget single-shot" mode. No hooks means Crow falls back to tmux scraping for state, which is fragile. Skills can't be ported. Best treated as a future "Cloud Agent handoff" target (&-prefix in the CLI), not a primary backend.

6. Out-of-scope but worth flagging

• Attribution trailer is hardcoded Co-Authored-By: Claude (setup.sh:356-397). Per-backend literal needed.
• UI labels in AutomationSettingsView.swift and elsewhere mention "Claude" — search-and-replace pass needed.
• CLAUDE_CODE_ENABLE_TELEMETRY (SessionService.swift:431) has no analog on Codex/OpenCode/Cursor; Crow's OTEL plumbing becomes backend-conditional.
• The Manager session itself runs Claude Code today (UUID 00000000-…) — swapping the Manager is a separate, larger question because the prompts in skills/crow-workspace/SKILL.md assume Claude Code's interpretation of dangerouslyDisableSandbox, Bash(...) allowlist patterns, and natural-language slash dispatch.

Bottom line: if anyone wants to pursue this, prototype Codex behind a CLIBackend protocol first — the adapter is genuinely small and the hook surface aligns. OpenCode and Cursor become tractable once that scaffolding lands; Cursor will always lose some capability.

---

Verification: file:line citations are against feature/crow-401-investigate-cli-swap @ 3fa407e. Candidate-CLI claims verified against developers.openai.com/codex/{noninteractive, hooks, skills, concepts/sandboxing}, opencode.ai/docs/{plugins, agents, commands}, and cursor.com/docs/{cli/overview, context/rules} on 2026-06-01.

[dgershman]

Addendum — Cursor agent --help corrects the table

Thanks for the --help paste. Several things change once we have the actual flag surface (most of which isn't on cursor.com/docs yet):

Corrections to the §3 table — Cursor column

Capability	Cursor — corrected
Non-interactive prompt	agent -p "<prompt>" (full tool access including write + shell)
Resume / continue	agent --continue, agent --resume [chatId], agent create-chat (returns ID — Crow can pre-allocate sessions)
Skill / command extension	agent generate-rule (interactive rule scaffolder), --plugin-dir <path> for per-invocation plugin loading, plus .cursor/rules/*.mdc. Still no /<name> custom slash commands, but plugins are a real surface.
Hooks	Not surfaced. But — see next row.
Sandbox / permission	--sandbox enabled|disabled, --force / --yolo (run everything; analog to --permission-mode auto), --trust for headless workspace trust
Memory file	Unchanged: AGENTS.md + .cursor/rules/*.mdc
Scrape-able output	--output-format text|json|stream-json with --stream-partial-output for token-level streaming. This is a real event stream — comparable to Codex --json. I had this wrong in the original comment.

Also surfaces I missed:

• -w, --worktree [name] — native git-worktree support at ~/.cursor/worktrees/<reponame>/<name>, with setup scripts via .cursor/worktrees.json. Conflicts with Crow's own worktree model (ADR 0003); Crow would always pass --skip-worktree-setup and keep ownership.
• agent worker — private cloud worker for remote execution. Out of scope, but relevant for a future "remote Crow" mode.
• agent mcp — MCP server management (useful symmetry with Claude Code's MCP).

Revised §5 sizing — Cursor

• Cursor — M (~3–4 weeks), not L. With agent -p --output-format stream-json --resume <chatId> --trust --force + create-chat for pre-allocation, the control-plane parity with Claude Code is much closer than I estimated. Crow can scrape the JSON stream for tool-use / completion events in lieu of callback hooks. Remaining gaps:
  • No callback hook system — must scrape stream-json events instead. Latency and reliability are different (parser owns the stream), but workable.
  • No .claude/skills/<n>/SKILL.md analog. .cursor/rules/ are passive context, not triggers; --plugin-dir plugins are the closest functional substitute and would have to be authored from scratch per skill.
  • Manager-style /crow-workspace slash dispatch doesn't exist — Crow would invoke the equivalent setup directly via agent -p with a composed prompt.

Recommendation — unchanged but tightened

Codex is still the realistic next backend (hook parity is the unlocker, and the .agents/skills/<n>/SKILL.md open standard means most of Crow's bundled skills port with a path rename). Cursor moves up to viable second ahead of OpenCode for the headless Crow use case, specifically because its stream-json output gives a scrape surface OpenCode lacks. OpenCode's value is the richer plugin runtime, which only pays off if Crow wants in-process JS callbacks rather than out-of-process shell hooks.

Revised order: Codex (S–M) → Cursor (M) → OpenCode (M–L).

[dhilgaertner]

@dgershman Check out my branch related to the codex implementation I made. Everything is generic so that other harnesses can be added in. I haven't landed this branch yet because i still need to test.

[dhilgaertner]

#197

[dgershman]

Second addendum — researched the remaining gaps

Five things I should have looked up myself before asking. Posting answers + impact.

1. Cursor --print slash-commands: broken

Per Cursor forum thread (Sept 30 2025), cursor-agent -p "/joke" --output-format text does not expand ~/.cursor/commands/joke.md or ./.cursor/commands/joke.md — the agent treats /joke as literal text. Workaround is to inline the file:

cursor-agent -p "$(cat ~/.cursor/commands/joke.md) $*" --output-format stream-json

Impact for Crow. The Manager's /crow-workspace <url> send at AppDelegate.swift:513 cannot drive a Cursor worker through --print. Two paths: (a) Manager composes the full prompt and pipes it to agent -p, or (b) workers run interactively (no -p) and lose the JSON event stream. Path (a) is the realistic one and is exactly the per-backend "send recipe" the CLIBackend protocol needs to own.

2. Cursor commands: project + global scope, no frontmatter

Per Cursor 1.6 changelog and community references, commands live at .cursor/commands/<name>.md (project) and ~/.cursor/commands/<name>.md (global). They are plain Markdown — no YAML frontmatter, single content field; the entire file body becomes the prompt template. Filename = command name. There's also a known bug where local .cursor/commands don't load in Cursor Cloud / Background Agent — forum report.

Impact for Crow. Crow's bundled command files would need a thin transform: strip frontmatter when scaffolding for Cursor. Skills (which do have frontmatter and are loaded from .claude/skills/ natively) are the cleaner port target on Cursor, given the headless-commands bug above.

3. OpenCode non-interactive: opencode run exists

I was wrong on this. Per official CLI docs and community references, the headless surface is:

opencode run "<prompt>"                    # one-shot
opencode run "..." -f json -q              # JSON output, quiet
opencode run "..." -c                      # --continue last session
opencode run "..." -s ses_xxx              # resume specific session
opencode run "..." --dangerously-skip-permissions   # fully unattended
opencode run "..." --attach http://localhost:4096   # attach to opencode serve for warm MCP

Caveats (real, documented):

• No stdin prompt support — positional argument only (issue #13851).
• Permission prompts hang automation — open feature request (issue #10411) to make non-TTY auto-reject. Today you need --dangerously-skip-permissions or you risk a hang.
• opencode serve + run --attach reportedly has bugs as of v1.1.60.

Impact for Crow. OpenCode jumps to roughly parity with Codex/Cursor for headless single-shot. The -f json mode gives Crow an event stream to scrape in lieu of shell hooks (the plugin-runtime hook gap remains, but is no longer the only path to state tracking). I'm revising the size downward.

4. Cursor "Memories": per-project, native since v1.0

Per forum threads, egghead context and MemNexus writeup: Cursor Memories shipped in v1.0 (June 2025), stores short preference strings per-project, lives inside Cursor only. Not cross-tool, not cross-machine. Survives sessions within the same project. Persistence across --resume is presumed (it's project-scoped, not session-scoped), but I couldn't find an authoritative statement. Cross-project / cross-tool memory is bolted on via MCP servers (Basic Memory, MemNexus, Recallium, CORE).

Impact for Crow. Crow's only existing memory hook is the preserve-## Known Issues / Corrections-section logic in Scaffolder.swift:38-62 against CLAUDE.md. Each backend has its own equivalent (CLAUDE.md / AGENTS.md / Cursor in-app memories) — the scaffolder needs a per-backend memory-file path and merge strategy. Cursor's in-app memories aren't a file, so Crow can't preserve them via filesystem; that's a backend-specific limitation worth flagging.

5. Manager session swap

Reasoning from the source (no external research needed here): the Manager runs Claude Code at UUID 00000000-… and its only worker-facing output is text it pushes into a worker's tmux buffer (AppDelegate.swift:513, 525). The Manager does not need to be the same backend as workers — it just needs to know how to compose the right opening text per-backend:

• Claude Code worker → /crow-workspace <url>\n
• Codex worker → $crow-workspace <url>\n (skill activation via $) or /skills crow-workspace <url>\n
• OpenCode worker → equivalent slash command if migrated, otherwise full prompt body
• Cursor worker → full prompt body (slash commands don't expand in --print)

That "send recipe per backend" is exactly what the CLIBackend.openingSendText(for: worktree) method I sketched earlier should return. So the Manager can stay on Claude Code regardless of worker backends, which is a meaningful simplification.

Revised §5 sizing — final

Candidate	Final sizing	Notes
Codex	S–M (1–3 weeks)	Unchanged. Hook event names match, .agents/skills/ is the open standard, --json event stream. Realistic next backend.
OpenCode	M (3–5 weeks), down from M–L	opencode run -f json -c -s gives full headless control. Hooks remain JS-plugin-only (Crow ships a bundled @crow/opencode-plugin shim → crow hook-event), but skills load from .claude/skills/ natively.
Cursor	M (3–5 weeks), down from L	agent -p --output-format stream-json --resume --trust --force gives full headless. .claude/skills/ loaded natively. But --print mode doesn't expand /foo slash commands, so Manager dispatch always composes the full prompt for Cursor workers. No hook callbacks; Crow scrapes stream-json events.

Order for "which to pursue first": Codex → OpenCode → Cursor if the priority is feature parity (hooks, command dispatch). Codex → Cursor → OpenCode if the priority is minimizing new runtimes (Crow stays out of the JS plugin business).

Sources

• Cursor forum: slash commands in cursor-agent -p — confirms --print doesn't expand custom slash commands as of Sept 30 2025
• Cursor 1.6 changelog — slash commands introduced
• hamzafer/cursor-commands — format reference, no frontmatter
• Cursor forum: local commands in Cursor Cloud
• OpenCode official CLI docs and opencode.asia CLI reference
• OpenCode issue #10411 — non-interactive permission hang
• OpenCode issue #13851 — no stdin prompt in run
• ComputingForGeeks OpenCode cheat sheet
• Cursor forum: persistent memory
• MemNexus writeup on Cursor memories

[dgershman]

Superseded by #417, which folds in the investigation answers (PR #197 shipped Phases A+B; the broad CLI-swap question is answered) and scopes the remaining Phase-C-equivalent work for Cursor specifically — with documented CLI surface, hook event mapping, Skills compat finding, and a test plan modeled on PR #197.