Use Droid

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

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).

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

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:

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

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.