Factory Droid: the agent from specification to pull request

Droid in one sentence

A Factory Droid is an AI agent that performs software engineering work through a loop of context gathering, planning, tool use, observation, revision, and delivery. It can answer a codebase question in one turn or spend a long session changing files and running tests. The agent is produced by Factory and delivered through several interfaces.

The name used to describe a family of purpose-specific Droids such as Code, Review, Test, Knowledge, Project, and Document. The current product presents Droid as a broad software development agent and lets users add custom Droids, skills, plugins, review workflows, and Missions. Older articles that imply six isolated products describe an earlier packaging state.

Calling Droid a wrapper understates the harness. Calling it a model overstates Factory’s ownership of the weights. The useful description is a model-independent engineering agent platform: Factory controls the agent design and can route among model providers.

The execution loop

Factory’s published terminal benchmark analysis argues that this harness layer matters independently of the model. It describes model-specific prompting, simple tool schemas, environment bootstrapping, short default timeouts, explicit plan updates, runtime signals, and controlled long-running processes. These design details can reduce tool errors and wasted turns.

The loop is still probabilistic. Droid can choose the wrong file, accept a misleading test, misunderstand product intent, or spend many turns on an environment failure. A strong task gives it a clean branch, narrow outcome, relevant paths, explicit non-goals, deterministic checks, and a clear stop condition.

The Droid CLI and Desktop

The Droid CLI is the most direct surface. Run droid in a project to open the full-screen terminal interface. It shows the current interaction mode, autonomy level, model, MCP state, transcript, tool proposals, and diff approvals. Slash commands switch models, inspect sessions, compress context, start reviews, manage Missions, configure custom Droids, add skills, inspect hooks, and connect MCP servers.

Factory Desktop exposes the same agent concepts through a native application. It can run against local context and can register the host as a remote-access computer while the app remains active. The desktop and CLI share modes and autonomy concepts, which reduces the behavioral gap between an interactive graphical session and a terminal session.

Bash mode is available from an empty prompt with !, sending commands directly to the shell without model interpretation. That is convenient for checking git state or running a known command between agent turns. The transcript view keeps full tool details available even when the default presentation is compact.

Droid Exec for automation

Droid Exec turns the agent into a non-interactive process. A prompt can come from an argument, a file, or stdin. The command can return plain text, a JSON result, a stream of JSON events, or a JSON-RPC protocol suitable for a custom client. Sessions can be resumed or forked, a working directory can be selected, and tools can be restricted for one run.

droid exec "summarize src/auth"

droid exec --use-spec --auto low "add account deletion"

droid exec -f review-prompt.md -o json

git diff origin/main...HEAD | droid exec "review for regressions"

droid exec --cwd ../service --auto medium "run tests and fix failures"

droid exec --mission --auto high -f migration-mission.md

The default Droid Exec posture is read-only. Low allows safe edits and low-risk commands. Medium covers local development work such as dependency installation, builds, tests, and local commits. High covers pushes, deployment scripts, long-running operations, subagent orchestration, and Missions under the configured policy. If an action exceeds the selected level, current documentation says Droid Exec fails fast with a nonzero exit and no partial changes from that denied request.

For unattended authentication, generate a Factory API key and expose it through FACTORY_API_KEY in the job’s secret store. Avoid placing it in the repository or command history. The process uses exit code 0 for success, 1 for a general runtime error, and 2 for invalid CLI arguments.

Specification Mode: plan before source changes

Specification Mode changes the interaction contract. Droid can explore the repository, integrations, and requirements, then writes a detailed specification and implementation plan. Source changes wait until a person approves. The mode is activated with Shift+Tab interactively or --use-spec in Droid Exec.

• Acceptance criteria define visible success and failure behavior.
• Technical plan names components, dependencies, interfaces, and sequencing.
• File-level outline makes scope and ownership reviewable before a broad patch appears.
• Testing strategy states which focused and integration checks should prove the change.
• Security and compliance considerations surface sensitive data, permissions, or operational effects early.

Approval can keep manual control or choose an autonomy level for implementation. A team can save approved specs as Markdown in a project, user, or custom .factory/docs directory. This turns the plan into an artifact that can be reviewed in git, referenced by a later session, or sent to a remote execution target.

