ZERG Configuration Guide

Complete reference for configuring ZERG — config files, environment variables, quality gates, logging, plugins, and tuning.

---

Table of Contents

• Configuration File
• Workers
• Quality Gates
• Pre-commit Hooks
• Logging
• Plugins
• Context Engineering
• Security
• MCP Servers
• Environment Variables
• Container Mode
• Tuning Guide

---

Configuration File

Location: .zerg/config.yaml

Created automatically by zerg init. All settings have sensible defaults.

Full Example

version: "1.0"
project_type: python

workers:
  default_count: 5
  max_count: 10
  context_threshold: 0.7
  timeout_seconds: 3600
  retry_attempts: 3

security:
  network_isolation: true
  filesystem_sandbox: true
  secrets_scanning: true

quality_gates:
  lint:
    command: "ruff check ."
    required: true
  typecheck:
    command: "mypy ."
    required: false
  test:
    command: "pytest"
    required: true

hooks:
  pre_commit:
    enabled: true
    security_checks:
      secrets_detection: true
      shell_injection: true
      block_on_violation: true
    quality_checks:
      ruff_lint: true
      warn_on_violation: true

plugins:
  enabled: true
  hooks:
    - event: level_complete
      command: echo "Level {level} done"
      timeout: 60
  quality_gates:
    - name: security-scan
      command: bandit -r src/
      required: false
      timeout: 300

mcp_servers:
  - name: filesystem
    command: npx
    args: ["-y", "@anthropic/mcp-filesystem"]

---

Workers

Control zergling behavior and resource allocation.

workers:
  default_count: 5        # Default workers for /zerg:rush
  max_count: 10           # Hard limit on concurrent workers
  context_threshold: 0.7  # Checkpoint at this context usage (0.0-1.0)
  timeout_seconds: 3600   # Max time per worker session
  retry_attempts: 3       # Max retries per task before marking blocked

Worker Count Guidelines

Diminishing returns beyond the widest level's parallelizable tasks.

---

Quality Gates

Quality gates run after each level merge. They validate the merged code before workers proceed to the next level.

quality_gates:
  lint:
    command: "ruff check ."
    required: true
  typecheck:
    command: "mypy . --ignore-missing-imports"
    required: false
  test:
    command: "pytest tests/ -v --tb=short"
    required: true

Gate Results

Adding Custom Gates

Via YAML (simple shell commands):

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

Via Python entry points (complex logic): See Plugin System.

---

Pre-commit Hooks

ZERG installs comprehensive pre-commit hooks at .zerg/hooks/pre-commit.

hooks:
  pre_commit:
    enabled: true
    security_checks:
      secrets_detection: true
      shell_injection: true
      block_on_violation: true
    quality_checks:
      ruff_lint: true
      warn_on_violation: true

Security Checks (Block Commit)

These patterns cause commits to be rejected:

Quality Checks (Warn Only)

ZERG-Specific Checks (Warn Only)

Exempt Paths

Tests and fixtures are exempt: tests/, fixtures/, *_test.py, test_*.py, conftest.py

---

Logging

ZERG uses structured JSONL logging with per-worker and per-task output.

Log Locations

JSONL Entry Format

{
  "ts": "2026-01-28T10:30:45.123Z",
  "level": "info",
  "worker_id": 0,
  "feature": "user-auth",
  "message": "Task T1.1 started",
  "task_id": "T1.1",
  "phase": "execute",
  "event": "task_started",
  "data": {},
  "duration_ms": null
}

Log Rotation

Worker logs auto-rotate at 50 MB (renamed to .jsonl.1).

Aggregation

LogAggregator merges JSONL files by timestamp at query time. No pre-built aggregate file exists on disk. Use zerg logs --aggregate to query across all workers.

---

Plugins

plugins:
  enabled: true

  hooks:
    - event: task_completed
      command: echo "Task {task_id} done"
      timeout: 60
    - event: level_complete
      command: ./scripts/notify.sh "Level {level} done"
      timeout: 120

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

See the Plugin System documentation for Python entry point plugins, the security model, and examples.

Context Engineering Plugin

The context engineering plugin minimizes token usage across workers. See Context Engineering for full details.

plugins:
  context_engineering:
    enabled: true                    # Master switch
    command_splitting: true          # Split large commands into core/details
    security_rule_filtering: true    # Filter security rules by task file types
    task_context_budget_tokens: 4000 # Max tokens per task context
    fallback_to_full: true           # Fall back to full context on errors

Hook Event Types

Variable Substitution

Hook commands support: {level}, {feature}, {task_id}, {worker_id}

---

Security

security:
  network_isolation: true
  filesystem_sandbox: true
  secrets_scanning: true

Environment Variable Filtering

ZERG controls which environment variables are passed to workers:

Allowed:

• ZERG_WORKER_ID, ZERG_FEATURE, ZERG_WORKTREE
• ANTHROPIC_API_KEY, OPENAI_API_KEY
• CI, DEBUG, LOG_LEVEL

Blocked:

• LD_PRELOAD, DYLD_INSERT_LIBRARIES
• PYTHONPATH, HOME, USER, SHELL

Command Safety

Task ID Validation

Task IDs are validated against: [A-Za-z][A-Za-z0-9_-]{0,63}

Rejects shell metacharacters, path traversal, and IDs longer than 64 chars.

---

MCP Servers

Configure MCP servers available to workers:

mcp_servers:
  - name: filesystem
    command: npx
    args: ["-y", "@anthropic/mcp-filesystem", "/workspace"]
  - name: github
    command: npx
    args: ["-y", "@anthropic/mcp-github"]

MCP server configuration is copied to worker containers at .devcontainer/mcp-servers/config.json.

---

Cross-Cutting Capabilities

New configuration sections for the cross-cutting capabilities framework.

Engineering Rules

rules:
  enabled: true              # Master switch for rule injection
  base_rules: true           # Include built-in safety/quality/efficiency rules
  custom_rules: true         # Include project-specific custom rules
  disabled_rules: []         # List of rule IDs to disable
  inject_into_workers: true  # Inject relevant rules into worker context

Rule files are YAML in .zerg/rules/ (safety.yaml, quality.yaml, efficiency.yaml). Rules are filtered by file extension and injected into worker context at ~15% of the task context budget.

Efficiency

efficiency:
  auto_compact_threshold: 0.75  # Context usage % to trigger compact mode
  symbol_system: true            # Use symbols for status/domain indicators
  abbreviations: true            # Abbreviate common terms (configuration→cfg)

Improvement Loops

improvement_loops:
  max_iterations: 5            # Max loop iterations (1-10)
  plateau_threshold: 2         # Consecutive no-improvement rounds to stop (1-5)
  rollback_on_regression: true # Revert if score decreases
  convergence_threshold: 0.02  # Min improvement to count as progress (0.001-0.5)

Verification Gates

verification:
  require_before_completion: true       # Require verification before marking done
  staleness_threshold_seconds: 300      # Re-run if older than this (10-3600)
  store_artifacts: true                 # Store verification results as JSON
  artifact_dir: ".zerg/artifacts"       # Artifact storage directory

Behavioral Modes

behavioral_modes:
  auto_detect: true          # Auto-detect mode from task keywords
  default_mode: precision    # Default when no mode detected
  log_transitions: true      # Log mode changes

Available modes: precision, speed, exploration, refactor, debug.

MCP Auto-Routing

mcp_routing:
  auto_detect: true           # Enable capability-based server matching
  available_servers:           # Servers to consider
    - sequential
    - context7
    - playwright
    - morphllm
    - magic
    - serena
  cost_aware: true            # Optimize for lower-cost servers
  telemetry: true             # Record routing decisions
  max_servers: 3              # Max servers per task (1-6)

TDD Enforcement

tdd:
  enabled: false              # Master switch (off by default)
  enforce_red_green: true     # Require red→green→refactor order
  anti_patterns:              # Anti-patterns to detect
    - mock_heavy
    - testing_impl
    - no_assertions

Heartbeat Monitoring

heartbeat:
  interval_seconds: 15        # How often workers write heartbeat (5-300)
  stall_timeout_seconds: 120  # Seconds before declaring a worker stalled (30-600)
  max_restarts: 2             # Auto-restarts before reassigning tasks (0-5)

The orchestrator reads heartbeat files from .zerg/state/heartbeat-{worker_id}.json. When a worker's heartbeat is older than stall_timeout_seconds, the orchestrator marks it as STALLED and triggers auto-restart. After max_restarts consecutive stalls, the worker's tasks are reassigned to a fresh worker.

Escalation Handling

escalation:
  auto_interrupt: true         # Alert terminal on new escalations
  poll_interval_seconds: 5     # How often orchestrator checks for escalations (1-60)

Workers escalate ambiguous failures (unclear spec, missing dependency, unclear verification criteria) to .zerg/state/escalations.json. When auto_interrupt is enabled, the orchestrator prints escalation alerts to stderr.

Three-Tier Verification

verification_tiers:
  tier1_blocking: true         # Tier 1 (syntax) blocks on failure
  tier1_command: null           # Override: custom lint/typecheck command
  tier2_blocking: true         # Tier 2 (correctness) blocks on failure
  tier2_command: null           # Override: custom test command (defaults to task verification)
  tier3_blocking: false        # Tier 3 (quality) does not block by default
  tier3_command: null           # Override: custom quality check command

