Configuration

Warden works out of the box with zero configuration. For customization, there are two layers: the config file (config.toml) controls general settings, and the rules files (rules.toml) control pattern matching, thresholds, and rule overrides.

config.toml Reference

Located at ~/.warden/config.toml. All fields have sensible defaults — a missing file or missing field is handled gracefully.

[assistant]
type = "auto"  # "claude-code", "gemini-cli", or "auto"

[restrictions]
disabled = []  # Rule IDs to disable, e.g. ["substitution.0", "substitution.2"]

[telemetry]
anomaly_detection = true      # Detect unusual command patterns
quality_predictor = true       # Predict session quality from early signals
cost_tracking = true           # Track token costs per session
error_prevention = true        # Proactive error avoidance
token_forecast = true          # Estimate remaining context budget
smart_truncation = true        # Adaptive output compression
project_dna = true             # Learn project-specific patterns
rule_effectiveness = true      # Track which rules improve outcomes
drift_velocity = true          # Monitor session goal drift
compaction_optimizer = true    # Optimize context compaction behavior
command_recovery = true        # Suggest recovery after command failures

The telemetry keys control which intelligence modules are active. Disabling a module removes its signal from the trust score calculation and the injection budget. For example, setting drift_velocity = false means drift won’t contribute to trust decay and won’t generate advisories. See Session Intelligence for how trust scores and the injection budget use these signals.

The 3-Tier Override Model

Rules come from three sources, merged in order:

1. Compiled defaults — baked into the binary under config/core/. These are the immutable floor. Safety rules at this tier cannot be disabled.
2. Global rules (~/.warden/rules.toml) — your personal overrides across all projects. Add custom patterns, disable non-critical rules, adjust thresholds.
3. Project rules (.warden/rules.toml in the project root) — per-project overrides. Team conventions, project-specific safety rules, custom filters.

Each tier merges on top of the previous one. By default, patterns from a TOML file are appended to the compiled defaults. Setting replace = true in a section replaces the compiled defaults entirely for that category.

# ~/.warden/rules.toml — example global override

[safety]
# Append a custom safety rule (default: replace = false)
patterns = [
  { match = "DROP TABLE", msg = "BLOCKED: DROP TABLE in raw SQL. Use migrations." }
]

[substitutions]
# Replace ALL compiled substitutions with your own list
replace = true
patterns = [
  { match = "\\bgrep\\s", msg = "Use rg instead of grep." }
  # Only grep→rg, no other substitutions
]

Common Configuration Tasks

Disable a specific substitution:

# In ~/.warden/config.toml
[restrictions]
disabled = ["substitution.0"]  # Stops grep → rg redirection

Add a custom safety rule:

# In ~/.warden/rules.toml or .warden/rules.toml
[safety]
patterns = [
  { match = "DROP DATABASE", msg = "BLOCKED: DROP DATABASE. Use migration rollbacks." },
  { match = "TRUNCATE TABLE", msg = "BLOCKED: TRUNCATE TABLE. Too destructive for AI." }
]

Add a shadow-mode rule for testing:

[hallucination]
patterns = [
  { match = "my-suspicious-pattern", msg = "Would block this pattern", shadow = true }
]

Shadow-mode rules log but don’t block. Check warden stats to see if they would have fired correctly before removing the shadow = true.

Change thresholds:

[thresholds]
max_read_size = 100000        # Allow reading files up to 100KB (default: 50KB)
doom_loop_threshold = 6       # Detect loops after 6 cycles (default: 4)
stagnation_turns = 8          # Flag stagnation after 8 turns without progress

Set up project-level overrides:

Create .warden/rules.toml in your project root. This is committed to version control so the whole team shares the same rules:

# .warden/rules.toml — project-specific

[thresholds]
max_read_size = 80000  # This project has large generated files

[[command_filters]]
match = "my-build-tool"
strategy = "keep_matching"
keep = ["ERROR", "WARN", "FAIL"]

[safety]
patterns = [
  { match = "migrate:reset", msg = "BLOCKED: Full database reset. Use migrate:rollback." }
]

Enable git read-only mode for a project:

git_readonly = true

This blocks all mutating git commands (push, commit, merge, rebase, etc.) regardless of other settings.

Useful Commands

# Show the config file path
warden config path

# Print current config
warden config list

# Set a value
warden config set telemetry.drift_velocity false

# Get a specific value
warden config get assistant.type

# Output JSON Schema for config.toml
warden config schema

# Show all active rules, their IDs, severities, and state
warden describe

# Show all rules including compiled defaults
warden describe --all

Disabling Rules

If a specific rule doesn’t fit your workflow, disable it by ID:

# In ~/.warden/config.toml
[restrictions]
disabled = ["substitution.0", "substitution.2"]

Not all rules can be disabled. Safety rules with HardDeny severity are the immutable floor — they protect against rm -rf /, sudo, and other universally dangerous operations. Attempting to disable them has no effect.

Use warden describe to see all active rules, their IDs, and whether each one can be disabled. The can_disable column tells you which rules support this.