Config

Smart defaults

Maestro will automatically generate a config file with reasonable default settings, but you can edit it to suit your preferences. The config file is stored in <projectRoot>/.maestro/config.json. A few of the most common tweaks you might want to make include:

Model selection which LLM you want to use for each type of agent (including local models)
Rate limits if you want to control LLM query speeds to keep under your key limits
Agent count how many coders you want to spin up

Configuration Reference

Below is a comprehensive reference of all configuration options available in config.json.

Top-Level Settings

Field	Type	Default	Description
`schema_version`	string	`"1.0"`	Config schema version. Do not modify manually.
`default_mode`	string	`"standard"`	Default operating mode: `"standard"` (cloud APIs) or `"airplane"` (offline with local Gitea + Ollama). Can be overridden with `-airplane` CLI flag.

`project` - Project Information

Basic project metadata.

Field	Type	Default	Description
`name`	string	`""`	Project name
`primary_platform`	string	`""`	Primary platform: `go`, `python`, `node`, `docker`, `generic`

`container` - Container Settings

Docker container configuration for running code.

Field	Type	Default	Description
`name`	string	`"maestro-bootstrap:latest"`	Container image name/tag
`dockerfile`	string	`""`	Path to Dockerfile if building custom image
`workspace_path`	string	`"/workspace"`	Path where project is mounted inside container
`pinned_image_id`	string	`""`	Currently pinned Docker image ID (sha256:...)
`safe_image_id`	string	`""`	Safe fallback Docker image ID
`network`	string	`"bridge"`	Docker network mode
`tmpfs_size`	string	`"1g"`	Size of tmpfs mount for /tmp
`cpus`	string	`"2"`	CPU limit for container
`memory`	string	`"2g"`	Memory limit for container
`pids`	int	`1024`	Process limit (--pids-limit)

`build` - Build Commands

Commands for building, testing, and running the project.

Field	Type	Default	Description
`build`	string	`"make build"`	Build command
`test`	string	`"make test"`	Test command
`lint`	string	`"make lint"`	Lint command
`run`	string	`"make run"`	Run command
`clean`	string	`""`	Clean command (optional)
`install`	string	`""`	Install command (optional)

`agents` - Agent Configuration

Settings for AI agents including model selection and concurrency.

Field	Type	Default	Description
`max_coders`	int	`3`	Maximum concurrent coder agents
`coder_model`	string	`"claude-sonnet-4-5"`	Model for coder agents
`coder_mode`	string	`"standard"`	Coder execution mode: `"standard"` or `"claude-code"`
`architect_model`	string	`"gemini-3-pro-preview"`	Model for architect agent
`pm_model`	string	`"claude-opus-4-5"`	Model for PM agent
`state_timeout`	duration	`"10m"`	Global timeout for state processing

Supported Models

Model Name	Provider	Context Window	Notes
`claude-sonnet-4-5`	Anthropic	200K	Recommended for coding
`claude-opus-4-5`	Anthropic	200K	Best for complex reasoning
`gpt-4o`	OpenAI	128K	Fast, capable
`o3`	OpenAI	128K	Reasoning model
`o4-mini`	OpenAI	128K	Fast reasoning
`gpt-5`	OpenAI	128K	Premium
`gemini-2.5-flash`	Google	1M	Large context
`gemini-3-pro-preview`	Google	1M	Best for architecture

Claude Code Mode

The coder_mode setting controls how coder agents execute their work. There are two modes:

