-
-
Notifications
You must be signed in to change notification settings - Fork 140
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.yamlis only required for daemon mode (openswarm start). The TUI chat,run, andcheckcommands work without it.
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
Default CLI adapter for Worker/Reviewer stages.
adapter: claude # "claude" | "codex" | "gpt" | "local"
See Adapters for provider-specific setup.
discord: token: ${DISCORD_TOKEN} channelId: ${DISCORD_CHANNEL_ID} webhookUrl: ${DISCORD_WEBHOOK_URL:-} # Optional, for rich embeds
linear: apiKey: ${LINEAR_API_KEY} teamId: ${LINEAR_TEAM_ID}
github: repos: - owner/repo # owner/repo format checkInterval: 300000 # 5 minutes (ms)
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: 1800000 # 30 minutes (ms)
autonomous: enabled: true pairMode: true # Worker + Reviewer schedule: "*/15 * * * *" # Cron expression maxAttempts: 3 maxConcurrentTasks: 4 allowedProjects: - ~/dev/my-project
decomposition: enabled: true thresholdMinutes: 30 # Decompose if estimated > 30 min plannerModel: claude-sonnet-4-20250514
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.
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
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
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
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
| 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 |
Getting Started
Reference
Deep Dive
Help