Configuration

Daydream reads repository configuration from two files at the repository root.

A pull request (PR) is a proposed change in a GitHub repository. The command-line interface (CLI) can override file configuration.

1. pyproject.toml provides the lower-priority [tool.daydream] table.
2. .daydream.toml provides higher-priority root keys.

Daydream merges the files by key. It merges phases by phase and field. It merges improve by key.

A missing file has no effect. A TOML syntax error stops most commands. post-findings reports a warning and uses default configuration after a syntax error.

Daydream validates configuration fields after it parses the files. An invalid field value usually uses the built-in default for that field.

pyproject.toml example

This is a valid Daydream configuration for pyproject.toml. Add these tables to an existing pyproject.toml file.

[tool.daydream]
backend = "codex"
reasoning_effort = "medium"
shallow_fanout_threshold = 2
precision_mode = true
approve_on_clean = false
group_max_wall_s = 600.0
group_max_serial_items = 6
uncovered_sweep = true
uncovered_sweep_max_files = 10
uncovered_sweep_min_hunk_lines = 5
quality_gate_enabled = true
quality_gate_erosion_delta = 0.05
quality_gate_verbosity_delta = 0.05
quality_gate_erosion_absolute = 0.05
quality_gate_verbosity_absolute = 0.05
supervisor = "rules"
supervisor_deny_globs = ["vendor/**", "generated/**"]
tool_supervisor = "rules"
tool_bash_deny = ["rm -rf"]
trajectory_hub_repo = "example-team/daydream-runs"

[tool.daydream.phases.review]
model = "gpt-5.6-sol"
reasoning_effort = "high"

[tool.daydream.phases.fix]
model = "gpt-5.6-terra"
reasoning_effort = "medium"

[tool.daydream.workspace]
copy = [".env", ".env.test"]

[tool.daydream.improve]
service_roots = ["apps/*", "services/*"]
partition_max_files = 400
max_partition_groups = 8

[tool.daydream.improve.service_groups]
web = ["apps/web", "packages/ui"]
workers = ["services/jobs", "services/queue"]

[tool.daydream.improve.github]
publish_issues = false

[tool.daydream.workspace]
copy = ["docs"]

.daydream.toml example

This is a separate and valid .daydream.toml example. Do not put the keys under [tool.daydream] in this file.

backend = "pi"
reasoning_effort = "high"
precision_mode = true
approve_on_clean = false
uncovered_sweep = true
supervisor = "off"
tool_supervisor = "off"

[phases.review]
model = "deepseek/deepseek-v4-flash-0731"

[phases.plan_write]
reasoning_effort = "max"

[improve]
service_roots = ["apps/*", "services/*"]
partition_max_files = 400
max_partition_groups = 8

[improve.service_groups]
web = ["apps/web", "packages/ui"]

[improve.github]
publish_issues = false

The .daydream.toml file does not support workspace copy configuration. Put [tool.daydream.workspace] in pyproject.toml.

Root configuration schema

