Configuration Reference

Configuration Reference

ZERG is configured through .zerg/config.yaml at the project root. This page documents every configuration option, its default value, and usage examples.

For performance tuning guidance, see [[Tuning Guide]]. For plugin configuration, see [[Plugin System]].

Configuration File Location

your-project/
  .zerg/
    config.yaml       <-- Primary configuration file
    state/            <-- Runtime state (managed by ZERG)
    logs/             <-- Worker and orchestrator logs

ZERG reads .zerg/config.yaml on every command invocation. Changes take effect on the next command run -- no restart is required.

Full Configuration Schema

project

Project metadata used in task subjects and log output.

project:
  name: my-service
  description: REST API for user management

workers

Controls how many parallel Claude Code instances run and how they behave.

workers:
  max_concurrent: 5
  timeout_minutes: 60
  retry_attempts: 2
  context_threshold_percent: 70
  launcher_type: subprocess
  backoff_strategy: exponential
  backoff_base_seconds: 30
  backoff_max_seconds: 300

ports

Port allocation for worker processes. Each worker reserves a contiguous block of ports from the configured range.

ports:
  range_start: 49152
  range_end: 65535
  ports_per_worker: 10

The total number of workers you can run simultaneously is constrained by (range_end - range_start) / ports_per_worker. With the defaults, this allows up to 1638 workers (far above any practical limit).

quality_gates

Ordered list of validation commands that run after each level merge. Gates execute sequentially in the order listed. See [[Plugin System]] for adding custom gates via plugins.

Each gate entry has these fields:

quality_gates:
  - name: lint
    command: ruff check .
    required: true
    timeout: 300

  - name: typecheck
    command: mypy . --strict --ignore-missing-imports
    required: true
    timeout: 300

  - name: test
    command: pytest tests/unit/ -x --timeout=30
    required: true
    timeout: 600

  - name: coverage
    command: pytest tests/unit/ --cov=zerg --cov-fail-under=80 -q --timeout=30
    required: false
    timeout: 600
    coverage_threshold: 80

  - name: security
    command: ruff check . --select S
    required: false
    timeout: 120

Gate results. Each gate produces one of five results: PASS, FAIL, SKIP, TIMEOUT, or ERROR. Required gates that produce FAIL or ERROR block the merge. Non-required gates log warnings but do not block.

mcp_servers

List of MCP (Model Context Protocol) servers to make available to worker instances.

mcp_servers:
  - filesystem
  - github
  - fetch

Workers launched in container mode receive these as --mcp-server flags. Subprocess workers inherit MCP servers from the parent Claude Code session.

resources

Resource limits for worker instances. These apply primarily to container mode but also inform subprocess resource monitoring.

resources:
  cpu_cores: 2
  memory_gb: 4
  disk_gb: 10
  container_memory_limit: "4g"
  container_cpu_limit: 2.0

logging

Log output configuration.

logging:
  level: info
  directory: .zerg/logs
  retain_days: 7

security

Security settings for worker execution and audit trail.

security:
  level: standard
  pre_commit_hooks: true
  audit_logging: true
  container_readonly: true

plugins

Plugin system configuration. See [[Plugin System]] and [[Plugin API Reference]] for details.

plugins:
  enabled: true

  hooks:
    - event: task_completed
      command: echo "Task done"
      timeout: 60

  quality_gates:
    - name: security-scan
      command: bandit -r src/
      required: false
      timeout: 300

  context_engineering:
    enabled: true
    command_splitting: true
    security_rule_filtering: true
    task_context_budget_tokens: 4000
    fallback_to_full: true

For context_engineering options, see [[Context Engineering]].

rules

Engineering rules injected into worker context based on file extensions.

rules:
  enabled: true
  base_rules: true
  custom_rules: true
  disabled_rules: []
  inject_into_workers: true

efficiency

Token efficiency settings for automatic compact mode activation.

efficiency:
  auto_compact_threshold: 0.75
  symbol_system: true
  abbreviations: true

improvement_loops

Iterative improvement loop configuration.

