# Droid Factory's AI coding agent for the terminal — interactive TUI and headless droid exec, with MCP, hooks, skills, and custom subagents. Schema: 1.0 · Data: ee5de863c30bdbe4fe7dd3e07c7e22ea9bf4ab2248dbc7c35cdbf60bc28be1db ## Configuration ### MCP Status: 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. - global: `~/.factory/mcp.json` (json) — key: mcpServers — Personal servers, available in all projects. Servers added via droid mcp add or the registry go here. - project: `.factory/mcp.json` (json) — key: mcpServers — Shared team servers committed to the repo; also read from .factory/mcp.json in ancestor directories (folder scope). Never put secrets in project config. - `type`: string — Server transport. May be omitted for stdio servers. Values: stdio, http, sse - `command`: string — Executable to run (stdio servers). - `args`: string[] — Command-line arguments (stdio servers). - `env`: record — Environment variables (stdio servers). Supports ${VAR} expansion. - `url`: string — HTTP/HTTPS endpoint (http and sse servers). - `headers`: record — 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. - transports: stdio, sse, http - auth: oauth, headers, env - Tools: supported — View each server's tools via /mcp; filter with enabledTools/disabledTools. - 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. mcp.json ```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 ```bash 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 ``` Source: https://docs.factory.ai/cli/configuration/mcp Checked: 2026-07-12 ### Skills Status: 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. - project: `.factory/skills//SKILL.md` (markdown) — Project skills shared with teammates, checked into git. Per-subproject .factory folders work in monorepos. - global: `~/.factory/skills//SKILL.md` (markdown) — Personal skills that follow you across projects. - project: `.agent/skills//SKILL.md` (markdown) — Compatibility path for .agent folder conventions. - `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. - invocation: /skill-name, automatic - 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. - /.agent/skills/ is also discovered for compatibility with .agent folder conventions. - Restart droid (or rescan) after adding skills so they are discovered. SKILL.md ```markdown --- 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. ``` Source: https://docs.factory.ai/cli/configuration/skills Checked: 2026-07-12 ### Rules Status: 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. - project: `AGENTS.md` (markdown) — Repo root and sub-folders; closest file to the edited code wins. - global: `~/.factory/AGENTS.md` (markdown) — Personal override read when no project file matches. - 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. AGENTS.md skeleton ```markdown # Build & Test - Build: `npm run build` - Test: `npm run test -- --runInBand` # Conventions - All backend code in `packages/api/src` - Use `zod` for request validation ``` Source: https://docs.factory.ai/cli/configuration/agents-md Checked: 2026-07-12 ### Hooks Status: 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. - project: `.factory/hooks.json` (json) — key: hooks — Committed to share with the team. - global: `~/.factory/hooks.json` (json) — key: hooks — Applies to all projects. - global: `~/.factory/settings.json` (json) — key: hooks — Fallback location when hooks.json is absent (same for project settings.json). Org-managed policy hooks are delivered via managed settings. - `matcher`: string — Case-sensitive pattern matched against tool names for PreToolUse/PostToolUse (exact, regex, or *). Omit for events without matchers. - `hooks[].type`: "command" (required) — Hook handler type. Currently only command is supported. - `hooks[].command`: string (required) — Bash command to execute; receives event JSON on stdin. Can use $FACTORY_PROJECT_DIR. - `hooks[].timeout`: number — Per-command timeout in seconds (default 60). - events: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart, SessionEnd - 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____ naming pattern. - Org-managed hooks are always loaded; allowManagedHooksOnly ignores user/project hooks entirely. Style check after file edits ```json { "hooks": { "PostToolUse": [ { "matcher": "Create|Edit|ApplyPatch", "hooks": [ { "type": "command", "command": "\"$FACTORY_PROJECT_DIR\"/.factory/hooks/check-style.sh" } ] } ] } } ``` Source: https://docs.factory.ai/reference/hooks-reference Checked: 2026-07-12 ### Commands Status: 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). - project: `.factory/commands/.md` (markdown) — Project commands shared with teammates; executables with a shebang also register. - global: `~/.factory/commands/.md` (markdown) — Personal cross-project shortcuts, always scanned. - `description`: string — Overrides the generated summary shown in slash suggestions. - `argument-hint`: string — Appends inline usage hints (e.g. /code-review ). - `allowed-tools`: string — Reserved for future use. Safe to omit. - invocation: /command-name - 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. Markdown command ```markdown --- description: Send a code review checklist argument-hint: --- 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) ```bash #!/usr/bin/env bash set -euo pipefail target=${1:-"src"} npm run lint -- "$target" npm test -- --runTestsByPath "$target" ``` Source: https://docs.factory.ai/cli/configuration/custom-slash-commands Checked: 2026-07-12 ### Settings Status: 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. - global: `~/.factory/settings.json` (json) — User settings (Windows: %USERPROFILE%\.factory\settings.json). settings.local.json merges on top. - project: `.factory/settings.json` (json) — Project-level settings; .factory/settings.local.json provides gitignored local overrides. - `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. Values: off, none, low, medium, high - `sessionDefaultSettings.interactionMode`: string — Whether new sessions start in Auto or Spec Mode. Default auto. Values: auto, spec - `sessionDefaultSettings.autonomyLevel`: string — Default Autonomy Level for new sessions. Default off (manual approvals). Values: off, low, medium, high - `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. Values: github, unified - `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. Values: inherit, off, low, medium, high - `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. Values: off, low, medium, high - 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. settings.json ```json { "model": "claude-opus-4-7", "reasoningEffort": "low", "diffMode": "github", "cloudSessionSync": true, "commandAllowlist": ["ls", "pwd", "dir"], "commandBlocklist": ["shutdown", "mkfs"] } ``` Source: https://docs.factory.ai/cli/configuration/settings Checked: 2026-07-12 ## Search, browser & identification Not researched. Unknown does not mean unsupported.