Autonomy and permissions

Droid separates the interaction mode from the autonomy level. Normal Mode and Specification Mode control whether the agent is executing or planning. Off, Low, Medium, and High define the maximum risk of actions that can proceed without a prompt. A user can cycle autonomy with Ctrl+L; an organization can set a default and cap the maximum.

The maximum level is only one control. Command allowlists and denylists, MCP restrictions, sandbox settings, hooks, scoped credentials, and organization policy can narrow capabilities further. A tool restriction on a single Droid Exec invocation is useful for jobs that only need repository reads or a known patch interface.

The --skip-permissions-unsafe flag bypasses permission checks. The name is intentionally explicit. It belongs only in an environment designed to be destroyed after the run, with credentials and network access limited outside the agent process. A normal developer checkout is not that environment.

Models, context, and extensions

Droid can use different supported models and can choose a separate model or reasoning effort for Specification Mode. Factory enterprise documentation describes direct providers, Bedrock, Vertex, Azure OpenAI, gateways, approved custom models, and on-premises endpoints. Administrators can define required models and restrict which providers, endpoints, and personal keys are permitted.

Repository context can come from files, AGENTS.md, Factory settings, skills, custom Droids, plugins, MCP servers, and platform integrations. A ticket link or design document can be resolved through an approved integration. Durable organization and repository instructions help the agent follow conventions across sessions. Each added source consumes attention and expands the trust boundary.

Keep the base context short and enforce rules close to the capability. A style preference can live in instructions. A forbidden production command belongs in a deny rule or hook. A secret boundary belongs in credentials and network policy. Prompts are guidance; capabilities are controls.

Droid Computers and remote work

Droid Computers give the agent persistent machines it can revisit. Factory-managed computers are provisioned by the platform. Bring Your Own Machine registers an existing VPS, workstation, cloud VM, or on-premises server. Both retain packages, files, running services, and configuration across sessions.

The CLI can list computers, register or remove the current host, open an SSH tunnel, and forward TCP ports through the relay. A managed computer can wake before a connection. VS Code Remote SSH can use droid computer ssh as a proxy, which makes the same persistent target available for manual inspection beside agent work.

• Use persistence for large dependency trees, integration services, prepared datasets, or long background tasks.
• Use customer-owned computers when the machine and network boundary should remain under company operation.
• Use managed computers when fast provisioning and low infrastructure work matter more.
• Reset deliberately because stale branches, services, caches, databases, and credentials survive into later sessions.

A persistent computer is a production-like asset even when it only builds code. Patch it, monitor it, scope its credentials, control outbound access, rotate secrets, and define who can target it. The agent should never be the only operator capable of explaining the state.

Custom Droids and Missions

Custom Droids are specialized subagents with their own instructions, model, and tool set. A frontend reviewer, migration worker, SQL specialist, or release-note writer can encapsulate a repeated role. They can be invoked from a parent session and inherit or receive a configured autonomy level, capped by organization policy. In Specification Mode they remain read-only.

Missions coordinate a larger goal across workers and validators. Droid creates a plan, delegates milestones, tracks progress, and validates results. Headless Mission flags can select worker and validator models plus reasoning effort independently. The arrangement can reduce time for decomposable work and increase the number of assumptions running concurrently.

Missions require High autonomy or the unsafe permission bypass. Use High in an isolated worktree or dedicated environment with scoped credentials. Reserve the bypass for disposable containers or virtual machines. Plan file ownership, integration order, model budget, stop conditions, and human checkpoints before launching a large Mission.

The specification-to-PR workflow

Droid can shorten the distance between a specification and a pull request because one session owns context gathering, implementation, tests, and delivery. The phrase one prompt to PR describes the start and end of that trajectory. The work between them remains visible and should remain reviewable.

A complete handoff should identify the branch, base commit, files changed, checks run, checks skipped, environment assumptions, remaining risks, and any generated or migrated data. That record lets a reviewer judge the result without replaying the full transcript. It also makes a failed Droid session useful: the next attempt can begin from evidence instead of repeating the same exploration. Small, explicit handoffs also make later audits much cheaper.

Questions people ask

Keep reading