use-droid

name

use-droid

description

Use when delegating bounded coding, audit, multi-agent mission, or review work to Factory's Droid CLI (droid exec, --mission mode with worker+validator subagent orchestration). Droid runs Claude Opus 4.8 by default (also carries Fable 5, Sonnet 5, GLM-5.2, Kimi K2.7, MiniMax M3, nemotron-3-ultra) on one Factory subscription across Anthropic/OpenAI/Google. Sibling skill of use-codex / use-gemini / use-cursor / use-copilot. Invoke from PowerShell (droid.ps1), NOT WSL — WSL's droid lacks auth (FACTORY_API_KEY error). Use -m to switch model, --cwd (Windows path) for target dir, -w/--worktree for isolated edits, -r/--resume or --fork for session memory. NOT for small targeted edits or live mid-flight debugging.

Use Droid

CRITICAL: invoke from PowerShell, NOT WSL

Always dispatch droid via powershell.exe. The Windows-side install at C:\Users\you\AppData\Roaming\npm\droid.ps1 reads auth from C:\Users\you\.factory\auth.v2.* and works cleanly. The WSL-side binary at /home/you/.local/bin/droid reads /home/you/.factory/ which has NO auth files and fails with Authentication failed. Please log in using /login or set a valid FACTORY_API_KEY environment variable.

Verified 2026-05-13: PowerShell droid exec -m claude-opus-4-8 "respond OK" → returns OK. WSL droid exec ... same args → auth error.

Invocation from PowerShell directly

& droid exec -m claude-opus-4-8 --cwd <workspace>\foo "your task"

Invocation from WSL bash (the way Claude orchestrator uses):

nohup powershell.exe -ExecutionPolicy Bypass -Command \
  "& droid exec --cwd '<workspace>\foo' -m kimi-k2.6 'your task'" \
  </dev/null > /tmp/droid_out.log 2>&1 &

The --cwd must be a Windows path (C:\...), not a WSL path (/mnt/c/...), because the running droid process is Windows-native. Convert with: echo "$WSL_PATH" | sed 's#^/mnt/c/#C:/#; s#^/c/#C:/#; s#/#\\#g'

Core rule

Droid is a bounded implementation worker AND a multi-agent mission orchestrator. Claude owns the plan, the prompt file, the audit synthesis, the tests, the commits, and the final answer to the user.

Droid's killer features over the other CLIs:

1. Multi-provider on one subscription — Anthropic + OpenAI + Google models switchable with -m. No per-provider billing math.
2. Mission mode (--mission) — built-in worker/validator subagent fan-out. When you'd otherwise dispatch N parallel Claude Agent subagents for a big build, droid mission does it server-side without burning your context.
3. Worktree-native — -w/--worktree flag spins up a git worktree automatically; safer for risky edits than running in-place.

When to use vs when to skip

Use droid	Use Claude Agent tool subagent
Multi-agent missions (build a feature with worker + validator decomposition)	Single-task work that fits in one Claude turn
Cross-provider audit (have droid run gemini-3.1-pro then claude-opus-4-8 on same diff)	Single-model review (use codex/gemini directly)
Worktree-isolated bulk write following an explicit spec	Edits where you need to inspect mid-flight
Long-horizon implementation (hours) where token budget matters	Conversational reasoning that must feed back to this thread
When you specifically want Factory's session memory (-r/--resume, --fork)	Anything where Claude session context is load-bearing

Don't use droid for:

• Small targeted edits (Edit tool is faster)
• Live debugging needing mid-flight Claude context
• Tasks where the final synthesis must happen in this conversation

Available models (probed 2026-05-03)

Default is claude-opus-4.7. Use -m <id> to switch. Full benchmark-backed analysis at docs/audits/2026-05-03-cli-model-task-matrix-extension.md (and 2026-05-02 base matrix for codex/gemini family detail).

