### Droid Exec Quickstart Examples

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/droid-exec/overview.mdx

Execute commands directly, from a file, via pipe, or continue a session.

```bash
droid exec "analyze code quality"
```

```bash
droid exec "fix the bug in src/main.js" --auto low
```

```bash
droid exec -f prompt.md
```

```bash
echo "summarize repo structure" | droid exec
```

```bash
droid exec --session-id <session-id> "continue with next steps"
```

--------------------------------

### Clone and Run Droid Exec Example

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/building/droid-exec-tutorial.mdx

Clones the official Droid Exec examples repository, installs dependencies, and starts the development server for a 'chat with repo' feature.

```bash
git clone https://github.com/Factory-AI/examples.git
cd examples/droid-chat
bun i
bun dev
```

--------------------------------

### Install Bun

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/building/droid-exec-tutorial.mdx

Installs the Bun JavaScript runtime. This is a prerequisite for running the example application.

```bash
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Verify Analysis Setup and Execution

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/skills/ai-data-analyst.mdx

Commands to set up a virtual environment, install dependencies, run the analysis script, and check generated outputs.

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Run analysis script
python analysis.py

# Check outputs generated
ls -lh outputs/
```

--------------------------------

### List Readiness Reports Example

Source: https://github.com/factory-ai/factory/blob/main/docs/reference/readiness-reports-api.mdx

This example shows how to retrieve readiness reports for your organization using the GET /api/organization/maturity-level-reports endpoint. You can filter results using query parameters like 'limit'.

```bash
curl -X GET "https://app.factory.ai/api/organization/maturity-level-reports?limit=10" \
  -H "Authorization: Bearer fk-your-api-key"
```

--------------------------------

### Install Automated QA Skill

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/skills/automated-qa.mdx

Run this command to initiate the installation process for the automated QA skill. It analyzes the codebase and guides through a questionnaire.

```bash
droid
> /install-qa
```

--------------------------------

### Run the AutoWiki Install Command

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/features/wiki/auto-refresh.mdx

Execute the /install-wiki command within the Droid session to initiate the Wiki regeneration setup.

```bash
> /install-wiki
```

--------------------------------

### Python Project Setup Script

Source: https://github.com/factory-ai/factory/blob/main/docs/web/machine-connection/cloud-templates/index.mdx

Install Python dependencies using 'pip' and run tests with 'pytest'. Ensure 'requirements.txt' is present and pytest is installed.

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

pip install -r requirements.txt
pytest -q

```

--------------------------------

### Multi-language Project Setup Script

Source: https://github.com/factory-ai/factory/blob/main/docs/web/machine-connection/cloud-templates/index.mdx

A setup script for projects with both Node.js and Python dependencies. It installs Node.js packages, Python packages, and runs a custom setup script.

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

# Install Node.js dependencies
npm ci

# Install Python dependencies
pip install -r requirements.txt

# Run setup script
bash ./scripts/setup.sh

```

--------------------------------

### Install a plugin from a marketplace

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/configuration/plugins.mdx

Installs a plugin from a registered marketplace. Use `--scope project` to install for the current project, or `user` for all projects. Omit the flag to be prompted.

```bash
droid plugin install droid-control@factory-plugins --scope project
```

--------------------------------

### Node.js (Next.js) Setup Script

Source: https://github.com/factory-ai/factory/blob/main/docs/web/machine-connection/cloud-templates/index.mdx

Use this script to install Node.js dependencies and build a Next.js project. Ensure 'npm ci' and 'npm run build' are appropriate for your project.

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

npm ci
npm run build

```

--------------------------------

### Test Plugin Installation

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/building/building-plugins.mdx

Install your plugin from a local directory to test its functionality. This involves adding it to the marketplace and then installing it.

```bash
droid plugin marketplace add ./my-plugin
droid plugin install my-plugin@my-plugin
```

--------------------------------

### PNPM Monorepo Setup Script

Source: https://github.com/factory-ai/factory/blob/main/docs/web/machine-connection/cloud-templates/index.mdx

This script installs dependencies and builds a PNPM monorepo. Use 'pnpm -w i' for workspace installs and 'pnpm -w build' for building.

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

pnpm -w i
pnpm -w build

```

--------------------------------

