Droid

CLI

Factory

Factory's AI coding agent for the terminal — interactive TUI and headless droid exec, with MCP, hooks, skills, and custom subagents.

Website Docs

MCP

Supported

MCP servers in mcp.json at user, folder, and project level, managed via the /mcp interactive UI, `droid mcp add`, or a built-in registry of 40+ servers.

Verified 2026-07-12Docs

Transportsstdiossehttp

Authoauthheadersenv

Config files

Path	Scope	Format	Key
`~/.factory/mcp.json` Personal servers, available in all projects. Servers added via droid mcp add or the registry go here.	Global	json	mcpServers
`.factory/mcp.json` Shared team servers committed to the repo; also read from .factory/mcp.json in ancestor directories (folder scope). Never put secrets in project config.	Project	json	mcpServers

Fields

Field	Type	Description
`type`	string	Server transport. May be omitted for stdio servers.
`command`	string	Executable to run (stdio servers).
`args`	string[]	Command-line arguments (stdio servers).
`env`	record<string, string>	Environment variables (stdio servers). Supports ${VAR} expansion.
`url`	string	HTTP/HTTPS endpoint (http and sse servers).
`headers`	record<string, string>	HTTP headers for authentication (http and sse servers).
`oauth`	object \| false	OAuth overrides (scopes, clientId/clientSecret + authorizationServerIssuer, clientMetadataUrl, tokenEndpointAuthMethod, callbackPort), or false to disable OAuth.
`disabled`	boolean	Temporarily disable the server. Default false.
`enabledTools`	string[]	Allowlist of tool names to load; takes precedence over disabledTools.
`disabledTools`	string[]	Blocklist of tool names to exclude; filtered tools never consume context tokens.
`timeoutMs`	number	Per-server MCP tool call timeout override; falls back to mcp.callTimeoutMs in settings.json.

Capabilities

ToolsSupported

Examples

mcp.json

{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "disabled": false
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "disabled": false
    }
  }
}

Add servers via CLI

droid mcp add sentry https://mcp.sentry.dev/mcp --type http
droid mcp add airtable "npx -y airtable-mcp-server" --env AIRTABLE_API_KEY=your_key

•Layering: user config takes priority, then folder-level (.factory/mcp.json in any ancestor directory), then project config.
•Enabling/disabling a project-defined server saves a copy to user config; project servers can only be removed by editing .factory/mcp.json directly.
•${VAR} and ${VAR:-default} expansion is supported in command, args, env, url, and headers — expansion happens in memory, the file is never rewritten.
•OAuth works with zero configuration for most remote servers (Dynamic Client Registration / CIMD); tokens are stored in the system keyring globally, not per-project.
•sse is the legacy HTTP+SSE transport; prefer http (Streamable HTTP).
•Custom droids (subagents) can scope themselves to specific servers via the mcpServers frontmatter field.
•Enterprise: mcpPolicy allowlist and mcpAutonomyUrlOverrides are enforced through org-managed settings.

Skills

Supported

SKILL.md skills in .factory/skills/ that both the user (/skill-name) and the Droid can invoke, with frontmatter to control invocation and optional supporting files.

Verified 2026-07-12Docs

Invoke/skill-nameautomatic

Config files

Path	Scope	Format	Key
`.factory/skills/<name>/SKILL.md` Project skills shared with teammates, checked into git. Per-subproject .factory folders work in monorepos.	Project	markdown	—
`~/.factory/skills/<name>/SKILL.md` Personal skills that follow you across projects.	Global	markdown	—
`.agent/skills/<name>/SKILL.md` Compatibility path for .agent folder conventions.	Project	markdown	—

Fields

Field	Type	Description
`name`	string	Display name; defaults to the directory name. Lowercase letters, numbers, and hyphens only.
`description`	string	What the skill does and when to use it. The Droid uses this to decide when to apply the skill. Recommended.
`user-invocable`	boolean	Set false to hide from the / slash menu (Droid-only background knowledge). Default true.
`disable-model-invocation`	boolean	Set true to prevent the Droid from loading the skill automatically (user-only workflows like /deploy). Default false.

Examples

SKILL.md

---
name: summarize-diff
description: Summarize the staged git diff in 3-5 bullets. Use when the user asks for a summary of pending changes.
---

# Summarize Diff

## Instructions

1. Run `git diff --staged`.
2. Summarize the changes in 3-5 bullets, focusing on user-visible behavior.
3. Call out any migrations, risky areas, or tests that should be run.