Model ID	Family	Best for	Headline benchmark	Don't use for
claude-opus-4.7 (default)	Anthropic	Multi-file production code review, frontier blast-radius decisions	SWE-Bench Pro 64.3% (beats GPT-5.5's 58.6%)	Terminal-heavy work — codex 5.5 wins (82.7% vs ~75% for Opus)
claude-opus-4.6	Anthropic	Cost-floor prod where 4.7's gains aren't worth delta	SWE-Bench Pro ~62%	Coding work — dominated by 4.7
claude-sonnet-4.6	Anthropic	Mid-tier; what Agent tool model: "sonnet" invokes	GDPval-AA 57% (beats gemini-3.1-pro's 40%)	Multi-file refactors where Opus 4.7 fits
claude-haiku-4	Anthropic (legacy)	Backward-compat against pre-4.5 haiku	—	New work — pick claude-haiku-4.5 via copilot
gpt-5.5	OpenAI	Terminal/agentic harness work, FrontierMath, cybersecurity	Terminal-Bench 2.0 82.7% (SOTA), GDPval 84.9%, FrontierMath Tier 4 39.6%	Routine work — 5.4 fits at half the cost
gpt-5.4	OpenAI	Default everyday coding, multi-file edits, native computer use	SWE-Bench Pro 57.7%, OSWorld 75.0%	Frontier reasoning beyond 272K (price cliff)
gpt-5.4-mini	OpenAI	Parallel subagent fan-out, OSWorld/screenshot tasks	OSWorld 72.1% (near full 5.4's 75.0%)	Long-context retrieval — MRCR collapses to 47.7% at 64K-128K
gpt-4.1 / gpt-4.1-mini	OpenAI (legacy)	Backward-compat testing only	—	New work — superseded by 5.x family
gemini-3.1-pro-preview	Google	Distributed-systems reasoning, web research, >200K context	GPQA 94.3% (SOTA), ARC-AGI-2 77.1% (~2× others)	Terminal-heavy work — harness instability (Cleary writeup)

Picking a model — quick decision

Cross-vendor opinion in one CLI?
  → -m claude-opus-4.7 OR -m gpt-5.5 OR -m gemini-3.1-pro-preview (run all 3 if it's high-stakes)

Long mission with worker + validator?
  → --mission --worker-model claude-haiku-4 --validator-model gpt-5.5 -m claude-opus-4.7

Frontier code review of a money/auth/migration diff?
  → -m claude-opus-4.7 (SWE-Bench Pro winner) OR -m gpt-5.5 (Terminal-Bench SOTA)
  Run BOTH for highest-stakes diffs (different cognitive lineages = independent signal).

Bulk fan-out, cost-sensitive?
  → -m claude-haiku-4 OR -m gpt-5.4-mini

Distributed-system / race-condition / abstract reasoning?
  → -m gemini-3.1-pro-preview (GPQA 94.3% SOTA, ARC-AGI-2 77.1%)

Verify availability before long runs: probe with droid exec -m <id> "ping". Wrong IDs return clear errors at first call.

Canonical Factory model picker (verified from droid exec --help "Available Models" after droid update 0.121.0 → 0.164.0, 2026-07-02)

-m ID (exact, from the help list) · Display name · (cost multiplier) — -m ID is the lowercased/hyphenated form (e.g. "Kimi K2.7 Code" → kimi-k2.7-code). ★ = Factory recommended. Probe droid exec -m <id> "ping" to confirm. ⚠ Stale-binary trap: a standalone <user-bin>\droid.exe shadows PATH and the npm ~/AppData/Roaming/npm build was a separate stale 0.122.0 — if new IDs return Invalid model, run droid update (NOT npm) to refresh the PATH binary agents dispatch through.

Current (Factory-provided), 2026-07-02:

Anthropic:  claude-opus-4-8 (2x) ★default · claude-opus-4-8-fast (4x) · claude-opus-4-7 (2x)
            claude-opus-4-7-fast (12x) · claude-opus-4-6 (2x) · claude-opus-4-5-20251101 (2x)
            claude-fable-5 (4x) · claude-sonnet-5 (0.8x, Launch Pricing) · claude-sonnet-4-6 (1.2x)
            claude-sonnet-4-5-20250929 (1.2x) · claude-haiku-4-5-20251001 (0.4x)
OpenAI:     gpt-5.5 (2x) · gpt-5.5-fast (5x) · gpt-5.5-pro (12x) · gpt-5.4 (1x) · gpt-5.4-fast (2x)
            gpt-5.4-mini (0.3x) · gpt-5.3-codex (0.7x) · gpt-5.3-codex-fast (1.4x) · gpt-5.2 (0.7x)
Google:     gemini-3.1-pro-preview "Gemini 3.1 Pro (High)" ★ (0.8x) · gemini-3.5-flash (0.6x) · gemini-3-flash-preview (0.2x)
China (Droid Core): glm-5.2 (0.55x) · glm-5.2-fast (1.1x) · glm-5.1 (0.55x) · kimi-k2.7-code (0.38x)
            kimi-k2.6 (0.4x) · nemotron-3-ultra (0.24x)
            minimax-m3 (0.12x) · minimax-m2.7 (0.12x) · minimax-m2.5 (0.12x)

Deprecated (avoid): gpt-5.2-codex (0.7x), gpt-5.1-codex-max (0.5x), kimi-k2.5 (0.25x), glm-5, glm-4.7.

Two big implications:

1. droid is a CROSS-VENDOR fallback. It runs gpt-5.5, gpt-5.3-codex, claude-opus-4-8, claude-sonnet-5, gemini-3.1-pro-preview on ONE Factory sub. So when codex-cli's gpt-5.5 cap is exhausted (returns empty — see use-codex fallback chain), droid exec -m gpt-5.5 is a third way to keep the frontier-5.5 seat alive. Cheapest China-frontier seats: MiniMax M3/M2.7 (0.12x).
2. Current China-frontier IDs (2026-07-02 update): kimi-k2.7-code (0.38x, supersedes kimi-k2.6), minimax-m3 (0.12x, supersedes minimax-m2.7), glm-5.2 (0.55x, supersedes glm-5.1; glm-5.2-fast = 1.1x fast variant). The prior IDs remain routable as fallbacks. New: nemotron-3-ultra (0.24x) as a distinct-lineage alternate. The default model is now claude-opus-4-8 (was 4.7).

Workflow

digraph droid_workflow {
  "Identify droid-fittable task" -> "Verify droid CLI auth";
  "Verify droid CLI auth" -> "Write task spec file";
  "Write task spec file" -> "Pick model + autonomy level";
  "Pick model + autonomy level" -> "Mission or single-task?";
  "Mission or single-task?" -> "droid exec --mission" [label="mission"];
  "Mission or single-task?" -> "droid exec" [label="single"];
  "droid exec --mission" -> "Wait for exit";
  "droid exec" -> "Wait for exit";
  "Wait for exit" -> "Audit diff via subagent";
  "Audit diff via subagent" -> "Run tests";
  "Run tests" -> "Claude commits";
}

1. Verify droid is installed and authed

which droid && droid --version
droid exec --list-tools 2>&1 | head -5   # confirms auth works

If which droid returns empty, droid was not installed. The user installs via Factory's instructions; do not attempt yourself. If --list-tools prints an auth error, the user must droid login themselves.

2. Write the task spec file

Save at <repo>/.claude/droid_task_<short-name>.md. Same shape as the use-codex spec template — explicit objective, inputs (read-only), edits required (with inline content), constraints (no commit/push), done criteria, final report line.

If task is a driver script for a long-running remote job: cite your own job-driver conventions if you keep them documented, and require droid to load + apply whatever environment-setup prerequisites (dependency pins, version upgrades) the target environment needs before the main work starts, so the job doesn't crash partway through.

For mission mode add an extra section:

## Mission decomposition (if --mission)
Workers should each handle:
1. <Task A — bounded scope, separate files>
2. <Task B — bounded scope, separate files>
3. <Task C — bounded scope, separate files>

Validator must verify:
- All N files in scope were edited (no scope creep)
- Tests pass (run: `<command>`)
- No lint errors (run: `<command>`)
- Spec section X is fully implemented

3. Launch droid

Single-task (default model = claude-opus-4-8):

nohup droid exec --auto medium --cwd <workspace>/<repo> \
  -f <workspace>/<repo>/.claude/droid_task_<name>.md \
  > /tmp/droid_<name>.log 2>&1 &
echo $! > /tmp/droid_<name>.pid

Single-task with provider switch (e.g. gpt-5.5 audit pass):

nohup droid exec --auto low -m gpt-5.5 --cwd <repo> \
  "Audit the diff produced by cursor-agent against spec in .claude/cursor_task_X.md. Output: severity-ranked findings. No file edits." \
  > /tmp/droid_<name>.log 2>&1 &

Mission mode (parallel subagents server-side):

nohup droid exec --mission --auto high \
  -m claude-opus-4-8 \
  --worker-model claude-haiku-4-5 \
  --validator-model gpt-5.5 \
  --cwd <repo> \
  -f <workspace>/<repo>/.claude/droid_mission_<name>.md \
  > /tmp/droid_mission_<name>.log 2>&1 &

The mission orchestrator dispatches workers (haiku, cheap fan-out) and runs the validator (gpt-5.5, second-opinion) before declaring success. Saves the orchestrator paying for both fan-out AND review tokens.

4. Autonomy levels

Level	What droid will do	Use when
(default, no --auto)	Read-only — cat, ls, git diff, find	Audit / review-only specs
--auto low	Read + minor edits requiring confirmation	Bounded one-file work
--auto medium	Read + edits + run tests + git ops (no push)	Standard implementation work
--auto high	Full agent loop — read + edit + run + retry + multi-step	Mission mode, long-horizon builds
--skip-permissions-unsafe	All gates off	NEVER use unless you wrote the spec yourself and accept the blast-radius

Default to medium. Escalate to high only for missions where the task spec explicitly forbids destructive ops (commit, push, drop, rm).

5. Wait for exit, then layered audit: subagent first, you second

while kill -0 $(cat /tmp/droid_<name>.pid) 2>/dev/null; do sleep 30; done
echo "exited"; tail -60 /tmp/droid_<name>.log
git diff --stat

Same layered review pattern as use-codex / use-cursor:

1. Subagent audits droid's diff first — dispatch a feature-dev:code-reviewer Agent subagent with the spec path + the working-tree diff. Look for scope creep, wrong-file edits, content drift, hallucinated function names.
2. You audit the subagent's report + the suspicious hunks only — don't re-read the whole diff.
3. If clean — git add explicit files (NOT git add -A), commit, push.
4. If subagent flags issues — rewrite the spec to be more explicit, relaunch droid against the same files (droid sessions can be resumed via -r <session_id> if you want to keep context, or fresh-start if you want a clean second attempt).

6. Tests + commit

Run only the tests touching the changed files. If clean: git add explicit files, commit with a message that credits droid (worker: droid --auto medium -m <model>), push.

Prompt shape — required fields

Same as use-codex / use-cursor:

Field	Why
Objective (one sentence)	Tells droid what good looks like
Inputs (read-only paths)	Stops droid from rewriting files outside scope
Edits required (with INLINE content where possible)	Droid hallucinates less with verbatim content
Constraints (no commit/push, line endings LF, blockers signal exit)	Bounds blast radius
Done criteria (file count + line delta)	Audit anchor
Final report line	Signals exit cleanly
(Mission only) Worker decomposition + Validator checks	Prevents server-side drift

Guardrails

• Never paste raw markdown into the launch command. Use a file path argument and let droid open it via -f. Same shell-injection risk as cursor.
• No backticks in the inline prompt argument. Reference the spec file path.
• Process pollution check after a bad launch: ps -ef | grep -E "droid" | grep -v grep
• Do not pass HF_TOKEN, cloud-provider API keys, OPENROUTER_API_KEY, or other secrets in the prompt. Droid reads them from the environment when the spec asks.
• Worktree mode is your friend for risky work — -w creates a fresh worktree so a failed droid run can't corrupt your active branch.
• Mission mode validators DO NOT replace the post-run subagent audit. Mission validators check spec compliance from inside droid's context; an external Claude subagent catches cross-context drift the validator can't see (e.g., did droid edit a file the spec didn't mention?).
• Token-conserve discipline: if you find yourself reading whole files droid wrote rather than diffing them, the task was too big — split next time.

When to escalate / abort

• Droid exits non-zero or prints a BLOCKER line → read the log tail (last 60 lines), diagnose, possibly rewrite the spec + relaunch
• Droid edits files outside the "Edits required" scope → revert via git checkout -- <file>, narrow the spec
• Droid commits despite the no-commit constraint → git reset --soft HEAD~1 to keep the work, audit, then re-commit cleanly with our message
• Droid stalls past expected wall (>30 min for typical multi-file edits, >2 hours for missions) → kill $(cat /tmp/droid_*.pid), inspect log, decide whether to retry

Routing — when droid beats codex / gemini / cursor

Situation	Pick
Multi-file content writes ≥3 files following spec	cursor (unlimited tokens, auto-mode) — droid is fine but cursor is cheaper
Frontier peer-review pass on diff that touches money/auth/migration	codex (gpt-5.5) — cleanest single-model SOTA review
Distributed-system reasoning / cross-document consistency	gemini (3.1-pro plan-mode) — different blind spots from OpenAI
Multi-agent mission with built-in worker+validator	droid (--mission) — only CLI with this primitive
Cross-provider second opinion on the same task in one tool	droid (-m switching) — runs claude+gpt+gemini back-to-back without per-tool setup
Long-horizon (hours+) build that must survive Claude session reset	droid (-r resume) — session state lives in Factory, not your shell

Cross-references

• Sibling skills: use-codex, use-gemini, use-cursor, use-copilot
• If you run a multi-seat review orchestrator, it can combine all of the above into a single multi-stage deliberation.
• Evidence-backed model picker: keep your own model-task benchmark notes if you maintain them, and cite the doc here.
• For research/audit work that needs to feed back into THIS conversation, prefer the Claude Agent tool over droid — droid commits silently and you audit the diff, while Claude subagents return their report inline.