Configuration Reference

Guild works without any configuration. .guild/settings.json exists only when you want to override a default — absent keys fall back to the built-in defaults, and parse errors never block a run (they print a warning and fall back).

Generate a fully-documented scaffold: /guild:config init
Inspect the resolved config: /guild:config show
Validate against the closed-key set: npx tsx scripts/read-guild-config.ts --validate

Precedence ladder

From highest priority (first wins) to lowest:

1. CLI flag  (--rigor=deep, --agent-mode=team, --model-tier=cheap …)
2. --rigor profile expansion  (fills only keys NOT set explicitly)
3. .guild/settings.json
4. Built-in defaults

Model-tier only: --model-tier=cheap|mid|powerful → per-lane plan model_tier: override → models.tiers + models.thresholds → built-in map.

Top-level keys

Rigor profiles

rigor fills loops, loop_cap, and review only for keys you did not set explicitly (in settings.json or as a CLI flag). Explicit values always win.

The resolved expansion is visible as _rigor_expanded in --validate output and in the JSON returned by read-guild-config.ts.

Agent-mode dispatch ladder

agent_mode: "auto" resolves at runtime in this order — team and independent agents are primary; subagent is the last resort:

Pinning agent_mode: "team" on a tmux-less host is rejected with a warning.

defaults.agent_team is a deprecated alias (warn-once). Migration: auto→auto, on→team, off→subagent. Removed at v2.1.0.

Example:

{ "agent_mode": "subagent" }

models.* — Cost tiering

Canonical ADR: cost-aware-tiering-and-lean-context (§1 tiers · §2 auto-score · §3 advisor · §4 recall · §5 handoff · §6 lifecycle · §8 learn · §10 config)

Closed key set — unknown models.* keys are rejected by --validate.

Default tier map

{
  "models": {
    "tiers": {
      "cheap":    { "claude": "haiku",  "codex": null, "gemini": null },
      "mid":      { "claude": "sonnet", "codex": null, "gemini": null },
      "powerful": { "claude": "opus",   "codex": null, "gemini": null }
    }
  }
}

codex and gemini slots are null pending those adapters; they slot in as config + adapter when available.

Default score weights

{
  "models": {
    "scoreWeights": {
      "workType":        0,
      "blastRadius":     1,
      "dependsOn":       1,
      "security":        1,
      "priorEscalation": 1
    }
  }
}

workType is a base offset: read/summarize = +0, draft/extract = +1, architect/review/schema = +2. The other weights are additive per signal.

Default escalation markers

{
  "models": {
    "escalationMarkers": [
      "I'm not sure",
      "unclear",
      "cannot determine",
      "I don't know",
      "ambiguous",
      "uncertain",
      "not enough information"
    ]
  }
}

Example — tune thresholds, reduce advisor rounds:

{
  "models": {
    "thresholds": { "mid": 2, "powerful": 4 },
    "advisorRounds": 1
  }
}

O-3 calibration buckets

ADR: v2-observability-and-replay §D-OBS-3

The O-3 “anomalously short output” advisor trigger fires when a lane’s output token count falls below the p10 baseline for that (task_type, tier) bucket. Thresholds are not built-in — derive them from ≥ 30 run samples and land them here manually.

Workflow:

1. Run npx tsx benchmark/src/calibrate-o3-cli.ts (after sufficient samples).
2. The CLI prints a models.shortOutputThreshold JSON fragment with proposed floors.
3. Review and merge the proposal into .guild/settings.json.
4. Nothing auto-writes this key. All writes are explicit.

Until a (task_type, tier) pair appears in this map, the O-3 trigger is silent for that bucket.

Example (after calibration on a mature repo):

{
  "models": {
    "shortOutputThreshold": {
      "build":  { "cheap": 80,  "mid": 150, "powerful": 200 },
      "review": { "cheap": 120, "mid": 200, "powerful": 300 },
      "plan":   { "mid": 180,   "powerful": 250 }
    }
  }
}

Malformed entries (non-object task-type values, non-number tier values) are silently dropped — a partial calibration proposal never hard-blocks config load.

security.* — bypassPermissions governance

ADR: v2-security-and-untrusted-content (D-BYPASS)

Closed key set — only bypass_permissions_policy is valid.

Example:

{ "security": { "bypass_permissions_policy": "deny" } }

secrets_policy.* — Secrets redaction

ADR: v2-security-and-untrusted-content (D-SECRETS)

Closed key set.

Example:

{
  "secrets_policy": {
    "env_allowlist": ["GITHUB_TOKEN"],
    "redaction_patterns": ["sk-[A-Za-z0-9]{32,}"],
    "fail_mode_durable": "closed",
    "fail_mode_telemetry": "open"
  }
}

mcp.* — MCP description pinning

ADR: v2-security-and-untrusted-content (D-MCP, PI-6)

Closed key set — only tool_description_hashes is valid.

defaults.* — Per-run behavioral defaults

The defaults block configures default posture for each Guild run. All keys deep-merge: absent sub-keys inherit the built-in defaults.

defaults.index.* — SQLite lazy-cache thresholds

ADR: v2-persistence-and-sqlite-index (D-PS-1)

Closed key set. These thresholds determine when the lazy index.sqlite cache is populated. Below each threshold, the existing BM25 grep path is used unchanged.

Example — disable index for a small repo:

{
  "defaults": {
    "index": { "enabled": false }
  }
}

defaults.cross_host.* — Cross-host SSH routing

ADR: v2-cross-host-orchestration (CR-1 / CH-1)

Security: address/port/user only — no secrets, no passwords, no key paths. SSH authentication must use keys or the ssh-agent socket (~/.ssh/config or SSH_AUTH_SOCK). The validator hard-rejects any key other than address, port, and user on each host entry.

Example:

{
  "defaults": {
    "cross_host": {
      "enabled": true,
      "hosts": {
        "codex-worker-1": {
          "address": "192.168.1.50",
          "port": 2222,
          "user": "guild"
        }
      }
    }
  }
}

Never add password, private_key, key_path, or any credential to a host entry. The validator rejects unknown host-entry keys.

Complete minimal example

{
  "agent_mode": "auto",
  "rigor": "standard",
  "review": "local",
  "codex_cap": 5,
  "loop_cap": 16,
  "models": {
    "enabled": true,
    "thresholds": { "mid": 1, "powerful": 3 },
    "advisorRounds": 2,
    "recallScoreThreshold": 0.4,
    "importanceGate": 3
  },
  "security": {
    "bypass_permissions_policy": "audit"
  },
  "defaults": {
    "auto_learn": false,
    "adversarial": "on",
    "wiki": { "share_mode": "team", "autopromote": false },
    "index": { "enabled": true },
    "cross_host": { "enabled": false, "hosts": {} }
  }
}

Validation and tooling

Migration from v1 config.yml

.guild/config.yml is read via a one-time back-compat shim when settings.json is absent. Once settings.json exists it is authoritative and config.yml is ignored. Run /guild:config init to migrate. See the v1 → v2 migration guide §3.

Related

• Cost-Aware Model Tiering — tier ladder, auto-score signals, and advisor escalation in depth.
• Architecture & Lifecycle — agent_mode dispatch in context of the full lifecycle.
• v1 → v2 Migration — complete key mapping and breaking changes.