Workers execute verification in three tiers. Blocking tiers must pass for the task to complete. Non-blocking tiers are logged but don't prevent progress. If no custom command is set, Tier 2 uses the task's verification.command from the task graph.

Repository Symbol Map

repo_map:
  enabled: true                # Build symbol graph at rush start
  languages:                   # Languages to extract symbols from
    - python
    - javascript
    - typescript
  max_tokens_per_module: 3000  # Max tokens for symbol output per module (500-10000)
  context_budget_percent: 15   # % of task context budget for repo map (5-30)

At rush start, ZERG builds a symbol graph using Python AST for .py files and regex extraction for .js/.ts/.jsx/.tsx files. The context plugin queries the graph per-task to inject relevant symbols (functions, classes, imports) into worker prompts, giving workers awareness of nearby code without reading full source files.

Token Metrics

token_metrics:
  enabled: true                    # Master switch for token usage tracking
  api_counting: false              # Use Anthropic API for exact counts (requires API key)
  cache_enabled: true              # Cache token counts to avoid re-counting
  cache_ttl_seconds: 3600          # Cache time-to-live in seconds (60-86400)
  fallback_chars_per_token: 4.0    # Heuristic ratio when API counting is off (1.0-10.0)

Each worker writes token usage to .zerg/state/tokens-{worker_id}.json with per-task breakdowns (command template, task context, repo map, security rules, spec excerpt). Use /zerg:status to view aggregate token consumption across workers. When api_counting is enabled, the Anthropic count_tokens API provides exact counts; otherwise a character-based heuristic (len(text) / fallback_chars_per_token) is used.

Error Recovery

error_recovery:
  circuit_breaker:
    enabled: true
    failure_threshold: 3       # Failures before tripping (1-20)
    cooldown_seconds: 60       # Recovery wait time (5-600)
  backpressure:
    enabled: true
    failure_rate_threshold: 0.5  # Rate to trigger throttling (0.1-1.0)
    window_size: 10              # Rolling window size (3-100)

---

Environment Variables

Required

ZERG-Specific (Set by Orchestrator)

Optional

---

Container Mode

Setup

# 1. Initialize with container support
zerg init --with-containers

# 2. Build the devcontainer image
devcontainer build --workspace-folder .

# 3. Run with container mode
zerg rush --mode container --workers 5

Authentication

Container workers authenticate via two methods:

Container Configuration

The devcontainer is configured at .devcontainer/devcontainer.json:

{
  "name": "project-zerg",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "mounts": [
    "source=${localWorkspaceFolder},target=/workspace,type=bind",
    "source=zerg-claude-tasks,target=/root/.claude/tasks,type=volume"
  ],
  "containerEnv": {
    "CLAUDE_CODE_TASK_LIST_ID": "${localEnv:ZERG_FEATURE}",
    "ZERG_WORKER_ID": "${localEnv:ZERG_WORKER_ID:-0}"
  }
}

Docker Network

Container mode creates a zerg-internal Docker network for worker isolation. Workers communicate via state files mounted from the host.

---

Tuning Guide

For Speed

workers:
  default_count: 8       # More workers
  timeout_seconds: 1800  # Shorter timeout
  context_threshold: 0.8 # Use more context before checkpoint

For Reliability

workers:
  default_count: 3          # Fewer workers, less contention
  retry_attempts: 5         # More retries
  context_threshold: 0.6    # Checkpoint earlier

quality_gates:
  lint:
    required: true
  typecheck:
    required: true
  test:
    required: true

For Large Features

workers:
  default_count: 10
  max_count: 10
  timeout_seconds: 7200  # 2 hours per worker

For CI/CD

workers:
  default_count: 5
  timeout_seconds: 3600

quality_gates:
  lint:
    command: "ruff check . --select ALL"
    required: true
  test:
    command: "pytest --cov --cov-fail-under=80"
    required: true
  security:
    command: "bandit -r src/"
    required: true

---

Directory Structure Reference

.zerg/
├── config.yaml              # Main configuration file
├── hooks/
│   └── pre-commit           # Pre-commit hook script
├── state/
│   ├── {feature}.json       # Runtime state per feature
│   ├── heartbeat-{id}.json  # Per-worker heartbeat (worker intelligence)
│   ├── progress-{id}.json   # Per-worker progress (worker intelligence)
│   └── escalations.json     # Shared escalation file (worker intelligence)
└── logs/
    ├── workers/
    │   └── worker-{id}.jsonl  # Structured per-worker logs
    ├── tasks/
    │   └── {TASK-ID}/         # Per-task artifacts
    │       ├── execution.jsonl
    │       ├── claude_output.txt
    │       ├── verification_output.txt
    │       └── git_diff.patch
    └── orchestrator.jsonl     # Orchestrator log