Subagentmaxxing

subagentmaxxing

Drive Codex and Cursor coding agents as subagents that behave just like native Claude Code subagents: give a prompt, pick a model + working dir + sandbox level, get one clean final answer back (optionally as structured JSON). Fan a prompt out across many models in parallel for consensus or a second opinion.

The engine is a single stdlib-Python CLI called subagent, installed wherever Codex, Cursor, and Claude are authenticated — either the machine you're on, or a remote host you reach over ssh with subagent-remote (set SUBAGENT_HOST to that host).

When to use this

• You (Claude/Fable) want to hand a self-contained task to another model — e.g. let

grok-4.5 or composer-2.5 write a function, review a diff, or research something.

• You want a second opinion / adversarial check from a different model family.
• You want cross-model consensus: same question to grok + composer + gpt-5.5 + claude,

compare answers.

• You want to parallelize independent subtasks across several agents.

If the work is Claude-native and you're already in Claude Code, just use the normal Agent tool. Reach for subagent when you specifically want a non-Claude model or a fan-out.

How to call it

Two ways to invoke, depending on where subagent is installed:

Locally (agents authed on this machine): call subagent directly.

On a remote host from your laptop: set SUBAGENT_HOST once, then use the subagent-remote shim — it forwards over ssh, quoting-safe, with stdin piped through (prompt via arg or -):

export SUBAGENT_HOST=my-agent-box   # any ssh host/alias where subagent is installed

# one subagent
subagent-remote run cursor -m grok --sandbox read "Explain what this repo does" -C /path/on/host

# prompt via stdin (avoids all quoting pain — preferred for long/complex prompts)
printf '%s' "$PROMPT" | subagent-remote run codex --sandbox read -

# fan out one prompt across models, parallel
subagent-remote fanout "Is this SQL injection-safe? yes/no + why" \
  --on cursor:grok --on cursor:composer --on codex --on claude:sonnet --sandbox read

(subagent-remote is just ssh "$SUBAGENT_HOST" 'subagent …' with the quoting handled.) The recipes below use plain subagent; prefix with subagent-remote when driving a remote host.

The four commands

| command | what it does | |---|---| | subagent run [opts] "prompt" | run one subagent, print its final answer | | subagent fanout "prompt" --on b:model ... | same prompt across many targets, parallel, prints JSON array | | subagent run … --background → jobs/wait/logs | detached execution + polling | | subagent models [backend] | list available models (and aliases) | | subagent doctor | check every backend is installed + authed |

Backends: claude, codex, cursor.

run options (also apply to fanout)

• -m, --model — model id or alias (see below). Omit for the backend default.
• -e, --effort minimal|low|medium|high|xhigh — reasoning effort (codex: config knob;

cursor: selects the grok tier; claude: encode in model).

• -C, --cwd DIR — working directory (default: cwd).
• --sandbox read|write|all — read = analysis only, write (default) = autonomous

edits in the workspace, all = no sandbox (dangerous). See mapping below.

• --system TEXT — system prompt / role instructions (claude: --append-system-prompt;

codex & cursor: prepended as a [SYSTEM INSTRUCTIONS] block).

• --schema FILE — JSON-schema file → structured JSON output (codex native; others best-effort).
• --worktree NAME — run inside an isolated git worktree (parity with Claude's

isolation:"worktree"); --worktree-base BRANCH sets the base. Edits don't touch your tree.

• --image FILE — attach an image (codex only; repeatable).
• --background — run detached, print a job id; poll with subagent wait / inspect with

subagent jobs and subagent logs .

• --json — print the full normalized envelope (backend, ok, result, session_id, usage,

duration_ms, worktree, cmd) instead of just the answer.

• --resume ID — continue a prior session (session_id from a previous envelope). Multi-turn

continuity is verified on codex and cursor.

• --timeout SECONDS — default 900.
• --add-dir DIR — extra readable/writable dir.

Model aliases (the ones worth remembering)

• cursor: grok → grok-4.5-high, grok-max → grok-4.5-xhigh,

composer → composer-2.5, composer-fast → composer-2.5-fast, opus → claude-opus-4-8-thinking-high, sonnet → claude-4.5-sonnet, gpt → gpt-5.5-high, gemini → gemini-3.1-pro.

• codex: omit -m for the default; gpt → gpt-5.5.
• claude: opus | sonnet | haiku.

⚠️ Cursor model ids must include an effort suffix — grok-4.5 alone is rejected; use grok-4.5-high (or the grok alias). Run subagent models cursor for the full live list.

Sandbox mapping (what each level does per backend)

| level | codex | cursor | claude | |---|---|---|---| | read | -s read-only | --mode ask | --permission-mode plan | | write | -s workspace-write | --force --sandbox enabled | --permission-mode acceptEdits | | all | --dangerously-bypass-approvals-and-sandbox | --force --sandbox disabled | --permission-mode bypassPermissions |

Use read for reviews/research/second-opinions. Use write when the subagent should actually edit files. Only use all when you explicitly need un-sandboxed shell.

Recipes

Second opinion on a diff (read-only):

git -C /path/to/repo diff | subagent run cursor -m grok --sandbox read \
  "Review this diff for bugs. Be terse: list only real issues." -C /path/to/repo

Cross-model consensus, then you synthesize:

subagent fanout "Should we index this column? table has 50M rows, queried by user_id range." \
  --on cursor:grok --on cursor:composer --on codex --sandbox read
# -> JSON array; read each .result, reconcile disagreements yourself.

Delegate a real edit to composer:

subagent run cursor -m composer --sandbox write \
  "Add type hints to utils.py and run the tests." -C /path/to/repo

Structured output:

# schema.json describing your object
subagent run codex --schema /path/to/schema.json --sandbox read \
  "Extract {title, severity, file} for each finding."

Notes & gotchas

• Codex is authed via ChatGPT login; Cursor via a session token lifted from the

Mac keychain into ~/.config/subagentmaxxing/cursor-access.jwt (valid ~2 months). When subagent doctor warns the token is near expiry, run lift-cursor-token on the Mac to refresh it. See docs/auth.md.

• Always prefer stdin (-) for prompts through the remote shim — it sidesteps every

layer of shell quoting.

• subagent run prints only the answer; add --json when you need session_id (to resume),

token usage, or the exact command that ran.

• Fanout runs up to --max-parallel (default 6) concurrently and prints a progress line per

task to stderr; the JSON array goes to stdout.

• This is not a replacement for the native Agent tool when you want a Claude subagent —

it's for reaching Codex/Cursor models specifically.

Full backend feature coverage: docs/backends.md · parity table: docs/feature-matrix.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Kuberwastaken
• Source: Kuberwastaken/subagentmaxxing
• License: MIT

Install and usage instructions live in the source repository linked above.