config-reference.md

agent-fox Configuration Reference

This document lists every configuration option supported by agent-fox. The simplified config.toml generated by agent-fox init contains only the most commonly changed settings. Add any section below manually to config.toml to override the defaults.

Table of Contents

• paths
• orchestrator
• routing
• models
• security
• theme
• platform
• knowledge
• archetypes
  • archetypes.instances
  • archetypes.reviewer_config
• pricing
• planning
• blocking
• night_shift
• caching

---

paths

Controls project directory locations.

Field	Type	Default	Bounds	Description
spec_root	str	".agent-fox/specs"	—	Spec root directory relative to project root. Legacy projects using .agent-fox/specs/ are auto-detected with a deprecation warning.

[paths]
spec_root = ".agent-fox/specs"

---

orchestrator

Controls the orchestration loop: parallelism, retries, timeouts, and quality gates.

Field	Type	Default	Bounds	Description
parallel	int	2	1–8	Maximum number of parallel coding sessions
quality_gate	str	""	—	Shell command run after each coder session to verify code quality (e.g. "make check")
max_budget_usd	float	2.0	≥ 0	Per-session spend cap in USD; 0 means unlimited
sync_interval	int	5	≥ 0	Task-group sync interval in number of sessions
hot_load	bool	true	—	Hot-reload spec files between sessions without restarting the orchestrator
max_retries	int	2	≥ 0	Maximum number of automatic retries per task group
session_timeout	int	30	≥ 1	Per-session timeout in minutes
inter_session_delay	int	3	≥ 0	Delay in seconds between consecutive session launches
max_cost	float|null	null	—	Hard cost ceiling for the entire run (null = no limit)
max_sessions	int|null	null	—	Maximum total sessions in a run (null = no limit)
audit_retention_runs	int	20	≥ 1	Number of run audit logs to retain on disk
max_blocked_fraction	float|null	null	0.0–1.0	Abort the run when this fraction of nodes are blocked; null disables
max_review_fraction	float	0.34	0.0–1.0	Maximum fraction of parallel slots for review sessions; auto_pre nodes exempt
quality_gate_timeout	int	300	—	Timeout in seconds for the quality-gate command
causal_context_limit	int	200	10–10000	Maximum prior facts included in causal extraction prompts
watch_interval	int	60	≥ 10	Seconds between polls in --watch mode

Example:

[orchestrator]
parallel = 4
quality_gate = "make check"
max_budget_usd = 10.0
session_timeout = 45
max_retries = 3

---

routing

Adaptive model routing configuration. Controls when the orchestrator escalates to a more capable model tier based on past session outcomes.

Note: This is a hidden section — it does not appear in the simplified template. Add it manually when you want to tune routing behaviour.

Field	Type	Default	Bounds	Description
retries_before_escalation	int	1	0–3	Failed retries before escalating to the next model tier
training_threshold	int	20	5–1000	Minimum outcome records needed before routing model training
accuracy_threshold	float	0.75	0.5–1.0	Minimum routing accuracy to trust the trained model
retrain_interval	int	10	5–100	Number of new outcomes between routing model retrains
max_timeout_retries	int	2	≥ 0	Maximum timeout retries before falling through to escalation (0 = disable timeout handling)
timeout_multiplier	float	1.5	≥ 1.0	Factor by which max_turns and session_timeout are extended on each timeout retry
timeout_ceiling_factor	float	2.0	≥ 1.0	Maximum session_timeout as a multiple of the original configured value

Example:

[routing]
retries_before_escalation = 2
training_threshold = 50
accuracy_threshold = 0.80
retrain_interval = 20
max_timeout_retries = 3
timeout_multiplier = 1.5
timeout_ceiling_factor = 2.0

---

models

Selects the model tier for each task category. Valid tier values are "SIMPLE", "STANDARD", and "ADVANCED".

Field	Type	Default	Bounds	Description
coding	str	"ADVANCED"	—	Model tier for coding tasks: SIMPLE, STANDARD, or ADVANCED
memory_extraction	str	"SIMPLE"	—	Model tier for memory/fact extraction
fallback_model	str	"claude-sonnet-4-6"	—	Fallback model ID when the primary model is unavailable

Example:

[models]
coding = "ADVANCED"
memory_extraction = "SIMPLE"
fallback_model = "claude-sonnet-4-6"

---

security

Controls the bash command allowlist that agent sessions may execute.

