Skip to main content
Factory Droid is Factory’s enterprise AI coding assistant, supporting GPT-5, Claude 4, and Gemini models with advanced reasoning capabilities.

​
Overview

Factory Droid (droid) provides production-grade AI coding with support for the latest models from OpenAI, Anthropic, and Google.
Factory Droid supports session resume, read-only mode, image input, stream-json output, and thinking display with comprehensive usage tracking.

​
Installation

1

Install Factory Droid

Install via Factory’s official installer:
curl -fsSL https://install.factory.ai/droid | sh
2

Authenticate

Authenticate with Factory:
droid auth login
Follow the prompts to sign in with your Factory account.
3

Verify Installation

Test Factory Droid:
droid --version

​
Capabilities

Factory Droid provides enterprise-grade AI features:
​
supportsResume
boolean
default:"true"
Resume sessions with -s, --session-id flag (requires a prompt)
​
supportsReadOnlyMode
boolean
default:"true"
Default mode is read-only (no flags needed)
​
supportsJsonOutput
boolean
default:"true"
Structured output with -o stream-json
​
supportsSessionId
boolean
default:"true"
UUIDs in session filenames
​
supportsImageInput
boolean
default:"true"
Attach images with -f, --file flag
​
supportsImageInputOnResume
boolean
default:"true"
Images work with -s flag
​
supportsSessionStorage
boolean
default:"true"
Sessions in ~/.factory/sessions/ (JSONL files)
​
supportsUsageStats
boolean
default:"true"
Token usage in settings.json per session
​
supportsModelSelection
boolean
default:"true"
Select models with -m, --model flag
​
supportsStreamJsonInput
boolean
default:"true"
Stream-json input format supported
​
supportsThinkingDisplay
boolean
default:"true"
Thinking content in message streams
​
supportsContextMerge
boolean
default:"true"
Receive merged context via prompts
​
supportsContextExport
boolean
default:"true"
Exportable session files
Factory Droid provides token counts but NOT cost tracking. Pricing varies by model and Factory plan.
Source: src/main/agents/capabilities.ts:290

​
Command-Line Arguments

Maestro uses the exec subcommand for batch operations: 
droid exec --skip-permissions-unsafe -o stream-json [options] "prompt"
​
exec
subcommand
Batch execution mode (required for Maestro)
​
--skip-permissions-unsafe
flag
Auto-approve all operations (like Claude’s —dangerously-skip-permissions)
​
-o
string
default:"stream-json"
Output format for structured parsing
Factory Droid doesn’t use -- separator. The prompt is a positional argument.

​
Resume Mode

Resume an existing session: 
droid exec --skip-permissions-unsafe -o stream-json -s {sessionId} "prompt"
​
-s, --session-id
string
Session ID to resume (requires a prompt)

​
Read-Only Mode

Factory Droid’s default mode is read-only: 
droid exec -o stream-json "prompt"
Omitting --skip-permissions-unsafe runs in read-only mode. Maestro uses this flag for YOLO mode.

​
Model Selection

Specify a model: 
droid exec --skip-permissions-unsafe -o stream-json -m gpt-5.1-codex "prompt"
​
-m, --model
string
Model ID from supported models list

​
Reasoning Effort

Adjust reasoning level: 
droid exec --skip-permissions-unsafe -o stream-json -r high "prompt"
​
-r, --reasoning-effort
string
Reasoning level: low, medium, high

​
Working Directory

Set working directory: 
droid exec --skip-permissions-unsafe -o stream-json --cwd /path/to/project "prompt"
​
--cwd
string
Working directory for execution

​
File/Image Input

Attach a file or image: 
droid exec --skip-permissions-unsafe -o stream-json -f /path/to/image.png "prompt"
​
-f, --file
string
Path to file or image
Source: src/main/agents/definitions.ts:261

​
Configuration

Configure Factory Droid in Maestro’s agent settings:

​
Model Selection

​
model
select
default:""
Model to use (empty = Factory’s default)Options:
  • “ - Use droid’s default
  • gpt-5.1 - OpenAI GPT-5.1
  • gpt-5.1-codex - GPT-5.1 optimized for coding
  • gpt-5.1-codex-max - Extended context
  • gpt-5.2 - Latest GPT-5
  • claude-sonnet-4-5-20250929 - Claude Sonnet 4.5
  • claude-opus-4-5-20251101 - Claude Opus 4.5
  • claude-haiku-4-5-20251001 - Claude Haiku 4.5
  • gemini-3-pro-preview - Google Gemini 3 Pro

​
Reasoning Effort

​
reasoningEffort
select
default:""
How much the model should reasonOptions:
  • “ - Use droid’s default
  • low - Fast responses
  • medium - Balanced
  • high - Deep reasoning

​
Context Window

​
contextWindow
number
default:"200000"
Token limit for UI display (varies by model)
Source: src/main/agents/definitions.ts:302

​
Session Storage

Factory Droid stores sessions as JSONL files: 
~/.factory/sessions/{session-uuid}/
  ├── conversation.jsonl    # Conversation history
  ├── settings.json         # Model config, token usage
  └── files/                # Created/modified files
Maestro can import and resume Factory Droid sessions. Source: src/main/storage/factory-droid-session-storage.ts

​
Output Format

Factory Droid outputs newline-delimited JSON events: 
{
  "type": "session.started",
  "session_id": "abc-123-def",
  "model": "gpt-5.1-codex"
}
Source: src/main/parsers/factory-droid-parser.ts

​
Supported Models

Factory Droid supports cutting-edge models:
  • gpt-5.1 - Latest GPT-5
  • gpt-5.1-codex - Coding optimized
  • gpt-5.1-codex-max - Extended context
  • gpt-5.2 - Latest variant
  • claude-sonnet-4-5-20250929 - Balanced performance
  • claude-opus-4-5-20251101 - Maximum capability
  • claude-haiku-4-5-20251001 - Fast responses
  • gemini-3-pro-preview - Latest Gemini Pro

​
Error Patterns

Common errors Maestro detects:
​
AUTH_FAILED
error
Pattern: authentication failedSolution: Re-authenticate with droid auth login
​
MODEL_UNAVAILABLE
error
Pattern: model not availableSolution: Check model ID and Factory plan access
​
RATE_LIMIT
error
Pattern: rate limit exceededSolution: Wait or upgrade Factory plan
Source: src/main/parsers/error-patterns.ts

​
Usage with Maestro Features

Auto Run

Full support for playbooks with enterprise reliability

Group Chat

Multi-agent collaboration across providers

Context Grooming

Export and merge conversation context

Thinking Display

View model reasoning in real-time

​
Best Practices

1

Choose Model by Task

  • Use gpt-5.1-codex for coding
  • Use claude-opus-4-5 for complex reasoning
  • Use claude-haiku-4-5 for speed
2

Adjust Reasoning Effort

Set reasoning level based on task complexity to balance speed and quality
3

Monitor Token Usage

Check session settings.json for token consumption per model
4

Use Default Read-Only

Omit --skip-permissions-unsafe for safer analysis tasks

​
Troubleshooting

Verify installation:
which droid
droid --version
Re-authenticate:
droid auth logout
droid auth login
Factory Droid resume always needs a prompt:
droid exec -s session-id "Continue the task"

Build docs developers (and LLMs) love

Get started for freeTalk to us