# Use Droid

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

- Skill: `oimiragieo/use-droid` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oimiragieo/use-droid`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/use-droid/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: oimiragieo (https://skillmd.com/u/oimiragieo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oimiragieo/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
```powershell
& droid exec -m claude-opus-4-8 --cwd <workspace>\foo "your task"
```

### Invocation from WSL bash (the way Claude orchestrator uses):
```bash
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) |
| `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:**
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

```dot
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

```bash
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:

```markdown
## 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):**

```bash
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):**

```bash
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):**

```bash
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

```bash
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.