Factory Droid Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Factory Droid Engine is a specialized AI integration within the Morty platform that leverages the droid CLI to perform autonomous coding tasks. It acts as one of several pluggable AI backends, allowing Morty to delegate complex implementation steps, testing, and linting to Factory’s autonomous agents. Sources: README.md:104, cli/src/engines/droid.ts:11
Within the Morty ecosystem, the Droid engine is invoked via the --droid flag. It is designed to work in both single-task (brownfield) mode and PRD-driven task list mode, supporting both sequential and parallel execution workflows. Sources: morty.sh:588, cli/src/cli/args.ts:74
Architecture and Integration
The Droid engine is implemented as a class extending BaseAIEngine. It communicates with the Factory Droid service by executing shell commands through the droid CLI. This integration specifically utilizes the exec command with the stream-json output format to capture real-time updates and final results. Sources: cli/src/engines/droid.ts:11-16
Execution Workflow
When Morty triggers the Droid engine, it constructs a command-line request that includes:
- Command:
droid exec - Format:
--output-format stream-json - Autonomy Level:
--auto medium - Prompt: The specific task description and context rules.
The engine supports both standard execution and streaming execution, the latter of which allows for real-time progress monitoring through step detection. Sources: cli/src/engines/droid.ts:19-25, cli/src/engines/droid.ts:68-74
Logic and Data Handling
The engine processes JSON-formatted output from the Droid CLI to determine the status of a task and extract the final response.
Output Parsing
Droid provides a completion event type in its JSON stream. The engine listens for this event to capture the finalText and durationMs. Unlike other engines like Claude or OpenCode, Droid does not expose token counts in exec mode; instead, it provides duration-based metrics. Sources: cli/src/engines/droid.ts:40-54, morty.sh:1037-1043
Engine Configuration Options
The Droid engine supports specific runtime overrides through Morty's CLI arguments.
| Parameter | Command Flag | Description |
|---|---|---|
| Model Override | --model <name> | Passes a specific model name to the droid exec command. |
| Autonomy | N/A | Hardcoded to medium for balanced autonomous development. |
| Output Format | N/A | Hardcoded to stream-json for machine readability. |
Sources: cli/src/engines/droid.ts:20-23, morty.sh:1022-1025
Usage in Parallel Execution
When Morty runs in parallel mode (--parallel), the Droid engine is instantiated within isolated git worktrees. Each parallel agent runs a separate instance of the droid CLI, ensuring that file system changes made by the AI are contained within the specific task's workspace. Sources: cli/src/execution/parallel.ts:68-80, morty.sh:1115-1120
Parallel Execution Flow
- Worktree Creation: A new git worktree is created for the task.
- Isolation: The
droid execcommand is run with theworkDirset to the worktree path. - Result Aggregation: The
durationMsprovided by Droid is tracked as a cost metric in the final summary.
Cost and Performance Tracking
Because Factory Droid does not expose standard token usage in its execution mode, Morty tracks "cost" as a duration string. This information is passed back in the AIResult object and eventually displayed in the session summary. Sources: cli/src/engines/droid.ts:62, morty.sh:1502-1510
- Metric Format:
duration:<milliseconds> - Summary Handling: The CLI parses this string to display the total API time used across all tasks.
Sources: morty.sh:1359-1363, cli/src/engines/droid.ts:62
Summary
The Factory Droid Engine provides a robust, autonomous backend for Morty by wrapping the droid CLI. It supports the full suite of Morty features, including rules injection, boundary enforcement, and parallel execution, while providing unique duration-based performance tracking. Its implementation via stream-json ensures that Morty can provide real-time feedback to the user during long-running autonomous implementation tasks. Sources: cli/src/engines/droid.ts:11-105, README.md:213