### Order Commands by Dependency in Setup Scripts

Source: https://github.com/factory-ai/factory/blob/main/docs/web/machine-connection/cloud-templates/index.mdx

Ensure package installation and build steps are executed before commands that depend on them. Use exact package managers for reproducible builds.

```bash
npm ci && npm run build
```

```bash
pip install -r requirements.txt && pytest -q
```

--------------------------------

### Install Documentation Tools (Go)

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/hooks/documentation-sync.mdx

Installs Go tools for generating API documentation, including Swagger support.

```bash
go install golang.org/x/tools/cmd/godoc@latest
go install github.com/swaggo/swag/cmd/swag@latest  # For Swagger
```

--------------------------------

### Provide Examples for Specific Output Formats

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/power-user/prompt-crafting.mdx

Include example input/output pairs within your prompt to guide Claude towards generating responses in a desired format, especially for error handling or structured data.

```plaintext
<example>
Input: "user not found"
Output: { code: "USER_NOT_FOUND", message: "The specified user does not exist", httpStatus: 404 }
</example>

Now handle these error cases following the same pattern:
- Invalid password
- Account locked
- Session expired
```

--------------------------------

### Install Mintlify CLI

Source: https://github.com/factory-ai/factory/wiki/overview--getting-started

Install the Mintlify CLI globally to enable live preview of documentation changes.

```bash
npm install -g mint
```

--------------------------------

### Implement Strict Error Handling in Setup Scripts

Source: https://github.com/factory-ai/factory/blob/main/docs/web/machine-connection/cloud-templates/index.mdx

Start bash scripts with `#!/usr/bin/env bash` and `set -euo pipefail` to ensure the script stops on the first failure, saving debugging time.

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

--------------------------------

### Feature Development Example

Source: https://github.com/factory-ai/factory/blob/main/docs/web/getting-started/quickstart.mdx

Use this prompt to guide Droid in implementing new features based on existing patterns.

```text
Implement a dark mode toggle following our existing theme patterns
```

--------------------------------

### Install Testing Frameworks

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/hooks/testing-automation.mdx

Install necessary testing frameworks and coverage tools for JavaScript/TypeScript, Python, or Go projects.

```bash
npm install -D jest @testing-library/react vitest
npm install -D @vitest/coverage-v8  # For coverage
```

```bash
pip install pytest pytest-cov
pip install coverage  # For coverage tracking
```

```bash
# go test is built-in
go install github.com/gotestyourself/gotestsum@latest  # Better test output
```

--------------------------------

### Check gofmt installation

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/hooks/auto-formatting.mdx

Verify that gofmt is installed, as it is included with the Go installation.

```bash
# gofmt is included with Go installation
go version
```

--------------------------------

### Clone Droid Exec Example

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/building/droid-exec-tutorial.mdx

Clone the official droid-chat example repository to begin.

```bash
git clone https://github.com/Factory-AI/examples.git
```

--------------------------------

### Install Plugin

Source: https://github.com/factory-ai/factory/blob/main/docs/reference/cli-reference.mdx

Installs a plugin from a specified repository. The alias `droid plugin i` can be used.

```bash
droid plugin install factory/code-review
```

--------------------------------

### Install Documentation Tools (Python)

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/hooks/documentation-sync.mdx

Installs essential Python packages for generating documentation from docstrings.

```bash
pip install sphinx pdoc3 mkdocs
pip install pydoc-markdown  # Markdown docs from docstrings
```

--------------------------------

### Install Documentation Tools (TypeScript/JavaScript)

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/hooks/documentation-sync.mdx

Installs necessary packages for documentation generation in TypeScript/JavaScript projects.

```bash
npm install -D typedoc jsdoc documentation
npm install -D @readme/openapi-parser  # For OpenAPI
```

--------------------------------

### Understand entry points and testing setup

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/getting-started/quickstart.mdx

Prompt droid to explain the main entry points of the project and how testing is configured.

```bash
> where are the main entry points and how is testing set up?
```

--------------------------------

### Preview Changes Locally

Source: https://github.com/factory-ai/factory/wiki/how-to-contribute

Use this command to preview your changes locally before submitting a pull request. Ensure you have followed the setup instructions in 'Getting started'.

```bash
mint dev
```

