# Cursor Subagent

> Cursor sidecar delegation. Use when explicitly asked to spawn Cursor or a Cursor-hosted Grok model for exploration, review, or isolated implementation. Native xAI Grok Build CLI requests belong to grok-cli-runtime.

- Skill: `jorgemenadev/cursor-subagent` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jorgemenadev/cursor-subagent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jorgemenadev/cursor-subagent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: jorgemenadev (https://skillmd.com/u/jorgemenadev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jorgemenadev/cursor-subagent

---


# Cursor Subagent

## Contract

- Cursor is a **sidecar**: an external `cursor-agent --print` process with its own session id, tools, auth, and workspace.
- Read-only is default: use `ask` for exploration/review and `plan` for planning.
- Implementation uses `agent` mode only in an isolated branch, worktree, or scratch workspace.
- Parent agent reviews all reports or diffs before integration.
- The active workspace authority contract governs credentials, production mutations, external sends, account actions, destructive operations, and final confirmation. Include that contract in any sidecar prompt that may reach those surfaces. Without one, stay read-only and stop before external effects.

## Preamble

Set `SKILL_DIR` to this skill directory, then run:

```bash
MODE="${MODE:-ask}"
WORKSPACE="${WORKSPACE:-$PWD}"
MODEL="${MODEL:-cursor-grok-4.5-high}"
WRAPPER="$SKILL_DIR/scripts/run-cursor-subagent.sh"
[ -x "$WRAPPER" ] && echo "WRAPPER: ok" || echo "WRAPPER: missing"
command -v cursor-agent >/dev/null 2>&1 && echo "CURSOR_AGENT: ok" || echo "CURSOR_AGENT: missing"
echo "MODE: $MODE"
echo "WORKSPACE: $WORKSPACE"
echo "MODEL: $MODEL"
if [ "$MODE" = agent ] && git -C "$WORKSPACE" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  dirty=$(git -C "$WORKSPACE" status --short)
  branch=$(git -C "$WORKSPACE" branch --show-current)
  [ -z "$dirty" ] && echo "GIT_STATE: clean:$branch" || echo "GIT_STATE: dirty:$branch"
elif [ "$MODE" = agent ]; then
  echo "GIT_STATE: no-git"
else
  echo "GIT_STATE: not-needed"
fi
```

Branch only on those tokens:

- `WRAPPER: missing` or `CURSOR_AGENT: missing` -> stop and report the missing dependency.
- `MODE: agent` plus `GIT_STATE: dirty:*` or `GIT_STATE: no-git` -> STOP. Launching a write-capable external agent into an unisolated or dirty workspace is the failure this gate prevents. Create a clean branch/worktree/scratch workspace or get explicit user approval for the risk.
- `MODE: ask|plan` -> proceed read-only.

The wrapper performs the live Cursor auth/model preflight and fails before launch if the model is unavailable.

## Launch

Read-only exploration:

```bash
"$WRAPPER" --workspace "$WORKSPACE" --mode ask --model "$MODEL" -- \
  "You are a Cursor CLI sidecar launched by another agent. Explore <scope>. Do not edit files. Return findings with file paths."
```

Write-capable implementation:

```bash
"$WRAPPER" --workspace "$WORKSPACE" --mode agent --force --model "$MODEL" -- \
  "You are a Cursor CLI sidecar launched by another agent. Implement <bounded change>. Scope: <files>. Do not revert unrelated changes. Follow this workspace authority contract exactly: <contract-or-read-only-fallback>. Return changed files and validation."
```

Use `--force` only for intentional write-capable runs. The wrapper refuses `--mode agent` without it.

## Output Format

End with:

```text
STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED
CURSOR_SESSION: <session_id or none>
OUTPUT: <json output path>
SUMMARY: <one line>
CHANGED_FILES: <none or paths>
VALIDATION: <commands/evidence or not run>
```

## Anti-Patterns

- Treating Cursor's report as verified truth: verify critical claims locally.
- Running `agent` mode on the user's dirty checkout: use an isolated workspace.
- Hardcoding UI labels as model ids: use `cursor-grok-4.5-high` by default and let the wrapper confirm it with `cursor-agent models`.
- Resuming by habit: resume only when the follow-up depends on Cursor's prior context.