Documentation

config.toml

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

config.toml is deliberately small. It parses four sections and nothing else: [assistant], [telemetry], [tools], and [restrictions]. Rules, thresholds, engine tuning, output filters, and git_readonly all live in rules.toml — putting them here has no effect.

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

[tools]
# Recorded by `warden init`. Actual availability is probed from PATH.
# rg = true
# fd = true
# bat = true

[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
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
read_suppression = true        # Withhold byte-identical re-reads

Field Reference

Key	Type	Default	Description
`assistant.type`	string	`"auto"`	Which host to target. `"auto"` detects from the environment.
`tools.<name>`	bool	detected	Written by `warden init` as a record of what it found. Whether a substitution actually fires is decided by probing PATH for the target tool, cached and re-probed daily — not by this table.
`telemetry.anomaly_detection`	bool	`true`	Notice when a turn looks unlike the rest of the session.
`telemetry.quality_predictor`	bool	`true`	Flag a session that is heading somewhere unproductive, early.
`telemetry.cost_tracking`	bool	`true`	Warn when a session is spending unusually heavily.
`telemetry.token_forecast`	bool	`true`	Warn before the context window runs out.
`telemetry.smart_truncation`	bool	`true`	Trim verbose command output to the part that matters.
`telemetry.project_dna`	bool	`true`	Remember what is normal for this project across sessions.
`telemetry.rule_effectiveness`	bool	`true`	Track which rules actually change outcomes.
`telemetry.drift_velocity`	bool	`true`	Notice when work wanders away from the stated goal.
`telemetry.compaction_optimizer`	bool	`true`	Improve what survives a context compaction, session over session.
`telemetry.command_recovery`	bool	`true`	Offer the next thing to try after a failure.
`telemetry.read_suppression`	bool	`true`	Withhold the payload of a re-read whose content is byte-identical and still in context, rather than advising against it and serving it anyway.

The telemetry keys control which intelligence modules are active. Disabling a module removes its signal from session health scoring and advisory generation. For example, setting drift_velocity = false means drift won’t generate advisories.

features.toml wins

Feature flags also live in ~/.warden/features.toml under a [features] table, with exactly the keys above. When that file exists, its [features] table replaces [telemetry] wholesale. config.toml [telemetry] still works for anyone who already had it, but features.toml is where new settings belong.

warden --debug features

prints every flag with its effective value and which file it came from — default, config.toml (deprecated), or features.toml.

What Does Not Belong Here

These are the mistakes that look plausible and silently do nothing:

Wrong	Right
`[thresholds]` in config.toml	`[thresholds]` in `rules.toml`
`[loopbreaker]`, `[compass]`, `[focus]`, `[dream]`, `[oversight]`	all in `rules.toml` — see Thresholds
`git_readonly = true` in config.toml	top-level key in `rules.toml`
`[[command_filters]]` in config.toml	in `rules.toml`
`[restrictions] disabled = [...]`	`[restrictions] disable = [...]` in `rules.toml`

config.toml does parse a [restrictions] table, but the live disable list is the disable key in rules.toml. That is what warden --debug restrictions disable <id> writes to, and what the merge reads.

Disabling a Rule

# ~/.warden/rules.toml
[restrictions]
disable = ["substitution.cat", "read.post-edit"]

Not every rule can be disabled. IDs in the safety, destructive, hallucination, zero_trace, permission, and git_readonly namespaces are refused — they are the immutable floor. A project-level .warden/rules.toml is narrower still: it may only disable substitution.* and advisory.*, so cloning a repository can never switch off enforcement.

Run warden --debug restrictions list to see every rule ID and whether it is disableable.