Key	Type	Built-in default	Effect
backend	String	claude	Selects claude, codex, pi, or osprey.
model	String	Backend and phase default	Sets one model for all phases that do not have a higher-priority value.
reasoning_effort	String	Phase or backend default	Sets one reasoning level for all phases that do not have a higher-priority value.
phases	Table	Empty	Sets backend, model, and reasoning_effort by phase.
shallow_fanout_threshold	Integer	2	Uses one combined review assignment when the diff has no more than this number of files. 0 disables this change.
review_profile	Path string	Packaged default	Selects the repo-committed review profile file.
deep_shard_enabled	Boolean	Unset	Enables bounding of the deep-flow diff size.
deep_shard_max_files	Integer	Unset	Caps the file count for a deep-flow diff shard.
deep_shard_max_bytes	Integer	Unset	Caps the byte count for a deep-flow diff shard.
deep_shard_fanout_cap	Integer	Unset	Caps concurrent shard reviews.
deep_shard_frontier_max	Integer	Unset	Caps the shard frontier size.
precision_mode	Boolean	false	Runs a second review that can remove borderline findings.
approve_on_clean	Boolean	false	Posts a PR approval with zero high- or medium-severity findings. Low or omitted severity permits approval. An unrecognized severity blocks approval.
group_max_wall_s	Number	600.0	Limits cumulative fix time for one file group.
group_max_serial_items	Integer	6	Limits serial finding fixes for one file group.
uncovered_sweep	Boolean	true	Runs an additional review for eligible changed files that no stack reviewer read.
uncovered_sweep_max_files	Nonnegative integer	10	Limits files in the additional review. 0 disables the review.
uncovered_sweep_min_hunk_lines	Nonnegative integer	5	Sets the minimum changed lines for each additional file. 0 removes the minimum.
quality_gate_enabled	Boolean	true	Analyzes eligible fixed Python files for code erosion and verbosity growth.
quality_gate_erosion_delta	Nonnegative number	0.05	Sets the allowed increase from a defined erosion baseline.
quality_gate_verbosity_delta	Nonnegative number	0.05	Sets the allowed increase from a defined verbosity baseline.
quality_gate_erosion_absolute	Nonnegative number	0.05	Sets the erosion limit when no baseline exists.
quality_gate_verbosity_absolute	Nonnegative number	0.05	Sets the verbosity limit when no baseline exists.
supervisor	off, rules, or llm	off	Selects finding supervision.
supervisor_deny_globs	Array of strings	[]	Defines repository-relative wildcard patterns for finding and tool supervision.
tool_supervisor	off or rules	off	Selects built-in tool supervision.
tool_bash_deny	Array of strings	[]	Defines regular expressions for denied Bash commands.
trajectory_hub_repo	String	Unset	Selects a Hugging Face dataset repository for completed run bundles.
improve	Table	See Improve schema	Configures Improve service discovery, partitioning, and issue publication.

Boolean keys accept TOML booleans only. A Boolean value with another type uses the built-in default. Quality thresholds must be finite and nonnegative. An invalid quality threshold uses 0.05.

Phase names are strings. Built-in names include parse, exploration, per_stack_review, review, arbiter, suppression, supervise, wonder, merge, intent, fix, test, verify, pr_feedback, recon, audit, vet, and plan_write. An extension application programming interface (API) package can register more phase names.

Backend, model, and reasoning precedence

Daydream resolves each phase independently. Python API calls can supply direct phase overrides. CLI users can ignore the Python override level.

Backend precedence

The first available value wins:

1. A direct per-phase runtime override from the Python API.
2. The CLI --backend value.
3. The phase backend value in the merged file configuration.
4. The global backend value in the merged file configuration.
5. claude.

Model precedence

The first available value wins:

1. A direct per-phase runtime override from the Python API.
2. The CLI --model value.
3. The phase model value in the merged file configuration.
4. The global model value in the merged file configuration.
5. The built-in model for the resolved backend and phase.
6. The backend default model.

Reasoning precedence

The first available value wins:

1. The CLI --reasoning-effort value.
2. The phase reasoning_effort value in the merged file configuration.
3. The global reasoning_effort value in the merged file configuration.
4. The built-in reasoning value for the resolved backend and phase.
5. The reasoning setting from the selected backend.

The CLI has no phase-specific backend or model options. Use a phase table.

When both files set the same key or phase field, .daydream.toml has priority. A phase field has priority over a global file field. A global CLI value has priority over both files.

Built-in model tiers

Claude models

Phases	Model
parse	claude-haiku-4-5
fix, test, verify, exploration, per_stack_review, suppression, supervise, intent, recon, audit	claude-sonnet-5
review, arbiter, wonder, merge, pr_feedback, vet, plan_write	claude-opus-5

The Claude backend default is claude-opus-5 when a phase has no table entry. Claude accepts low, medium, high, xhigh, and max reasoning values.

Codex models

Phases	Model
parse	gpt-5.6-luna
fix, test, verify, exploration, per_stack_review, suppression, supervise, intent, recon, audit	gpt-5.6-terra
review, arbiter, wonder, merge, pr_feedback, vet, plan_write	gpt-5.6-sol

The Codex backend default is gpt-5.6-sol when a phase has no table entry.

Codex also accepts none as an explicit reasoning value. Pi also accepts off and minimal. Daydream does not use these extra values in built-in phase defaults.

Codex uses these review pipeline reasoning defaults:

Reasoning	Phases
low	parse, exploration
medium	fix, test, verify, suppression, supervise, merge, intent
high	per_stack_review, review, wonder, pr_feedback
xhigh	arbiter