Field	Type	Default	Bounds	Description
bash_allowlist	list[str]|null	null	—	Full replacement allowlist (null uses the built-in list)
bash_allowlist_extend	list[str]	[]	—	Additional commands appended to the built-in allowlist

Example:

[security]
bash_allowlist_extend = ["my-custom-tool", "deploy.sh"]

---

theme

Rich text styles for terminal output. Values use Rich markup syntax.

Note: This is a hidden section — add it manually to customise colours.

Field	Type	Default	Bounds	Description
playful	bool	true	—	Enable playful emoji/banner output style
header	str	"bold #ff8c00"	—	Style for section headers
success	str	"bold green"	—	Style for success messages
error	str	"bold red"	—	Style for error messages
warning	str	"bold yellow"	—	Style for warning messages
info	str	"#daa520"	—	Style for informational messages
tool	str	"bold #cd853f"	—	Style for tool/command output
muted	str	"dim"	—	Style for secondary/muted text

Example:

[theme]
playful = false
header = "bold blue"
success = "green"

---

platform

Issue-tracker integration. Set type = "github" to enable GitHub Issues support for the af-fix skill.

Note: This is a hidden section.

Field	Type	Default	Bounds	Description
type	str	"none"	—	Platform type: "none" or "github"
url	str	""	—	Issue tracker base URL (inferred from type when left empty)

Example:

[platform]
type = "github"
url = "https://github.com/my-org/my-repo"

---

knowledge

Knowledge store and semantic search configuration. The knowledge store persists facts learned across sessions for use as context in future sessions.

Note: This is a hidden section.

Field	Type	Default	Bounds	Description
store_path	str	".agent-fox/knowledge.duckdb"	—	Path to the DuckDB knowledge store file
embedding_model	str	"all-MiniLM-L6-v2"	—	Sentence-transformers model used for fact embeddings
embedding_dimensions	int	384	—	Dimensionality of embedding vectors
ask_top_k	int	20	≥ 1	Number of top-ranked facts returned by knowledge queries
ask_synthesis_model	str	"STANDARD"	—	Model tier used to synthesise query answers
confidence_threshold	float	0.5	0.0–1.0	Minimum similarity score for fact inclusion in session context
fact_cache_enabled	bool	true	—	Pre-compute fact rankings at plan time for faster session start
dedup_similarity_threshold	float	0.92	—	Cosine similarity threshold for near-duplicate detection
contradiction_similarity_threshold	float	0.8	—	Cosine similarity threshold for contradiction candidates
contradiction_model	str	"SIMPLE"	—	Model tier for contradiction classification LLM calls
decay_half_life_days	float	90.0	—	Days for fact confidence to halve
decay_floor	float	0.1	—	Effective confidence below which facts are auto-superseded
cleanup_fact_threshold	int	500	—	Active fact count above which decay cleanup runs
cleanup_enabled	bool	true	—	Enable/disable end-of-run fact lifecycle cleanup
retrieval	table	—	—	Adaptive retrieval tuning parameters (see [knowledge.retrieval])
sleep	table	—	—	Sleep-time compute configuration (see [knowledge.sleep])
provider	table	—	—	Knowledge provider configuration (see [knowledge.provider])

knowledge.provider

Configuration for the pluggable knowledge provider (spec 115). Controls retrieval limits, gotcha TTL, and the LLM model tier used for gotcha extraction.

Field	Type	Default	Description
max_items	int	10	Max total retrieval items across all categories
gotcha_ttl_days	int	90	Days before gotcha expiry
model_tier	str	"SIMPLE"	LLM tier for gotcha extraction

Example:

[knowledge.provider]
max_items = 10
gotcha_ttl_days = 90
model_tier = "SIMPLE"

knowledge.sleep

Configuration for the sleep-time compute pipeline (spec 112). Controls pre-computation of context blocks and retrieval bundles during idle periods.

Field	Type	Default	Description
enabled	bool	true	Enable/disable sleep compute globally
max_cost	float	1.0	Maximum LLM cost (USD) per sleep compute invocation
nightshift_interval	int	1800	Seconds between nightshift sleep compute runs
context_rewriter_enabled	bool	true	Enable context re-representation task
bundle_builder_enabled	bool	true	Enable retrieval bundle builder task

Example:

[knowledge.sleep]
enabled = true
max_cost = 0.50
nightshift_interval = 3600

knowledge.retrieval

Tuning parameters for the unified adaptive retriever (spec 104). Controls multi-signal RRF fusion, token budgeting, and per-signal candidate caps.

