The registered deep flow handles review, comment, shallow, and fix modes. Each mode enables a different part of the same flow.

A pull request (PR) is a proposed change in a GitHub repository. A language stack is a group of changed files that use the same language or framework.

Workspace selection

Pass the top-level directory of a Git worktree as TARGET.

Daydream selects a workspace with these rules:

Command input	Workspace behavior
No `--branch` or `--worktree`	Daydream uses the current worktree. Daydream does not fetch or remove this worktree.
`--worktree`	Daydream fetches and creates a detached worktree at the current `HEAD`.
`--branch FEATURE_BRANCH`	Daydream fetches and creates a detached worktree at `origin/FEATURE_BRANCH`.

Daydream creates temporary worktrees below .daydream/worktrees/. Daydream tries to remove each temporary worktree after the run. A removal failure produces a warning and leaves the worktree for manual recovery.

Daydream can copy ignored support files into a temporary worktree. The default list contains .env, .env.local, and ignored .env.* files. The [tool.daydream.workspace] copy setting replaces the default list. Each --copy value adds another file. Daydream confines each copy path to the source and destination worktrees.

Review-only and comment-only modes do not copy support files. These modes do not run tests.

Base and diff selection

Daydream selects the base in this order:

Daydream uses --base when the command supplies that option.
Daydream uses the open PR base when --branch identifies a PR.
Daydream uses the repository default branch.

An in-place fix run cannot review the base branch against itself. Check out a feature branch or use --branch in this case.

Daydream prefers origin/BASE_BRANCH when that remote reference exists. Daydream calculates the committed diff with three-dot Git diff syntax. Daydream also includes staged and unstaged changes to tracked files. Daydream does not include untracked files in the review diff.

Use a repeatable --ignore-path PATH option to exclude a path from the review diff. The exclusion applies before stack detection and review.

Deep review flow

The default review uses these steps:

Daydream scans affected files and repository conventions.
An intent agent analyzes the diff, commit history, and applicable PR description.
An alternative-review agent looks for another implementation approach.
Daydream runs one review for each detected language stack.
Daydream runs a separate structural review for applicable code changes.
Daydream parses each review into structured findings.
Daydream checks changed files that no review agent read.
An arbiter checks high-severity and contested findings.
A merge agent removes duplicates and combines the stack results.
Daydream removes findings without sufficient evidence.
An optional findings supervisor can keep, edit, drop, or hold findings.
Daydream writes a findings artifact or offers to post the findings.
Daydream asks whether it can change the repository.
A read-only verifier checks each non-structural recommendation.
Fix agents apply accepted findings by file group.
A test agent runs the project test suite.
Daydream offers to commit and push the tested changes.

During a new multi-stack run, the alternative review and language-stack reviews can run concurrently. The merge step waits for these reviews.

The recommendation verifier returns consistent, contradicts, or uncertain. The verdict gives instructions to the fix agent. The verdict does not automatically remove a finding. Structural findings do not use this verifier.

--review stops before fixes and tests. --comment posts the review and then stops. --findings-out FILE writes the findings artifact and then stops. The default mode can continue through fixes, tests, and an optional commit.

Shallow mode and small diffs

--shallow uses the deep review flow with one language-review assignment. Daydream still uses a separate structural-review assignment. Shallow mode skips the arbiter and the agent that merges language-stack results. The Daydream process writes the combined finding list.

For a diff with at most two changed files, Daydream also uses one language-review assignment. The shallow_fanout_threshold setting controls the maximum file count for this behavior. A value of 0 disables this automatic behavior.

Shallow mode makes one review, fix, and test pass.

Exploration and coverage

Daydream selects an exploration tier from the changed-file count.

Changed files	Exploration work
0 or 1	Daydream skips the exploration pre-scan.
2 or 3	Daydream uses static data and one dependency specialist.
4 or more	Daydream uses static data and three specialists. The specialists inspect patterns, dependencies, and tests.

A diff with zero or one changed file also skips the alternative review.

Exploration errors do not stop the review. Daydream keeps the available static or partial context.