Claude and Pi do not have built-in reasoning values for the review pipeline. They use their backend settings when no file or CLI value exists.

All three backends use these Improve reasoning defaults:

Phase	Reasoning
recon	low
audit	high
vet	xhigh
plan_write	max

Pi backend

Pi does not use phase model tiers. Pi uses one resolved model for each phase.

When Daydream does not set a model, Pi checks these sources in order:

1. TARGET/.pi/settings.json and its defaultModel value.
2. $PI_CODING_AGENT_DIR/settings.json and its defaultModel value.
3. ~/.pi/agent/settings.json and its defaultModel value.
4. deepseek/deepseek-v4-flash-0731 with the nous provider.

PI_CODING_AGENT_DIR replaces the default user settings directory. A project setting has priority over a user setting.

An explicit Daydream model uses PI_PROVIDER when that variable is set. It uses nous when the variable is not set. A Pi settings model keeps the provider selected by Pi.

PI_API_KEY is a convenience input. Daydream maps it to NOUS_API_KEY for nous. Daydream maps it to ZAI_API_KEY for zai. Daydream removes PI_API_KEY from the Pi child process. Set the provider's native credential variable for another provider.

A resolved Daydream reasoning value has priority over PI_THINKING. Daydream passes the value through Pi's --thinking option.

Pi read-only phases restrict tools to read, find, ls, and grep.

Pi looks for skills in these locations:

1. DAYDREAM_SKILLS_DIR.
2. ~/.agents/skills.
3. ~/.claude/skills.
4. The repository .agents/skills and .claude/skills directories.

Temporary workspace copy

Workspace copy copies local support files into a temporary Git worktree. It runs only for flows that can fix and test. Report-only and comment modes skip it.

Configure the copy list only in pyproject.toml:

[tool.daydream.workspace]
copy = [".env", ".env.test", "config/local.toml"]

Without this table, Daydream considers .env, .env.local, and every .env.* file. Daydream copies only existing regular files that Git ignores. Tracked files already exist in the worktree.

A configured copy array replaces the default list. Each CLI --copy PATH value adds one entry.

Every entry must be relative to the repository root. An entry cannot contain ... An entry cannot resolve outside the source or destination worktree. Daydream validates all entries before it copies any file. A failed validation stops the copy.

Daydream silently skips a configured entry that does not name an existing regular file.

Parallel review and additional-file review

A review fanout is a set of review assignments that run concurrently. shallow_fanout_threshold = 2 changes a small review to one combined assignment. The change applies when the diff has no more than two files. Daydream then skips cross-stack arbitration and merge. Set the key to 0 to use the normal fanout for every diff size.

An uncovered-file sweep is an additional review after the stack reviews. The sweep selects changed files that no stack reviewer read. A file must have the configured minimum changed lines. Daydream selects at most uncovered_sweep_max_files files.

Daydream records the sweep coverage. A sweep failure does not fail the review. A resumed merge or fix flow does not run the sweep.

A suppression pass is a second review that can remove unsupported findings. precision_mode = true runs this pass after finding merge. The pass checks borderline findings that have no conflicting review decision.

Finding supervision

supervisor = "off" keeps accepted merged findings unchanged.

supervisor = "rules" drops findings whose repository-relative paths match supervisor_deny_globs.

supervisor = "llm" sends merged findings to a batched language model supervisor. The supervisor can keep, drop, edit, or hold each finding.

Finding supervision runs before posting or fixing. It records its decisions in run artifacts.

Tool supervision

tool_supervisor = "rules" enables the built-in rule supervisor. It blocks Write and Edit calls for paths that match supervisor_deny_globs. It blocks Bash calls that match a regular expression in tool_bash_deny.

Use valid regular expressions. An invalid Bash expression stops the run.

An extension API package can register one tool supervisor. The built-in rule supervisor and an extension supervisor cannot run together. Daydream reports an extension error when both are enabled.

Quality analysis

The fix quality analysis checks changed *.py candidates. It silently skips a candidate that is absent from the Python metrics. The analysis checks code erosion and verbosity growth.

The delta thresholds apply when Daydream has a before-fix baseline. The absolute thresholds apply when a baseline does not exist.