Mode	Description
`standard`	Default mode. Coder agents use Maestro's built-in LLM integration with tool calls for file operations, shell commands, etc. Works with any supported model provider.
`claude-code`	Coder agents delegate to Claude Code (Anthropic's agentic coding tool) as a subprocess. Provides enhanced coding capabilities with Claude Code's specialized tooling.

Enabling Claude Code Mode:

{
  "agents": {
    "coder_mode": "claude-code",
    "coder_model": "claude-sonnet-4-5"
  }
}

Requirements for Claude Code Mode:

Anthropic model required: The coder_model must be a Claude model (e.g., claude-sonnet-4-5, claude-opus-4-5). Using a non-Anthropic model with claude-code mode will fail validation.
Claude Code CLI: The claude CLI must be installed and accessible in the system PATH.
ANTHROPIC_API_KEY: Must be set in environment or secrets file.

When to Use Claude Code Mode:

Complex refactoring tasks that benefit from Claude Code's agentic capabilities
Projects where you want Claude Code's specialized file editing and shell execution
When you prefer Claude Code's approach to multi-file changes

When to Use Standard Mode:

When using non-Anthropic models (GPT, Gemini, Ollama)
When you want consistent behavior across different model providers
For simpler tasks where Maestro's built-in tooling is sufficient

`agents.airplane` - Airplane Mode Model Overrides

Models to use when running in airplane mode (offline).

Field	Type	Default	Description
`coder_model`	string	`"mistral-nemo:latest"`	Ollama model for coders
`architect_model`	string	`"mistral-nemo:latest"`	Ollama model for architect
`pm_model`	string	`"mistral-nemo:latest"`	Ollama model for PM

`agents.metrics` - Metrics Configuration

Field	Type	Default	Description
`enabled`	bool	`true`	Enable metrics collection
`exporter`	string	`"internal"`	Exporter type: `"internal"`, `"prometheus"`, `"noop"`
`namespace`	string	`"maestro"`	Metrics namespace
`prometheus_url`	string	`""`	Prometheus server URL

`agents.resilience` - Resilience Configuration

Circuit Breaker

Field	Type	Default	Description
`failure_threshold`	int	`5`	Failures before opening circuit
`success_threshold`	int	`3`	Successes to close circuit
`timeout`	duration	`"30s"`	Time before trying half-open

Retry Policy

Field	Type	Default	Description
`max_attempts`	int	`3`	Maximum retry attempts
`initial_delay`	duration	`"100ms"`	Initial delay before first retry
`max_delay`	duration	`"10s"`	Maximum delay between retries
`backoff_factor`	float	`2.0`	Exponential backoff multiplier
`jitter`	bool	`true`	Add random jitter

Rate Limits (per provider)

Each provider (anthropic, openai, google, ollama) has:

Field	Type	Default (Anthropic/OpenAI)	Default (Google)	Default (Ollama)	Description
`tokens_per_minute`	int	`1000000`	`1200000`	`1000000`	Rate limit in TPM
`max_concurrency`	int	`5`	`5`	`2`	Max concurrent requests

`git` - Git Configuration

Field	Type	Default	Description
`repo_url`	string	`""`	Git repository URL (HTTPS format)
`target_branch`	string	`"main"`	Target branch for pull requests
`mirror_dir`	string	`".mirrors"`	Directory for git mirrors
`branch_pattern`	string	`"story-{STORY_ID}"`	Branch naming pattern
`git_user_name`	string	`"Maestro {AGENT_ID}"`	Commit author name
`git_user_email`	string	`"maestro-{AGENT_ID}@localhost"`	Commit author email

`webui` - Web UI Settings

Field	Type	Default	Description
`enabled`	bool	`true`	Enable web UI
`host`	string	`"localhost"`	Host to bind to
`port`	int	`8080`	Port to listen on
`ssl`	bool	`false`	Enable SSL/TLS
`cert`	string	`""`	Path to SSL certificate
`key`	string	`""`	Path to SSL private key

`chat` - Agent Chat System

Field	Type	Default	Description
`enabled`	bool	`true`	Enable chat system
`max_new_messages`	int	`100`	Max new messages per LLM call

`chat.limits`

Field	Type	Default	Description
`max_message_chars`	int	`4096`	Maximum message size

`chat.scanner` - Secret Scanning

Field	Type	Default	Description
`enabled`	bool	`true`	Enable secret scanning
`timeout_ms`	int	`800`	Scanner timeout in ms

`pm` - PM Agent Settings

Field	Type	Default	Description
`enabled`	bool	`true`	Enable PM agent
`max_interview_turns`	int	`20`	Max conversation turns
`default_expertise`	string	`"BASIC"`	Default user expertise: `NON_TECHNICAL`, `BASIC`, `EXPERT`

`search` - Web Search

Field	Type	Default	Description
`enabled`	bool	`null` (auto-detect)	Enable web search (auto-enabled when API keys are detected)

`demo` - Demo Mode Settings

Field	Type	Default	Description
`container_port_override`	int	`0`	Manual override for container port
`selected_container_port`	int	`0`	User-selected or auto-detected port
`run_cmd_override`	string	`""`	Override build.run command for demo
`healthcheck_path`	string	`"/health"`	HTTP path for readiness check
`healthcheck_timeout_seconds`	int	`60`	Max wait time for app to become healthy

`logs` - Log Management

Field	Type	Default	Description
`rotation_count`	int	`4`	Number of old log files to keep

`debug` - Debug Settings

Field	Type	Default	Description
`llm_messages`	bool	`false`	Enable debug logging for LLM messages

`maintenance` - Automated Maintenance

Settings for periodic housekeeping between specs.

Field	Type	Default	Description
`enabled`	bool	`true`	Enable maintenance mode
`after_specs`	int	`1`	Number of specs before triggering maintenance

`maintenance.tasks` - Enabled Tasks

Field	Type	Default	Description
`branch_cleanup`	bool	`true`	Clean up stale merged branches
`knowledge_sync`	bool	`true`	Sync knowledge graph with codebase
`docs_verification`	bool	`true`	Verify documentation accuracy
`todo_scan`	bool	`true`	Scan for TODOs and deprecated code
`deferred_review`	bool	`true`	Review deferred knowledge nodes
`test_coverage`	bool	`true`	Improve test coverage

`maintenance.branch_cleanup`

Field	Type	Default	Description
`protected_patterns`	[]string	`["main", "master", "develop", "release/", "hotfix/"]`	Branch patterns to never delete

`maintenance.todo_scan`

Field	Type	Default	Description
`markers`	[]string	`["TODO", "FIXME", "HACK", "XXX", "deprecated", "DEPRECATED", "@deprecated"]`	Comment markers to scan for

Example Configuration

{
  "schema_version": "1.0",
  "project": {
    "name": "my-project",
    "primary_platform": "go"
  },
  "agents": {
    "max_coders": 3,
    "coder_model": "claude-sonnet-4-5",
    "architect_model": "gemini-3-pro-preview",
    "pm_model": "claude-opus-4-5",
    "resilience": {
      "rate_limit": {
        "anthropic": {
          "tokens_per_minute": 1000000,
          "max_concurrency": 5
        }
      }
    }
  },
  "git": {
    "repo_url": "https://github.com/owner/repo.git",
    "target_branch": "main"
  },
  "webui": {
    "enabled": true,
    "port": 8080
  }
}

Uh oh!

Config

Smart defaults

Configuration Reference

Top-Level Settings

project - Project Information

container - Container Settings

build - Build Commands

agents - Agent Configuration

Supported Models

Claude Code Mode

agents.airplane - Airplane Mode Model Overrides

agents.metrics - Metrics Configuration

agents.resilience - Resilience Configuration

Circuit Breaker

Retry Policy

Rate Limits (per provider)

git - Git Configuration

webui - Web UI Settings

chat - Agent Chat System

chat.limits

chat.scanner - Secret Scanning

pm - PM Agent Settings

search - Web Search

demo - Demo Mode Settings

logs - Log Management

debug - Debug Settings

maintenance - Automated Maintenance

maintenance.tasks - Enabled Tasks

maintenance.branch_cleanup

maintenance.todo_scan

Example Configuration

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Overview

Subsystems

Clone this wiki locally

`project` - Project Information

`container` - Container Settings

`build` - Build Commands

`agents` - Agent Configuration

`agents.airplane` - Airplane Mode Model Overrides

`agents.metrics` - Metrics Configuration

`agents.resilience` - Resilience Configuration

`git` - Git Configuration

`webui` - Web UI Settings

`chat` - Agent Chat System

`chat.limits`

`chat.scanner` - Secret Scanning

`pm` - PM Agent Settings

`search` - Web Search

`demo` - Demo Mode Settings

`logs` - Log Management

`debug` - Debug Settings

`maintenance` - Automated Maintenance

`maintenance.tasks` - Enabled Tasks

`maintenance.branch_cleanup`

`maintenance.todo_scan`