Daydream caches a completed exploration result in .daydream/exploration/. The cache key contains HEAD, the diff, the tier, and the exploration depth. Daydream uses the cache only for an exact key match.

The uncovered-file sweep runs after stack parsing. The sweep selects diff files that no completed review read. By default, a file needs at least five changed hunk lines. The default sweep limit is ten files. Sweep failures do not stop the merge. Daydream records skipped files and sweep failures in coverage-stats.json.

Finding checks

The arbiter receives high-severity and contested findings. A missing arbiter verdict keeps the original finding. An explicit reject verdict removes the finding.

Precision mode adds a check for borderline findings. Use --precision to enable precision mode. The precision check removes a borderline finding when the check cannot confirm the finding.

The evidence check rejects a finding in these cases:

The confidence is LOW.
The evidence is blank or contains only a placeholder.
The rationale states that no exploration evidence exists.
The finding has neither a real file and positive line number nor a valid path:line citation.

A structural finding needs non-empty evidence. A structural finding can use line 0 for a whole-file problem. Daydream writes rejected findings to .daydream/deep/dropped-speculative.json.

The findings supervisor is off by default. Rules mode drops findings for files that match configured path patterns. Large language model mode uses one batched supervisor call. A held finding appears in a held section of the report. Daydream does not post or fix held findings.

A separate tool supervisor can reject configured file edits and shell commands. The built-in tool supervisor supports rules mode only.

Failure isolation

A failed stack review does not cancel completed stack reviews. Daydream records the failed stack. A multi-stack merge identifies the missing stack coverage in the report.

A parse failure stops the run after sibling parse tasks finish. Completed parse artifacts remain available when you restart the run.

An unparseable merge result produces a partial report from the available stack records. Daydream records the merge failure in per-stack-failures.json. The run then exits with status 1.

Use --start-at merge to retry the merge with saved stack records. Use --start-at fix only when you accept the partial merged result.

Fix boundaries

Daydream sorts findings by severity before the fix phase. Daydream batches findings that name the same file. Daydream can run different file groups concurrently. The backend and configured concurrency limit control the active group count.

Daydream fixes only findings for files in the reviewed diff. Daydream tries to file each out-of-diff finding as a GitHub issue. An issue-post failure does not expand the fix scope.

Daydream takes a pre-fix snapshot before fix agents start. An exception in a file group stops the run. When a trusted snapshot exists, Daydream reverts the failed group. Daydream first saves recoverable work below .daydream/partial-fixes/.

A file group can reach its configured time or serial-fix limit. Daydream keeps changes that the group already completed. The run continues to tests, but the archive records a partial status.

Daydream restores edits to existing generated files and existing lockfiles. Daydream also restores related dependency manifests when necessary. The guard permits a newly created generated file, such as a new migration.

After fixes, Daydream reverts tracked edits outside the allowed file set. Daydream tries to file each reverted edit as a GitHub issue. The final scope check does not restore a newly created untracked file. Inspect git status before you approve a commit.

The anti-degradation check measures complexity concentration and selected verbosity patterns in Python files. A result that exceeds a configured limit produces a warning and an artifact. An unavailable result also produces a warning and an artifact. The anti-degradation check does not stop the run.

Tests and completion

The test agent selects and runs the project test suite. An environmental failure stops the test phase without a repair attempt.

An unattended run without --yes stops after an ordinary test failure. Daydream writes a handoff.md file for that failure path.

An unattended run with --yes permits one repair and test retry. A second failure stops the run and writes a handoff.

An interactive run can retry, repair, ignore, or abort. The ignore option records the failed test result and permits the commit step.

The commit step asks before it stages, commits, and pushes changes. --yes accepts the available PR-post, fix, and commit gates without a prompt. It also enables report cleanup when no cleanup option is set.

--cleanup removes .review-output.md only after exit status 0. Daydream keeps failure evidence after a nonzero exit. Daydream also keeps the report for a --findings-out run.

Archive assembly occurs when the trajectory recorder closes. The archive keeps the deep report even when cleanup removes the root report. Daydream assembles the archive before it removes a temporary worktree.

See Artifacts and evaluation for archive controls.

Back to Daydream