| 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:
- Multi-provider on one subscription — Anthropic + OpenAI + Google models switchable with
-m. No per-provider billing math.
- 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.
- 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) |
gemini-3.1-flash | Google | Cheap reasoning at fast-tier price; 1M-context audits | GPQA ~90%, 1M context | Code generation — lags GPT-5 mini on LiveCodeBench |
gemini-auto | Google (router) | Defer model choice to Google's router | varies | Reproducibility — routing is not pinned |
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:
- 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).
- 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
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:
- 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.
- You audit the subagent's report + the suspicious hunks only — don't re-read the whole diff.
- If clean —
git add explicit files (NOT git add -A), commit, push.
- 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.