Field	Type	Default	Description
rrf_k	int	60	RRF smoothing constant (denominator offset)
max_facts	int	50	Maximum facts in the fused anchor set
token_budget	int	30000	Maximum characters for the formatted context block
keyword_top_k	int	100	Candidate cap for the keyword signal
vector_top_k	int	50	Candidate cap for the vector signal
entity_max_depth	int	2	Max BFS traversal depth for entity signal
entity_max_entities	int	50	Max entities traversed in entity signal
causal_max_depth	int	3	Max traversal depth for causal signal

Example:

[knowledge]
ask_top_k = 30
confidence_threshold = 0.6
fact_cache_enabled = true
cleanup_enabled = true
decay_half_life_days = 90

[knowledge.retrieval]
rrf_k = 60
max_facts = 50
token_budget = 30000

---

archetypes

Archetype enable/disable toggles and per-archetype advanced configuration.

After the reviewer consolidation, the former skeptic, oracle, and auditor archetypes are unified into a single reviewer archetype with mode-based behaviour (pre-review, drift-review, audit-review, fix-review).

Field	Type	Default	Bounds	Description
coder	bool	true	—	Enable the Coder archetype
reviewer	bool	true	—	Enable the Reviewer archetype (replaces skeptic, oracle, auditor)
verifier	bool	true	—	Enable the Verifier archetype (post-code correctness checks)
instances	table	see below	—	Per-archetype instance counts
reviewer_config	table	see below	—	Reviewer-specific configuration (replaces skeptic_config, oracle_settings, auditor_config)
models	dict[str, str]	{}	—	Per-archetype model tier overrides (e.g. {coder = "STANDARD"})
allowlists	dict[str, list[str]]	{}	—	Per-archetype extra bash command allowlists
max_turns	dict[str, int]	{}	—	Per-archetype maximum turn limits (≥ 0)
thinking	dict[str, ThinkingConfig]	{}	—	Per-archetype extended thinking configuration
overrides	dict[str, PerArchetypeConfig]	{}	—	Per-archetype config overrides (model_tier, max_turns, allowlist, modes)
custom	list[CustomArchetypeConfig]	[]	—	Custom archetype definitions

Example:

[archetypes]
reviewer = true
verifier = true
# Override model tiers per archetype
models = {coder = "STANDARD", reviewer = "ADVANCED"}

# Limit turns for specific archetypes
max_turns = {coder = 100, verifier = 50}

archetypes.instances

Controls how many parallel instances of each archetype are spawned.

Field	Type	Default	Bounds	Description
reviewer	int	1	1–5	Number of parallel Reviewer instances
verifier	int	1	1	Number of Verifier instances (always clamped to 1)

Example:

[archetypes.instances]
reviewer = 2

archetypes.reviewer_config

Reviewer-specific configuration, consolidating settings for all review modes.

Field	Type	Default	Bounds	Description
pre_review_block_threshold	int	3	≥ 0	Finding count to block merge for pre-review mode
drift_review_block_threshold	int|null	null	≥ 1	Drift count to block for drift-review mode; null = advisory only
audit_min_ts_entries	int	5	≥ 1	Minimum test-spec entries to trigger audit-review injection
audit_max_retries	int	2	≥ 0	Maximum audit-review retry iterations

Example:

[archetypes.reviewer_config]
pre_review_block_threshold = 5
audit_min_ts_entries = 3
audit_max_retries = 1

---

pricing

Custom per-model pricing for cost tracking. By default agent-fox ships with pricing for the standard Claude models. Override here when using custom deployments or when Anthropic updates prices.

Note: This is a hidden section.

Field	Type	Default	Description
models	dict[str, ModelPricing]	(see below)	Per-model pricing entries

Each entry in models is a TOML inline table or sub-table with these fields:

Sub-field	Type	Default	Bounds	Description
input_price_per_m	float	0.0	≥ 0	USD per million input tokens
output_price_per_m	float	0.0	≥ 0	USD per million output tokens
cache_read_price_per_m	float	0.0	≥ 0	USD per million cache-read input tokens
cache_creation_price_per_m	float	0.0	≥ 0	USD per million cache-creation input tokens

Built-in defaults:

Model	Input $/M	Output $/M	Cache read $/M	Cache creation $/M
claude-haiku-4-5	1.00	5.00	0.10	1.25
claude-sonnet-4-6	3.00	15.00	0.30	3.75
claude-opus-4-5	5.00	25.00	0.50	6.25
claude-opus-4-6	5.00	25.00	0.50	6.25

