Droid

Do NOT use Droid when: the task requires Craft Agent context (sources, skills, labels, automations, session state).

Quick Reference

# Basic (default model = GPT-5.4 Medium, read-only)
droid exec "Analyze this codebase for security issues" --output-format json --cwd /path/to/repo

# With autonomy for dev work
droid exec --auto medium "Fix the failing tests in src/auth" --output-format json --cwd /path/to/repo

# Different model
droid exec -m "custom:GPT-5.3-Spark-(High)-8" "Implement the feature" --output-format json --auto medium --cwd /path

# Git worktree isolation (CANNOT combine with --cwd)
cd /path/to/repo && droid exec --worktree --branch feat-name "Implement X" --output-format json --auto medium

# Multi-agent mission (requires --auto high or --skip-permissions-unsafe)
droid exec --mission --auto high "Build a complete auth system" --output-format json --cwd /path

# Resume a session
droid exec -s SESSION_ID "Follow-up instruction" --output-format json

# File input (long prompts)
droid exec -f /path/to/prompt.md --output-format json --auto medium --cwd /path

# Pipe input
echo "What does this code do?" | droid exec --output-format json --cwd /path

# Tool filtering (limit what Droid can use)
droid exec --enabled-tools "Read,Execute" "Read and explain this file" --output-format json

# Session tagging
droid exec --tag "craft-agent" --tag '{"name":"task","metadata":{"source":"skill"}}' "Do X" --output-format json

Models — ALL via vibeproxy (localhost:8317)

CRITICAL: NEVER use native Droid model IDs (claude-opus-4-6, gpt-5.4, gemini-3.1-pro, etc.). ALL models MUST use the custom: prefixed vibeproxy IDs below. Native IDs are blocked by org policy and will fail or use wrong billing.

Default behavior: When no -m flag is passed, Droid uses custom:GPT-5.4-(Medium)-2 (configured in ~/.factory/settings.json as sessionDefaultSettings.model). This is a good general-purpose default — only override when you have a reason.

GPT-5.4 (Flagship — best general coding)

GPT-5.3 Spark (Codex — fast, code-optimized)

Claude (via vibeproxy — CURRENTLY BROKEN)

Claude models through Droid+vibeproxy currently return "Exec failed". For any Claude-based work, use Craft Agent's native subagents (Agent tool, spawn_session, call_llm). Periodically re-test — this may get fixed.

Gemini (via vibeproxy)

Model Selection Guide

Autonomy Levels

Default to read-only or --auto medium. Only use --auto high when the user explicitly asks for push/deploy operations.

Output Formats

JSON Output Structure

{
  "type": "result",
  "subtype": "success",       // or "failure"
  "is_error": false,          // true on failure
  "duration_ms": 27442,
  "num_turns": 4,
  "result": "...",            // May be EMPTY when Droid uses tools (files, commands)
  "session_id": "uuid",      // Save this for session resume
  "usage": {
    "input_tokens": 57392,
    "output_tokens": 771,
    "thinking_tokens": 136
  }
}

CRITICAL: The result field is often empty when Droid performs tool actions (creating files, running commands). This is normal — the work was done, the files exist. Always verify by checking the filesystem or git status after tool-using tasks.

Edge Cases & Gotchas

1. --worktree and --cwd cannot be combined — use cd into the repo first, then --worktree
2. Bad model IDs produce no output (exit code 1, no JSON) — always use verified custom IDs
3. Bad --cwd paths give non-JSON errors (ENOENT on stderr, exit code 1)
4. Exit codes: 0 = success, 1 = failure — check $? for quick validation
5. Worktree output wraps JSON — worktree creation/preservation messages appear outside the JSON on stdout
6. Session resume requires a new prompt — --session-id loads history but needs new input
7. Droid invokes its own skills (Using Superpowers, Brainstorming) which add overhead for simple tasks — for quick tasks, consider using --enabled-tools to limit scope

Patterns for Craft Agent Integration

Simple Dispatch (Most Common)

RESULT=$(droid exec --auto medium "Your task here" --output-format json --cwd /path/to/repo 2>&1)
echo "$RESULT" | python3 -c "import json,sys; d=json.load(sys.stdin); print('Session:', d.get('session_id','?')); print('Success:', not d.get('is_error',True)); print('Result:', d.get('result','(tool actions performed)'))"

Long Task with Monitoring

For tasks expected to take >60 seconds, use stream-json to monitor progress:

droid exec --auto medium "Complex refactoring task" --output-format stream-json --cwd /path 2>&1 | while IFS= read -r line; do
  echo "$line" | python3 -c "import json,sys; d=json.load(sys.stdin); t=d.get('type',''); print(f'[{t}]', d.get('toolName','') or d.get('text','')[:80] if t in ('tool_call','message') else '')" 2>/dev/null
done

Session Continuity

Save the session_id from the first call, pass it back for follow-ups:

# First call
SID=$(droid exec --auto medium "Start implementing feature X" --output-format json --cwd /path 2>&1 | python3 -c "import json,sys; print(json.load(sys.stdin).get('session_id',''))")
# Follow-up
droid exec -s "$SID" "Now add tests for what you just built" --output-format json --auto medium 2>&1

Worktree Isolation

cd /path/to/repo
droid exec --worktree --branch feat-my-feature --auto medium "Implement the feature described in SPEC.md" --output-format json 2>&1
# Worktree is at /path/to/repo-wt-feat-my-feature (preserved if changes were made)

Search Past Sessions

droid search "keyword" --json --limit-sessions 5

Mission Mode (Multi-Agent)

Missions spawn parallel worker sessions for large tasks. Only use for substantial multi-file work.

droid exec --mission --auto high "Build a complete REST API with auth, CRUD, and tests" --output-format json --cwd /path

• Default worker model: GPT-5.4 Medium
• Default validation model: Claude Opus 4.6
• These are configured in ~/.factory/settings.json under missionModelSettings
• Missions are stored in ~/.factory/missions/

Droid's Own Ecosystem

Droid has its own subagents ("droids"), skills, plugins, and MCP servers configured at ~/.factory/. Notable custom droids: code-reviewer, debugger, correctness-bug-hunter, refactor-safety-auditor, worker. These are automatically used by Droid when relevant — you don't need to invoke them manually.

Decision Flowchart

Is this a coding/analysis task? ──no──> Use Craft Agent normally
         │yes
Does it need Craft Agent sources/context? ──yes──> Use native subagents
         │no
Do you want a non-Claude model (GPT-5.x, Gemini)? ──yes──> Use Droid
         │no
Is it a large multi-file refactor? ──yes──> Use Droid --mission
         │no
Do you want guaranteed worktree isolation? ──yes──> Use Droid --worktree
         │no
Is it read-only analysis with zero risk? ──yes──> Use Droid (default mode)
         │no
Use native Craft Agent subagents (simpler, integrated)