•Custom slash commands have been merged into skills: .factory/commands/review.md and .factory/skills/review/SKILL.md both create /review.
•The skill file can be SKILL.md or skill.mdx; supporting files (scripts, schemas, checklists) live in the same directory.
•disable-model-invocation: true makes a skill user-only (e.g. /deploy); user-invocable: false makes it Droid-only background knowledge.
•<repo>/.agent/skills/ is also discovered for compatibility with .agent folder conventions.
•Restart droid (or rescan) after adding skills so they are discovered.

Rules

Supported

AGENTS.md files at repo root, subdirectories, and a personal override in ~/.factory/AGENTS.md brief the agent on build/test commands, architecture, and conventions.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`AGENTS.md` Repo root and sub-folders; closest file to the edited code wins.	Project	markdown	—
`~/.factory/AGENTS.md` Personal override read when no project file matches.	Global	markdown	—

Examples

AGENTS.md skeleton

# Build & Test

- Build: `npm run build`
- Test: `npm run test -- --runInBand`

# Conventions

- All backend code in `packages/api/src`
- Use `zod` for request validation

•Discovery order (first match wins): ./AGENTS.md in the cwd, nearest parent up to the repo root, AGENTS.md in sub-folders the agent is working inside, then the personal override ~/.factory/AGENTS.md.
•Multiple files can coexist; the file closer to the code being edited takes precedence.
•Plain Markdown; top-level headings act as semantic sections (Build & Test, Architecture Overview, Security, Git Workflows, Conventions & Patterns).
•Factory recommends keeping it under ~150 lines with concrete backtick-wrapped commands.
•The legacy .droid.yaml project config is superseded by AGENTS.md plus .factory/ settings, MCP, hooks, and skills.

Hooks

Supported

Shell-command hooks in hooks.json at user, project, plugin, and org-managed scope, with matchers, JSON stdin input, and decision control via exit codes or structured JSON output.

Verified 2026-07-12Docs

EventsPreToolUsePostToolUseUserPromptSubmitNotificationStopSubagentStopPreCompactSessionStartSessionEnd

Config files

Path	Scope	Format	Key
`.factory/hooks.json` Committed to share with the team.	Project	json	hooks
`~/.factory/hooks.json` Applies to all projects.	Global	json	hooks
`~/.factory/settings.json` Fallback location when hooks.json is absent (same for project settings.json). Org-managed policy hooks are delivered via managed settings.	Global	json	hooks

Fields

Field	Type	Description
`matcher`	string	Case-sensitive pattern matched against tool names for PreToolUse/PostToolUse (exact, regex, or *). Omit for events without matchers.
`hooks[].type`*	"command"	Hook handler type. Currently only command is supported.
`hooks[].command`*	string	Bash command to execute; receives event JSON on stdin. Can use $FACTORY_PROJECT_DIR.
`hooks[].timeout`	number	Per-command timeout in seconds (default 60).

Examples