The quality check records flagged files in deep/fix-quality-gate.json and in the run manifest. It also prints a warning. It does not stop the run. Tests remain the blocking validation step.

Set quality_gate_enabled = false to skip the calculations. Daydream still records that the check was disabled.

Agent and fix budgets

Budget	Default	Configuration
Standard agent call wall time	1800 seconds	Fixed runtime default
Test agent call wall time	3600 seconds	Fixed runtime default
Tool calls per agent call	Unlimited	Fixed runtime default
Cumulative fix time per file group	600 seconds	group_max_wall_s
Serial fixes per file group	6	group_max_serial_items

Daydream checks file-group budgets between fix calls. It sorts a group by severity. Items beyond the serial limit do not run.

Use a positive integer for group_max_serial_items. Use a nonnegative finite number for group_max_wall_s. A zero or negative practical budget can stop group work immediately.

Improve audit calls do not use the standard wall-time or tool-call budgets. The subprocess stream idle limit still applies to Codex and Pi.

Improve configuration

Key	Type	Default	Effect
improve.service_roots	Array of repository-relative wildcard patterns	[]	Defines service roots.
improve.service_groups.NAME	Array of repository-relative roots	[]	Defines a named group for --scope NAME.
improve.partition_max_files	Positive integer	400	Sets the maximum files in an automatic partition. partition-max-files is also accepted.
improve.max_partition_groups	Positive integer	Effort tier	Caps automatic groups. max-partition-groups is also accepted.
improve.github.publish_issues	Boolean	false	Publishes each validated plan as a GitHub issue. publish-issues is also accepted.

The quick effort uses one whole-repository group. The standard effort uses at most eight groups by default. The deep effort has no default group limit. A configured max_partition_groups replaces the effort value.

Issue publication requires authenticated gh access and repository issue permission. Daydream always writes the local plan before it tries issue publication.

Benchmark configuration

The legacy bench file-configuration section is removed. Daydream ignores a stale [tool.daydream.bench] section and prints a warning. Configure the private Harbor benchmark through the daydream benchmark commands. See Benchmarking.

Trajectory archive and upload

Daydream writes the primary Agent Trajectory Interchange Format (ATIF) trajectory to TARGET/.daydream/runs/SESSION_ID/trajectory.json by default. --trajectory PATH changes this location.

Daydream also assembles a central run bundle under ~/.daydream/archive. DAYDREAM_ARCHIVE_DIR changes the archive root. --no-archive disables the central archive.

The trajectory dataset repository uses this precedence:

1. CLI --trajectory-hub-repo.
2. DAYDREAM_TRAJECTORY_HUB_REPO.
3. File trajectory_hub_repo.

Upload requires a Hugging Face access token in HF_TOKEN. Upload also requires the optional huggingface_hub Python package. Daydream creates a missing dataset repository as private. Daydream keeps the visibility of an existing repository. It warns when an existing repository is public.

Each completed bundle uses its session ID as the dataset folder. Daydream does not upload a partial interrupted bundle. Upload failure reports a warning and does not fail the Daydream run.

--no-archive prevents trajectory upload. --dump-artifacts can still activate bundle assembly, but it does not override this upload block.

Pricing

Daydream reports a backend-provided cost when the backend supplies one. Otherwise, Daydream calculates cost from token counts and a price table. An unknown model has an unknown cost marker.

User prices have priority over built-in prices. Daydream finds the user price file in this order:

1. An explicit Python API path.
2. DAYDREAM_PRICES_FILE.
3. ~/.daydream/prices.toml.

Use this independent TOML format for a price file:

[prices."private-model"]
input = 1.25
cached_input = 0.25
output = 5.0

Rates are United States dollars per one million tokens. input and output are required. cached_input is optional and defaults to input. Every value must be finite and nonnegative. An invalid entry produces a warning and has no effect. A user entry replaces the complete built-in entry for that model.

The built-in effective rates in Daydream 0.27.0 are:

Model	Input	Cached input	Output
gpt-5.5	5.00	0.50	30.00
gpt-5.5-pro	30.00	30.00	180.00
gpt-5-codex	1.25	1.25	10.00
gpt-5.3-codex	1.75	1.75	14.00
gpt-5.6-sol	5.00	0.50	30.00
gpt-5.6-terra	2.50	0.25	15.00
gpt-5.6-luna	1.00	0.10	6.00
gpt-5.6	5.00	0.50	30.00
claude-sonnet-5	3.00	0.30	15.00
glm-5.2	1.40	0.26	4.40
deepseek/deepseek-v4-flash-0731	0.28	0.028	0.42