--------------------------------

### Run Mintlify Development Server

Source: https://github.com/factory-ai/factory/blob/main/docs/README.md

Start the local development server to preview your documentation. Ensure you are in the root directory of your documentation project where 'docs.json' is located.

```bash
mintlify dev
```

--------------------------------

### Make setup-env script executable

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/hooks/session-automation.mdx

Make the setup-env.sh script executable.

```bash
chmod +x .factory/hooks/setup-env.sh
```

--------------------------------

### Set up Nginx with Docker

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/building/droid-vps-setup.mdx

Use Droid to automatically install Docker, configure Nginx, create an HTML file, and run a container to serve a 'Hello World' page on your VPS.

```bash
# In your VPS, with droid running
> Set up Nginx with Docker and serve a hello world page
```

--------------------------------

### Start Interactive REPL with Initial Prompt

Source: https://github.com/factory-ai/factory/blob/main/docs/reference/cli-reference.mdx

Starts the Droid CLI in interactive mode with a pre-defined prompt to guide the initial conversation.

```bash
droid "explain this project"
```

--------------------------------

### Install Remotion Dependencies

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/features/droid-control.mdx

After adding the droid-control plugin, navigate to its remotion directory and install the necessary npm dependencies for video rendering. This is a one-time setup step.

```bash
droid plugin list --scope user
cd <plugin-path>/remotion && npm install
```

--------------------------------

### Start Local Preview with Mint

Source: https://github.com/factory-ai/factory/wiki/how-to-contribute--development-workflow

Use this command to start a local development server for previewing documentation changes. Hot-reloads on file changes.

```bash
cd docs
mint dev   # or: mintlify dev
```

--------------------------------

### Clone Repository and Start Dev Server

Source: https://github.com/factory-ai/factory/wiki/overview--getting-started

Clone the Factory AI repository and navigate to the docs directory to start the local development server for live preview.

```bash
git clone https://github.com/Factory-AI/factory.git
cd factory/docs
mint dev   # or: mintlify dev
```

--------------------------------

### Run Incident Response Setup Command

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/features/incident-response.mdx

Execute this command in the Droid CLI to initiate the guided setup for an incident response channel. If Slack is not yet connected, it will trigger the Slack OAuth flow.

```text
/setup-incident-response
```

--------------------------------

### Example CLI Configuration

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/configuration/settings.mdx

A sample JSON configuration file for the CLI. This includes settings for the AI model, reasoning effort, diff mode, and various sound preferences.

```json
{
  "model": "claude-opus-4-7",
  "reasoningEffort": "low",
  "diffMode": "github",
  "cloudSessionSync": true,
  "completionSound": "fx-ok01",
  "awaitingInputSound": "fx-ack01",
  "soundFocusMode": "always"
}
```

--------------------------------

### CLI App QA Example

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/skills/automated-qa.mdx

This example demonstrates the output of a QA test run for a CLI application, specifically showing the help text output. It verifies that the help text includes updated descriptions and new features.

```bash
$ ./glow --help
  Render markdown on the CLI, with pizzazz!
  Now with improved word wrapping and line number support.
```

--------------------------------

### Get Daily Productivity Data

Source: https://github.com/factory-ai/factory/blob/main/docs/reference/analytics-api.mdx

Retrieve daily file operations and Git activity. Requires specifying start and end dates.

```bash
GET /productivity
```

--------------------------------

### OTLP Collector Configuration Examples

Source: https://github.com/factory-ai/factory/blob/main/docs/enterprise/telemetry-export.mdx

Environment variable configurations for various observability platforms.

```bash
export OTEL_TELEMETRY_ENDPOINT="https://collector.example.com:4318"
```

```bash
export OTEL_TELEMETRY_ENDPOINT="http://localhost:4318"
```

```bash
export OTEL_TELEMETRY_ENDPOINT="https://otlp.datadoghq.com"
export OTEL_TELEMETRY_HEADERS="dd-api-key=<your-datadog-api-key>"
```

```bash
export OTEL_TELEMETRY_ENDPOINT="https://otlp.nr-data.net:4318"
export OTEL_TELEMETRY_HEADERS="api-key=<your-new-relic-license-key>"
```

