Configure Factory Droid CLI: AGENTS.md, settings.json, autonomy, custom droids and MCP

Factory lists four install methods. On Linux, make sure xdg-utils is installed. After installing, open your project folder and run droid, then sign in through your browser if prompted.

# macOS / Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# npm
npm install -g droid

# Start an interactive session
cd /path/to/your/project
droid

Add an AGENTS.md file at the repository root with exact install, test, lint and build commands, conventions and safety rules, and commit it. Droid searches from the current directory up to the git root, checking each level and its .factory, .agents and .agent folders, plus personal folders such as ~/.factory. It also reads compatible names such as CLAUDE.md. Nested files refine the root file, and project files override personal defaults.

Personal settings live in ~/.factory/settings.json on macOS and Linux, or %USERPROFILE%\.factory\settings.json on Windows. The file is created with defaults the first time you run droid, and you can edit it interactively with the /settings command. A settings.local.json file next to settings.json, at user or project level, merges on top for machine specific overrides.

{
  "model": "YOUR_MODEL_ID",
  "reasoningEffort": "medium",
  "sessionDefaultSettings": {
    "interactionMode": "auto",
    "autonomyLevel": "low"
  },
  "cloudSessionSync": true,
  "diffMode": "github",
  "includeCoAuthoredByDroid": true,
  "enableDroidShield": true
}

Autonomy Level sets the highest risk work Droid can run without asking. The levels are Off, Low, Medium and High. In the interactive CLI, press Ctrl+L to cycle levels, or set sessionDefaultSettings.autonomyLevel as the default. Permission rules, safety checks and organization limits still apply at every level.

• No flag: droid exec is read only, suited to analysis, planning and reviews.
• --auto low: low risk file creation and edits, such as docs, formatting and comments.
• --auto medium: adds local development work such as package installs, builds, tests, git commit, git checkout and git pull, but not git push.
• --auto high: adds remote writes, deployments and migrations, subject to remaining hard safety checks.
• --skip-permissions-unsafe skips all prompts, cannot be combined with --auto, and is meant only for disposable environments.

droid exec "summarize the architecture of this repo"
droid exec --auto low "add JSDoc comments to all exported functions"
droid exec --auto medium "install deps, run tests, and fix failing checks"
droid exec --auto high "fix the bug, run tests, commit, and push the branch"

If a requested action is above the current level, droid exec stops with an error and a non zero exit code instead of making partial changes.

A custom droid is a Markdown file with YAML frontmatter that runs as a subagent in a fresh context window. Project droids go in .factory/droids in your repo and personal droids go in ~/.factory/droids. A project droid wins when names clash. You can also create one with the /droids menu.

---
name: code-reviewer
description: Focused reviewer that checks diffs for correctness risks
model: inherit
tools: read-only
---

You are the team's senior reviewer. Examine the diff the parent agent shares and
flag correctness, security, and migration risks.

Add MCP servers with droid mcp add, which always writes to your user config at ~/.factory/mcp.json, or open the /mcp manager inside Droid. A project level .factory/mcp.json can be committed for the team, but never put secrets in it. Droid reloads automatically when an mcp.json file changes.

# Remote HTTP server
droid mcp add linear https://mcp.linear.app/mcp --type http

# Local stdio server with an environment variable
droid mcp add airtable "npx -y airtable-mcp-server" --env AIRTABLE_API_KEY=YOUR_VALUE

# List and remove
droid mcp list
droid mcp remove YOUR_SERVER_NAME

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