Example (override a single model's pricing):

[pricing.models.claude-sonnet-4-6]
input_price_per_m = 3.00
output_price_per_m = 15.00
cache_read_price_per_m = 0.30
cache_creation_price_per_m = 3.75

---

planning

Controls task scheduling, duration prediction, and file-conflict detection.

Note: This is a hidden section.

Field	Type	Default	Bounds	Description
duration_ordering	bool	true	—	Sort ready tasks by predicted duration (shortest first)
min_outcomes_for_historical	int	10	1–1000	Minimum session outcomes before using historical duration data
min_outcomes_for_regression	int	30	5–10000	Minimum outcomes before training the duration regression model
file_conflict_detection	bool	false	—	Detect and defer tasks that edit the same files in parallel

Example:

[planning]
duration_ordering = true
file_conflict_detection = true
min_outcomes_for_historical = 15

---

blocking

Threshold learning for the blocking subsystem. When enabled, the orchestrator learns from past blocking decisions to auto-tune its thresholds.

Note: This is a hidden section.

Field	Type	Default	Bounds	Description
learn_thresholds	bool	false	—	Enable automatic blocking threshold learning from history
min_decisions_for_learning	int	20	1–1000	Minimum blocking decisions before learning begins
max_false_negative_rate	float	0.1	0.0–1.0	Maximum acceptable false-negative rate for the learned thresholds

Example:

[blocking]
learn_thresholds = true
min_decisions_for_learning = 50
max_false_negative_rate = 0.05

---

night_shift

Daemon configuration for the night-shift background scan mode (agent-fox night-shift). Night-shift periodically scans for issues such as stale dependencies, TODO debt, and linter violations.

Note: This is a hidden section.

Field	Type	Default	Bounds	Description
issue_check_interval	int	900	≥ 60	Seconds between issue-tracker checks
hunt_scan_interval	int	14400	≥ 60	Seconds between full hunt scans
quality_gate_timeout	int	600	≥ 60	Per-check timeout in seconds
categories	table	(all enabled)	—	Per-category enable/disable toggles
spec_interval	int	60	≥ 10	Seconds between spec executor cycles
enabled_streams	list	["specs","fixes","hunts"]	—	List of enabled work stream names
merge_strategy	string	"direct"	—	Merge strategy: direct or pr
push_fix_branch	bool	false	—	Push fix branches to origin before harvest

night_shift.categories

Field	Type	Default	Description
dependency_freshness	bool	true	Scan for stale or outdated dependencies
todo_fixme	bool	true	Scan for TODO/FIXME comments
test_coverage	bool	true	Check test coverage metrics
deprecated_api	bool	true	Detect usage of deprecated APIs
linter_debt	bool	true	Surface accumulated linter warnings
dead_code	bool	true	Identify unreachable or unused code
documentation_drift	bool	true	Detect stale or missing documentation
quality_gate	bool	true	Run the project's quality-gate command

Example:

[night_shift]
issue_check_interval = 1800
hunt_scan_interval = 7200
quality_gate_timeout = 300

[night_shift.categories]
dead_code = false
documentation_drift = false

---

caching

Prompt caching configuration. Controls whether cache_control markers are injected into Anthropic API requests, reducing input token costs on cache hits.

Field	Type	Default	Description
cache_policy	str	"DEFAULT"	Caching strategy: NONE, DEFAULT (5-min TTL), or EXTENDED (1-hour TTL)

Policies:

Policy	cache_control marker	TTL	Cost trade-off
NONE	None	—	No caching — identical behaviour to pre-caching releases
DEFAULT	{"type": "ephemeral"}	5 minutes	Reduces input costs on repeated calls within a short window
EXTENDED	{"type": "ephemeral", "ttl": "1h"}	1 hour	Higher cache-write cost; pays off on long-running sessions

Token threshold: Caching is automatically skipped when the system prompt is estimated to be below the model's minimum cacheable size (≈2 048 tokens for Sonnet-class models, ≈4 096 for Opus/Haiku-class). Prompts below this threshold are passed through unchanged regardless of policy.

Example:

[caching]
cache_policy = "DEFAULT"   # NONE | DEFAULT | EXTENDED

Rollback: Set cache_policy = "NONE" to fully disable caching with no code changes required.

---

For the simplified quick-start config, run agent-fox init.