```bash
export OTEL_TELEMETRY_ENDPOINT="https://api.honeycomb.io"
export OTEL_TELEMETRY_HEADERS="x-honeycomb-team=<your-api-key>,x-honeycomb-dataset=droid-metrics"
```

--------------------------------

### Analyze Codebase Architecture

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/getting-started/common-use-cases.mdx

Use this prompt to get an overview of a codebase's architecture, technologies, frameworks, entry points, and testing setup.

```text
Analyze this codebase and explain the overall architecture.
What technologies and frameworks does this project use?
Where are the main entry points and how is testing set up?
```

--------------------------------

### Programmatically Extract Doc Examples

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/hooks/documentation-sync.mdx

Use sed to extract code blocks marked with specific start and end comments from test files.

```bash
sed -n '/DOC_EXAMPLE_START/,/DOC_EXAMPLE_END/p' test.ts
```

--------------------------------

### Monorepo Workspace Setup Hook

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/hooks/session-automation.mdx

This script automatically detects monorepo structures and displays workspace information and recent changes. It requires jq to be installed.

```bash
#!/bin/bash
set -e

input=$(cat)
cwd=$(echo "$input" | jq -r '.cwd')

# Check if this is a monorepo
if [ ! -f "$cwd/package.json" ] || ! grep -q '"workspaces"' "$cwd/package.json"; then
  exit 0
fi

echo "## Monorepo Structure"
echo ""

# List workspaces
if command -v npm &> /dev/null; then
  echo "Available workspaces:"
  npm ls --workspaces --depth=0 2>/dev/null | grep -E '^[├└]' | sed 's/^[├└]── /  - /'
  echo ""
fi

# Show recent changes by workspace
if [ -d ".git" ]; then
  echo "Recently modified workspaces:"
  git diff --name-only HEAD~5..HEAD | \
    grep -E '^(packages|apps)/' | \
    cut -d/ -f1-2 | \
    sort -u | \
    head -n 5 | \
    sed 's/^/  - /'
  echo ""
fi

exit 0

```

--------------------------------

### GET User Activity Endpoint

Source: https://github.com/factory-ai/factory/blob/main/docs/reference/analytics-api.mdx

Retrieve daily, weekly, and monthly active users and session counts. Specify start and end dates for the query.

```http
GET /activity
```

--------------------------------

### Example hooks.json Configuration

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/configuration/plugins.mdx

An example of the hooks.json file, demonstrating how to configure hooks for specific lifecycle events like PostToolUse.

```json
{
  "PostToolUse": [
    {
      "matcher": "Create|Edit|ApplyPatch",
      "hooks": [
        {
          "type": "command",
          "command": "${DROID_PLUGIN_ROOT}/hooks/format.sh"
        }
      ]
    }
  ]
}
```

--------------------------------

### GET /tools Endpoint

Source: https://github.com/factory-ai/factory/blob/main/docs/reference/analytics-api.mdx

Use this endpoint to retrieve daily analytics data. Specify start and end dates for the desired period. The `group_by` parameter can be set to `tool_name` for a more granular breakdown.

```http
GET /tools
```

--------------------------------

### Example Action Items

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/features/readiness-report.mdx

Provides concrete recommendations for improving the repository's maturity level.

```text
Action Items:
- Add pre-commit hooks with husky to enforce linting and formatting
- Configure branch protection rules on the main branch
- Add AGENTS.md with setup and development instructions
```

--------------------------------

### Full Plugin Manifest Example

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/building/building-plugins.mdx

This is a comprehensive example of a plugin manifest file, including all optional fields like author, homepage, repository, and license.

```json
{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "homepage": "https://github.com/you/my-plugin",
  "repository": "https://github.com/you/my-plugin",
  "license": "MIT"
}
```

--------------------------------

### CI Periodic Security Audit with Artifact Upload

Source: https://github.com/factory-ai/factory/blob/main/docs/enterprise/security-review.mdx

Schedule a mission-based security audit in GitHub Actions. This example includes installing the Droid CLI, running the audit, and uploading the findings as an artifact for later retrieval.

