Delegate the work that
happens on every push.
Droid Exec is Factory's headless mode for CI/CD. Wire it into any GitHub Action, GitLab pipeline, or cron job to review PRs, refresh docs, fix lint, sweep for vulnerabilities - with tiered autonomy and clean exit codes you can trust in a pipeline.
Agents, built for pipelines.
Not an interactive session - a predictable, scriptable task runner. Fail-fast exits, explicit permissions, and output formats your automation can parse.
Non-interactive
One-shot task runner that writes to stdout / stderr. Designed for CI/CD and shell scripting.
Secure by default
Read-only by default. Mutations require explicit opt-in via tiered autonomy levels.
Composable
Pipe, xargs, background jobs, matrix jobs. Agent-shaped Unix tool.
Clean output
text, json, and stream-jsonrpc output formats with structured artifacts.
Pick exactly how much power the agent gets for this job.
Each tier is a hard ceiling on what the agent can do. If the task needs something out of reach, Droid exits non-zero with a clear message - no partial changes, no surprises.
defaultRead-only
Reads files and logs, runs git status / log / diff, lists directories, gathers info. No file or system modifications.
Safe review of planned changes; analysis; audits.
--auto lowFile operations
Adds file create / edit in project directories. No system modifications or package installs.
Docs updates, formatting, comment passes, codegen into the repo.
--auto mediumDevelopment
Adds trusted package installs, builds, network requests, and local git operations (commit, checkout, pull). No git push. No sudo.
Dependency updates, local test runs, repo maintenance tasks.
--auto highProduction
Adds git push, curl | bash, firewall changes, and production deploys. Still blocks sudo rm -rf / and system-wide changes.
CI/CD pipelines, automated deploys, end-to-end automation.
--skip-permissions-unsafe
Dangerous: bypasses every check and cannot be combined with --auto flags. Only use in fully isolated, disposable environments - ephemeral Docker containers, throwaway VMs, sandboxed runners.
Twelve starting points. Each one is a Droid on a schedule.
Every recipe is backed by a published workflow in the Factory cookbooks. Clone one, tune the prompt, and you have an agent on your pipeline by lunch.
Automated code review
PR reviews with inline comments. P0-P3 severity, deep or shallow depth, custom per-repo guidelines.
Automated wiki refresh
/install-wiki scaffolds a CI job that regenerates your wiki on every push to the default branch.
Security review
STRIDE, OWASP, OWASP LLM, and supply-chain checks on every PR, plus scheduled full-repo audits.
Documentation sync
Keep READMEs, JSDoc, and API references in sync with code changes on a nightly cron.
Lint autofix
Fix ESLint violations across the whole codebase in parallel, opening a PR with the results.
Import organization
Normalize and organize imports across every module, monorepo-safe.
Error message refactors
Make error messages consistent, descriptive, and actionable across services.
Dependency + secret scanner
Weekly cron job: secret sweep, CVE audit, dependency bumps, auto-opens PR with the fixes.
Daily docs + tests
Nightly job that updates docstrings and writes missing unit tests based on the last 7 days of diffs.
License header enforcer
Ensure every source file starts with the expected license header; add or fix where missing.
API contract drift
Compare OpenAPI operations to your TypeScript clients and report any drift between them.
Matrix monorepo analysis
One module per runner via GitHub Actions matrix. Aggregate results into a single PR.
Automation for what happens inside a session.
Hooks are user-defined shell commands that run at lifecycle events inside a Droid session. Turn policy into executable code: formatting on save, sensitive-file protection, custom notifications, auditing.
Auto-format after edits
Run prettier on TypeScript files and gofmt on Go files after every file edit. PostToolUse + Create | Edit | ApplyPatch matcher.
Protect sensitive files
Block edits to .env, package-lock.json, or anything under .git/ with a PreToolUse hook that exits non-zero.
Custom notifications
Trigger desktop alerts, sounds, or Slack messages when the agent is awaiting input. Hook into Notification events.
Works like any Unix tool. Compose freely.
Pipe into it, xargs over it, parallelize with job control, and drop it into any CI matrix. --cwd scopes execution inside monorepos; --output-format json makes results parseable.
Parallel fan-out
Refactor every TypeScript file in the repo, four at a time.
find src -name "*.ts" -print0 | \
xargs -0 -P 4 -I {} \
droid exec --auto low \
"Refactor file: {} to use modern TS patterns"Monorepo matrix
Run a focused agent per module on a GitHub Actions matrix.
strategy:
matrix:
module:
- src/components
- src/services
- src/hooks
steps:
- run: droid exec --cwd "${{ matrix.module }}" \
--auto low \
"Identify unused exports; write cleanup-report.md"Chunked PR diffs
Break a huge PR into 50-file chunks, review each independently.
git diff --name-only origin/main...HEAD | \
split -l 50 - /tmp/files_
for f in /tmp/files_*; do
list=$(tr '\n' ' ' < "$f")
droid exec --auto low \
"Review: $list; write review.json"
doneThree output formats. One fail-fast contract.
Exit 0 means success. Non-zero means permission violation, tool error, or the agent couldn't meet the objective - all treated as failed in CI. No partial changes when autonomy runs out.
text
defaultHuman-readable output for direct consumption or build logs.
json
--output-format jsonStructured result with duration, turn count, exit status, and session id. Parse it in a script.
stream-jsonrpc
--input-format stream-jsonrpcLong-lived JSON-RPC subprocess. Build custom UX, policy layers, or orchestrators on top of raw events.
Ship Droid into your own product.
When the CLI isn't enough, drop down to the SDKs. Stream turns, handle permissions, fork sessions, bridge events to your own message bus, or build a fully custom UX on top of Droid.
@factory/droid-sdk
TypeScript SDK
Node apps, streaming, multi-turn sessions, structured output, permissions, MCP tools. Built on the JSON-RPC transport.
droid-sdk
Python SDK
asyncio apps, streaming, direct client control, typed event handling, permissions. First-class for data and ML pipelines.
Automations your security team can sign off.
Every Droid Exec run inherits your org policies, streams audit telemetry, and respects gateway / model allow-lists. Deploy in cloud, hybrid, or fully airgapped.
LLM safety + agent controls
Risk classification, allow/deny policies, Droid Shield, hooks, sandboxes.
Hierarchical settings
Org > project > folder > user control over models, tools, policies, telemetry.
Telemetry export
OpenTelemetry metrics streamed to your own OTLP collector.
GitHub integration security
Architecture, data flows, and controls for the Factory Droid GitHub App.
Install the CLI. Pick a recipe. Replace a weekly chore with a cron.
curl -fsSL https://app.factory.ai/cli | sh
export FACTORY_API_KEY=fk-...
droid exec --auto low "summarize this repo"
