daydream improve examines a repository and writes advisory files. The analysis does not edit application source files. The command does not create a branch, commit changes, or push changes.

Daydream writes run data under .daydream/improve/. Daydream writes implementation plans under daydream_plans/. JavaScript Object Notation (JSON) files provide machine-readable run data.

The implementation is in daydream/improve/.

Run an audit

Run the default audit from a repository root:

daydream improve .

Use --non-interactive when no person can answer prompts. The non-interactive default selects the first five prioritized findings. Issue publication selects all findings when publication is enabled.

daydream improve . --non-interactive

The audit has these steps:

Daydream finds repository services, stacks, commands, and high-risk areas.
Daydream divides large repositories into groups.
Review agents examine the selected groups and categories.
A separate agent checks each candidate finding against repository evidence.
Daydream prioritizes the accepted findings.
Daydream asks for a plan selection during an interactive run.
Plan writers create validated implementation plans.
Daydream publishes selected plans when issue publication is enabled.
Daydream writes the final report.

Untracked files are not part of a full repository audit. Use --focus branch to examine only the diff from the base branch.

Select the audit effort

Use --effort to select audit breadth. The option does not select the model or reasoning effort.

Value	Behavior
`quick`	Checks correctness, security, tests, and technical debt. Runs the audit serially. Keeps high-confidence findings. Returns at most six findings.
`standard`	Checks all eight categories. Uses a default limit of eight repository groups. Does not include investigation-only findings. This value is the default.
`deep`	Checks all eight categories. Includes low-confidence investigation items. Has no effort-tier repository-group limit.

The eight categories are correctness, security, performance, tests, technical debt, dependencies, developer experience, and documentation.

Use --focus to narrow the audit:

daydream improve . --focus security
daydream improve . --focus performance
daydream improve . --focus tests
daydream improve . --focus branch

The branch focus compares the current branch with the base branch. The command stops when the current branch is the base branch.

Use --scope to select one service path, one wildcard path pattern, or one named group:

daydream improve . --scope services/api
daydream improve . --scope 'services/*'
daydream improve . --scope backend

Configure repository services

Define service roots when automatic service detection is not sufficient. Define named groups for repeated --scope values.

Use this form in pyproject.toml:

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

[tool.daydream.improve.service_groups]
backend = ["services/api", "services/worker"]
frontend = ["apps/web"]

partition_max_files sets the maximum size of one repository group. max_partition_groups replaces the default group limit for standard and deep audits. Quick and branch-focused audits use one group.

See Configuration for .daydream.toml syntax and precedence.

Read the output

The .daydream/improve/ directory can contain these files:

File	Contents
`recon.json`	Repository services, stacks, commands, and high-risk areas.
`coverage.json`	Repository groups and the audit status of each group.
`audit-findings.json`	Candidate findings from the audit agents.
`vetted-findings.json`	Findings that passed the evidence check.
`selected.json`	Findings selected for plan writing.
`plan-write-diagnostics.json`	Sanitized data about failed or repaired plan output.
`published-issues.json`	GitHub issue publication results.
`report.md`	Audit scope, coverage, findings, plans, and publication results.

The daydream_plans/ directory contains numbered Markdown plans. The directory also contains README.md and .index.json. The index keeps plan status and finding identities between runs. rejected.json keeps durable rejected findings when rejections exist.

Daydream checks each plan before it writes the plan. The check requires repository paths, evidence, actions, and test instructions. Daydream records a blocked plan when a valid plan cannot be produced.

Write one requested plan

Use improve plan when you already know the requested change:

daydream improve plan "Add request limits to the upload service" .

This command runs repository discovery. The command then investigates the description and writes one plan. The command does not run the general category audit.

The command accepts the same --effort, --focus, and --scope options. It also accepts the shared backend and artifact options.

Publish plans as GitHub issues

Issue publication is disabled by default. Enable publication in the repository configuration:

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

Authenticate the GitHub command-line program before you enable publication. Daydream first writes and validates each local plan. Daydream then copies the complete plan into one GitHub issue. Daydream does not create a branch, commit, or push for publication.

Each issue contains stable plan-group and finding markers. A plan group contains one plan and its source findings. Daydream checks open and closed issues for those markers. A repeated run uses the matching issue instead of creating a duplicate. Daydream checks GitHub again when an issue creation request has an uncertain result.

Daydream stops publication for a plan group when issue matches overlap. Daydream also stops publication when only part of a plan group matches. The local plan remains available after a publication failure.

Daydream publishes issues in plan order during one process. The publisher does not use a lock between separate processes. Use an external lock for concurrent automated runs on one repository. Complete publication failure returns exit status 1. Partial publication returns exit status 2.

Manage re-anchored plans

The repository head can change while Daydream writes plans. Daydream can keep affected plans in a temporary re-anchor worktree. These worktrees use .daydream/worktrees/NAME-reanchor.

List current re-anchor worktrees:

daydream improve list-reanchor .

List durable re-anchored plan records:

daydream improve list-reanchored .
daydream improve list-reanchored . --json

The durable list reads daydream_plans/.index.json. Each row contains the plan number, title, status, and landing path.

The prune command force-removes the named Git worktree. The removal can delete plans that exist only in that worktree. Copy or commit required plans before you run the command.

Remove one temporary re-anchor worktree:

daydream improve prune-reanchor RUN_NAME-reanchor .

The name must be safe for the file system and end with -reanchor.

A new plan-writing run removes stale re-anchor worktrees. Daydream keeps a worktree that has a recent lock. Daydream treats a lock older than 24 hours as stale.

list-reanchor, list-reanchored, and prune-reanchor do not run agents. The two list commands return exit status 0 for an empty result. The prune command returns exit status 1 unless it removes the named worktree.

Back to Daydream