```yaml
on:
  schedule:
    - cron: '0 6 * * 1'

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Droid CLI
        run: |
          curl -fsSL https://app.factory.ai/cli | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Run deep security review
        env:
          FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
        run: |
          droid exec --mission --auto high -m claude-opus-4-7 \
            "/security-review across the entire repository"
      - name: Upload security review output
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: deep-security-review-${{ github.run_id }}
          path: ~/security-audits/
          if-no-files-found: warn
          retention-days: 90
```

--------------------------------

### Run Parallel Droid Sessions in Separate Worktrees

Source: https://github.com/factory-ai/factory/blob/main/docs/reference/cli-reference.mdx

This example demonstrates running two Droid sessions in parallel, each isolated in its own git worktree on different branches. This setup is useful for simultaneously working on distinct features or bug fixes within the same repository.

```bash
droid --worktree feature-a &
droid --worktree feature-b &
```

--------------------------------

### Run QA Skill in GitHub Actions

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/skills/automated-qa.mdx

This example shows a GitHub Actions workflow that triggers on pull requests, installs necessary tools, and runs the QA skill. It uploads evidence and posts a report as a PR comment. Configure required GitHub secrets for credentials.

```yaml
name: QA

on:
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup Python
      uses: actions/setup-python@v3
      with:
        python-version: '3.x'
    - name: Install dependencies
      run: |
        pip install "git+https://github.com/factory-ai/factory.git#egg=factory-ai[qa]"
        # install other dependencies like ImageMagick
        sudo apt-get update && sudo apt-net install -y imagemagick
    - name: Run QA skill
      run: droid exec --skill qa --config config.yaml
```

--------------------------------

### Install Mintlify CLI

Source: https://github.com/factory-ai/factory/blob/main/docs/README.md

Install the Mintlify CLI globally to preview documentation changes locally. This command is run in your terminal.

```bash
npm i -g mintlify
```

--------------------------------

### Record a Demo with /demo

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/features/droid-control.mdx

Use the /demo command to record a demo video of a feature or pull request. Accepts a PR number, GitHub URL, or free-text description. Flags can be added for extra polish like 'showcase' or 'keys'.

```bash
/demo pr-1847
```

```bash
/demo pr-1847 -- showcase, keys
```

--------------------------------

### Add Authentication Middleware to GET Handler

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/droid-exec/refactor-fix-lint.mdx

Before: GET handler without authentication. After: GET handler secured with `handleAuthenticatedMiddleware` for proper user authentication.

```typescript
// apps/factory-app/src/app/api/sessions/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { getFirestoreInstance } from '@factory/services/firebase/admin';

export async function GET(req: NextRequest) {
  const searchParams = req.nextUrl.searchParams;
  const userId = searchParams.get('userId');
  
  ...
  
  return NextResponse.json({
    sessions: sessions.docs.map(doc => doc.data())
  });
}
```

```typescript
// apps/factory-app/src/app/api/sessions/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { getFirestoreInstance } from '@factory/services/firebase/admin';
import { handleAuthenticatedMiddleware } from '@/app/api/_utils/middleware';

export async function GET(req: NextRequest) {
  return handleAuthenticatedMiddleware(req, async ({ req, user }) => {
    const searchParams = req.nextUrl.searchParams;
    const userId = searchParams.get('userId');
    
    ...
    
    return NextResponse.json({
      sessions: sessions.docs.map(doc => doc.data())
    });
  });
}
```

--------------------------------

### Create AGENTS.md for Project Guidelines

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/power-user/setup-checklist.mdx

Create a basic AGENTS.md file at your repository root to define project guidelines for build, test, lint, and code style.

```markdown
# Project Guidelines

## Build & Test
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Code Style
- Use TypeScript strict mode
- Prefer functional components in React
- Write tests for new features
```

--------------------------------

### Uninstall an installed plugin

Source: https://github.com/factory-ai/factory/blob/main/docs/cli/configuration/plugins.mdx

Removes an installed plugin. The command accepts an optional scope flag (`--scope user|project`) to specify where the plugin is installed.

```bash
droid plugin uninstall droid-control@factory-plugins
```

--------------------------------

### Run Droid Exec Example Locally

Source: https://github.com/factory-ai/factory/blob/main/docs/guides/building/droid-exec-tutorial.mdx

Navigate to the droid-chat directory and run the local development server.

```bash
cd examples/droid-chat && bun dev
```