A gpt-5.6 request with more than 272,000 total input tokens uses twice the input and cached-input rate. It uses 1.5 times the output rate. This policy applies to gpt-5.6, gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna.

Environment variables

Authentication and providers

Variable	Use
ANTHROPIC_API_KEY	Authenticates Claude and the direct Anthropic judge route.
PI_PROVIDER	Selects a Pi provider.
PI_API_KEY	Supplies a convenience key for the nous or zai Pi provider.
NOUS_API_KEY	Supplies the native Nous credential.
ZAI_API_KEY	Supplies the native Z.ai credential.
PI_THINKING	Sets the Pi reasoning value when Daydream does not set one.
GH_TOKEN	Supplies non-interactive GitHub CLI authentication. An authenticated gh session also works.
DAYDREAM_APP_ID	Supplies the numeric GitHub App ID.
DAYDREAM_APP_PRIVATE_KEY	Supplies the GitHub App private key in Privacy-Enhanced Mail (PEM) format.
DAYDREAM_BOT_HANDLE	Supplies the GitHub App bot login for posting and deduplication.
HF_TOKEN	Authenticates Hugging Face trajectory upload.

Paths and discovery

Variable	Default	Use
DAYDREAM_ARCHIVE_DIR	~/.daydream/archive	Sets the central archive root.
DAYDREAM_TRAJECTORY_HUB_REPO	Unset	Selects the trajectory dataset repository.
DAYDREAM_PRICES_FILE	~/.daydream/prices.toml	Selects a user price file.
DAYDREAM_EXT_DIR	Import daydream_ext	Selects an extension API source directory.
DAYDREAM_SKILLS_DIR	User and repository skill directories	Adds the first Pi skill search location.
CLAUDE_CONFIG_DIR	~/.claude	Selects Claude configuration and the plugin registry.
PI_CODING_AGENT_DIR	~/.pi/agent	Selects Pi user settings.

Concurrency, retry, and timeout

Variable	Default	Use
DAYDREAM_FANOUT_CONCURRENCY	8	Sets the maximum concurrent Claude and Codex calls. A workflow can set a lower maximum.
DAYDREAM_PI_FANOUT_CONCURRENCY	10	Sets the maximum concurrent Pi calls. A workflow can set a lower maximum.
DAYDREAM_OSPREY_FANOUT_CONCURRENCY	4	Sets the maximum concurrent Osprey calls. A workflow can set a lower maximum.
OSPREY_BINARY	osprey	Names the Osprey program that the backend starts.
DAYDREAM_PI_RETRY_ATTEMPTS	20	Sets retry attempts after the first backend attempt. The setting applies to all backends.
DAYDREAM_PI_RETRY_BASE_DELAY_S	Pi 10, other backends 2	Sets the initial retry delay in seconds.
DAYDREAM_PI_RETRY_MAX_DELAY_S	120	Sets the maximum retry delay in seconds.
DAYDREAM_STREAM_IDLE_TIMEOUT_S	2700	Stops a silent Codex or Pi subprocess after this many seconds. 0 disables idle detection.
DAYDREAM_GH_TIMEOUT_SECONDS	60	Sets the GitHub CLI request timeout. The value must be positive.
DAYDREAM_GH_TIMEOUT_RETRIES	2	Sets retries for read-only GitHub CLI timeouts. The value must be nonnegative.
CI	Unset	Enables non-interactive continuous integration mode when the value is not empty, 0, or false.

Benchmark judge

Variable	Use
OPENAI_API_KEY	Authenticates the OpenAI-compatible judge route.
OPENAI_BASE_URL	Overrides the OpenAI-compatible service base URL.

The OpenRouter route is the judge provider for the Harbor benchmark. See Benchmarking for the credential rules.

Daydream does not read DAYDREAM_MODEL or DAYDREAM_BACKEND. Use CLI options or file configuration.

Source

The file schema is in daydream/config_file.py. Model and reasoning defaults are in daydream/config.py. The daydream/backends package defines backend behavior.

Back to Daydream