Configuration

Configuration

OpenSwarm uses config.yaml for daemon-mode settings. Generate a scaffold with:

openswarm init

Environment variables are supported via ${VAR_NAME} or ${VAR_NAME:-default} syntax. Config is validated with Zod schemas on startup.

Note: config.yaml is only required for daemon mode (openswarm start). The TUI chat, run, and check commands work without it.

---

Minimal Config

adapter: claude

discord:
  token: ${DISCORD_TOKEN}
  channelId: ${DISCORD_CHANNEL_ID}

linear:
  apiKey: ${LINEAR_API_KEY}
  teamId: ${LINEAR_TEAM_ID}

agents:
  - name: main
    projectPath: ~/dev/my-project
    enabled: true

Create a .env file alongside:

DISCORD_TOKEN=your-discord-bot-token
DISCORD_CHANNEL_ID=your-channel-id
LINEAR_API_KEY=your-linear-api-key
LINEAR_TEAM_ID=your-linear-team-id

---

Full Reference

adapter

Default CLI adapter for Worker/Reviewer stages.

adapter: claude   # "claude" | "codex" | "gpt" | "local"

See Adapters for provider-specific setup.

discord

discord:
  token: ${DISCORD_TOKEN}
  channelId: ${DISCORD_CHANNEL_ID}
  webhookUrl: ${DISCORD_WEBHOOK_URL:-}  # Optional, for rich embeds

linear

linear:
  apiKey: ${LINEAR_API_KEY}
  teamId: ${LINEAR_TEAM_ID}

github

github:
  repos:
    - owner/repo            # owner/repo format
  checkInterval: 300000      # 5 minutes (ms)

agents

Define one or more agents, each tied to a project directory.

agents:
  - name: main
    projectPath: ~/dev/my-project
    heartbeatInterval: 1800000   # 30 min (ms)
    linearLabel: main            # Linear issue label filter
    enabled: true
    paused: false

defaultHeartbeatInterval

defaultHeartbeatInterval: 1800000   # 30 minutes (ms)

---

Autonomous Mode

autonomous:
  enabled: true
  pairMode: true                     # Worker + Reviewer
  schedule: "*/15 * * * *"           # Cron expression
  maxAttempts: 3
  maxConcurrentTasks: 4
  allowedProjects:
    - ~/dev/my-project

Task Decomposition (Planner)

  decomposition:
    enabled: true
    thresholdMinutes: 30                   # Decompose if estimated > 30 min
    plannerModel: claude-sonnet-4-20250514

Per-Role Settings

Each pipeline role can have its own adapter, model, and timeout.

  defaultRoles:
    worker:
      enabled: true
      adapter: claude
      model: claude-sonnet-4-20250514
      escalateModel: claude-opus-4-6       # Fallback on failure
      escalateAfterIteration: 3
      timeoutMs: 1800000
    reviewer:
      enabled: true
      adapter: local                       # Free local model
      model: gemma-4-e4b-it
      escalateModel: claude-sonnet-4-20250514
      escalateAfterIteration: 3
      timeoutMs: 60000
    tester:
      enabled: false
    documenter:
      enabled: false
      adapter: local
      model: gemma-4-e4b-it
      timeoutMs: 120000
    auditor:
      enabled: false
    skill-documenter:
      enabled: false

Escalation: When a Worker or Reviewer fails after N iterations, it automatically switches to a more capable model.

Pipeline Guards

  guards:
    qualityGate: true            # Code quality checks
    fakeDataGuard: true          # Block fake/mock data in production code
    conventionalCommits: true    # Enforce conventional commit format
    branchValidation: true       # Validate branch naming
    uncertaintyDetection: true   # Detect uncertain language in outputs
    registryCheck: true          # Code Registry validation
    bsDetector: true             # Bad code smell detection

Job Profiles

Assign different models based on task complexity.

  jobProfiles:
    - name: quick-analysis
      maxMinutes: 15
      roles:
        worker: claude-haiku-4-5-20251001
    - name: deep-engineering
      minMinutes: 16
      roles:
        worker: claude-sonnet-4-20250514
        reviewer: claude-sonnet-4-20250514

---

PR Auto-Improvement

Monitors open PRs, auto-fixes CI failures, and resolves merge conflicts.

prProcessor:
  enabled: true
  schedule: "*/15 * * * *"       # Check every 15 minutes
  cooldownHours: 6               # Wait 6h after processing a PR
  maxIterations: 3               # Max fix iterations per PR

---

Long-Running Monitors

Track external processes (training jobs, batch tasks).

monitors:
  - id: runpod-training
    name: "LSTM model training"
    issueId: INT-456
    checkCommand: 'ssh runpod "tail -1 /workspace/train.log"'
    completionCheck:
      type: output-regex
      successPattern: "Training finished"
      failurePattern: "Error|FAILED"
    checkInterval: 2              # Every 2 heartbeats
    maxDurationHours: 24
    notify: true

---

State & Data Paths

Path	Description
~/.openswarm/	State directory
~/.openswarm/registry.db	Code entity registry (SQLite)
~/.openswarm/issues.db	Local issue tracker (SQLite)
~/.openswarm/chat/	Chat session files
~/.claude/openswarm-*.json	Pipeline history
config.yaml	Main configuration
.env	Environment variables