improvement_loops:
  max_iterations: 5
  plateau_threshold: 2
  rollback_on_regression: true
  convergence_threshold: 0.02

verification

Verification gate pipeline settings.

verification:
  require_before_completion: true
  staleness_threshold_seconds: 300
  store_artifacts: true
  artifact_dir: ".zerg/artifacts"

behavioral_modes

Behavioral mode auto-detection and defaults.

behavioral_modes:
  auto_detect: true
  default_mode: precision
  log_transitions: true

mcp_routing

MCP auto-routing configuration.

mcp_routing:
  auto_detect: true
  available_servers:
    - sequential
    - context7
    - playwright
    - morphllm
    - magic
    - serena
  cost_aware: true
  telemetry: true
  max_servers: 3

tdd

TDD enforcement configuration (off by default).

tdd:
  enabled: false
  enforce_red_green: true
  anti_patterns:
    - mock_heavy
    - testing_impl
    - no_assertions

error_recovery

Error recovery with circuit breaker and backpressure.

error_recovery:
  circuit_breaker:
    enabled: true
    failure_threshold: 3
    cooldown_seconds: 60
  backpressure:
    enabled: true
    failure_rate_threshold: 0.5
    window_size: 10

Complete Example

The following is the full default configuration with all options shown:

project:
  name: my-project
  description: My project description

workers:
  max_concurrent: 5
  timeout_minutes: 60
  retry_attempts: 2
  context_threshold_percent: 70
  launcher_type: subprocess
  backoff_strategy: exponential
  backoff_base_seconds: 30
  backoff_max_seconds: 300

ports:
  range_start: 49152
  range_end: 65535
  ports_per_worker: 10

quality_gates:
  - name: lint
    command: ruff check .
    required: true
    timeout: 300
  - name: typecheck
    command: mypy . --strict --ignore-missing-imports
    required: true
    timeout: 300
  - name: test
    command: pytest tests/unit/ -x --timeout=30
    required: true
    timeout: 600

mcp_servers:
  - filesystem
  - github

resources:
  cpu_cores: 2
  memory_gb: 4
  disk_gb: 10
  container_memory_limit: "4g"
  container_cpu_limit: 2.0

logging:
  level: info
  directory: .zerg/logs
  retain_days: 7

security:
  level: standard
  pre_commit_hooks: true
  audit_logging: true
  container_readonly: true

plugins:
  enabled: true
  hooks: []
  quality_gates: []
  launchers: []
  context_engineering:
    enabled: true
    command_splitting: true
    security_rule_filtering: true
    task_context_budget_tokens: 4000
    fallback_to_full: true

rules:
  enabled: true
  base_rules: true
  custom_rules: true
  disabled_rules: []
  inject_into_workers: true

efficiency:
  auto_compact_threshold: 0.75
  symbol_system: true
  abbreviations: true

improvement_loops:
  max_iterations: 5
  plateau_threshold: 2
  rollback_on_regression: true
  convergence_threshold: 0.02

verification:
  require_before_completion: true
  staleness_threshold_seconds: 300
  store_artifacts: true
  artifact_dir: ".zerg/artifacts"

behavioral_modes:
  auto_detect: true
  default_mode: precision
  log_transitions: true

mcp_routing:
  auto_detect: true
  available_servers:
    - sequential
    - context7
    - playwright
    - morphllm
    - magic
    - serena
  cost_aware: true
  telemetry: true
  max_servers: 3

tdd:
  enabled: false
  enforce_red_green: true
  anti_patterns:
    - mock_heavy
    - testing_impl
    - no_assertions

error_recovery:
  circuit_breaker:
    enabled: true
    failure_threshold: 3
    cooldown_seconds: 60
  backpressure:
    enabled: true
    failure_rate_threshold: 0.5
    window_size: 10

Environment Variables

Workers recognize specific environment variables for cross-session coordination. These are set automatically by the launcher and should not normally require manual configuration.

See Also

• [[Tuning Guide]] -- When and how to adjust these values
• [[Plugin System]] -- Extending ZERG with custom gates, hooks, and launchers
• [[Context Engineering]] -- Token optimization configuration