Style check after file edits

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Create|Edit|ApplyPatch",
        "hooks": [
          {
            "type": "command",
            "command": "\"$FACTORY_PROJECT_DIR\"/.factory/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

•If hooks.json is absent, Droid falls back to hooks declared under the hooks key in the matching settings.json; the older .factory/hooks/hooks.json location keeps working and is migrated on save.
•matcher applies to PreToolUse/PostToolUse and matches tool names (exact, regex like Edit|Create, or * for all); PreCompact matches manual/auto, SessionStart matches startup/resume/clear/compact.
•Hooks receive JSON on stdin (session_id, transcript_path, cwd, permission_mode, event-specific fields). Exit code 2 blocks (per-event behavior); JSON stdout enables permissionDecision allow/deny/ask, updatedInput, additionalContext, continue/stopReason, and suppressOutput.
•PreToolUse hooks can modify tool inputs via hookSpecificOutput.updatedInput before execution.
•Use $FACTORY_PROJECT_DIR for project-relative scripts; hooks run in parallel with a 60s default timeout, configurable per command.
•Manage via the /hooks menu; disable all hooks globally with the hooksDisabled setting. Direct file edits require review in /hooks before applying (session snapshot).
•MCP tools are matchable with the mcp__<server>__<tool> naming pattern.
•Org-managed hooks are always loaded; allowManagedHooksOnly ignores user/project hooks entirely.

Commands

Supported

Custom slash commands as Markdown prompts or shebang executables in .factory/commands/, now merged into skills (which offer the same /command plus more features).

Verified 2026-07-12Docs

Invoke/command-name

Config files

Path	Scope	Format	Key
`.factory/commands/<name>.md` Project commands shared with teammates; executables with a shebang also register.	Project	markdown	—
`~/.factory/commands/<name>.md` Personal cross-project shortcuts, always scanned.	Global	markdown	—

Fields

Field	Type	Description
`description`	string	Overrides the generated summary shown in slash suggestions.
`argument-hint`	string	Appends inline usage hints (e.g. /code-review <branch-name>).
`allowed-tools`	string	Reserved for future use. Safe to omit.

Examples

Markdown command

---
description: Send a code review checklist
argument-hint: <branch-name>
---

Please review `$ARGUMENTS` and summarize any merge blockers, test gaps, and risky areas.

- Highlight security or performance concerns
- Suggest follow-up tasks with owners

Executable command (smoke.sh registers as /smoke)

#!/usr/bin/env bash
set -euo pipefail

target=${1:-"src"}
npm run lint -- "$target"
npm test -- --runTestsByPath "$target"

•Slash commands are merged into skills: .factory/commands/review.md and .factory/skills/review/SKILL.md both create /review. Existing commands keep working; Factory recommends skills for new commands.
•Only Markdown (*.md) files and files with a leading shebang (#!) are registered; filenames are slugged (Code Review.mdx becomes /code-review). Nested folders are ignored.
•Workspace commands override personal commands with the same slug.
•$ARGUMENTS expands to everything typed after the command name in Markdown commands; positional $1/$2 placeholders are not supported in Markdown (executables receive them as script arguments).
•Executable stdout/stderr (up to 64 KB) plus the script contents are posted back to the chat transcript; scripts run from the cwd and inherit your environment.
•Run /commands to browse, reload (R), or import (I) commands from .agents or .claude directories.

Settings

Supported

settings.json in .factory/ folders controls model, autonomy, command allow/deny/block lists, hooks toggle, and more, with local overrides and enterprise org-managed settings.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`~/.factory/settings.json` User settings (Windows: %USERPROFILE%\.factory\settings.json). settings.local.json merges on top.	Global	json	—
`.factory/settings.json` Project-level settings; .factory/settings.local.json provides gitignored local overrides.	Project	json	—

Fields

Field	Type	Description
`model`	string	Default AI model used by droid (any available model ID).
`reasoningEffort`	string	How much structured thinking the model performs; availability depends on the model.
`sessionDefaultSettings.interactionMode`	string	Whether new sessions start in Auto or Spec Mode. Default auto.
`sessionDefaultSettings.autonomyLevel`	string	Default Autonomy Level for new sessions. Default off (manual approvals).
`commandAllowlist`	string[]	Commands treated as safe and run without extra confirmation.
`commandDenylist`	string[]	Commands that always require confirmation; can still run if explicitly approved.
`commandBlocklist`	string[]	Commands that can never run — no prompt, no approval path, enforced even under full autonomy.
`hooksDisabled`	boolean	Globally disable all hooks execution without removing configurations. Default false.
`includeCoAuthoredByDroid`	boolean	Append the Droid co-author trailer to commits. Default true.
`enableDroidShield`	boolean	Enable secret scanning and git guardrails. Default true.
`cloudSessionSync`	boolean	Mirror CLI sessions to Factory web. Default true.
`diffMode`	string	How code changes are displayed. Default github.
`customModels`	array	Custom model configurations for BYOK (bring your own key).
`mcp.callTimeoutMs`	number	Global timeout for MCP tool calls; overridden per-server by timeoutMs in mcp.json.
`subagentAutonomyLevel`	string	Autonomy Level applied to subagents spawned by the Task tool. Default inherit.
`statusLine`	object	Custom status line: { command, padding?, maxRows? }; the command's stdout renders above the input.
`maxAutonomyLevel`	string	Enterprise: maximum Autonomy Level any session may use; user selections are clamped.

Examples

settings.json

{
  "model": "claude-opus-4-7",
  "reasoningEffort": "low",
  "diffMode": "github",
  "cloudSessionSync": true,
  "commandAllowlist": ["ls", "pwd", "dir"],
  "commandBlocklist": ["shutdown", "mkfs"]
}

•Configure interactively with /settings; changes are saved to the settings file immediately.
•settings.local.json alongside settings.json at any level merges on top of it — add it to .gitignore for machine-specific preferences.
•Hierarchy: org-managed settings, then user, project, and local overrides (see Enterprise Hierarchical Settings docs).
•commandBlocklist can never be bypassed — not even with full autonomy or --skip-permissions-unsafe — and resolves the actual program invoked; commandDenylist requires confirmation; commandAllowlist runs without confirmation.
•Enterprise settings (maxAutonomyLevel, modelPolicy, mcpPolicy, networkPolicy, sandbox, ...) are pushed via managed settings and cannot be overridden by users.