Use the command error and exit status to select a recovery procedure.

The command-line interface (CLI) is the daydream command. A pull request (PR) is a proposed change in a GitHub repository. Continuous integration (CI) is an unattended automation environment. An application programming interface (API) connects Daydream to an external service.

Exit status

Status	Meaning
`0`	The command completed or found no work.
`1`	An operational check, validation, agent, test, post, or setup operation failed.
`2`	The command syntax or selected subcommand was invalid.
`130`	Daydream received an interrupt or termination signal.

Some commands use a more specific status within this pattern. For example, daydream summarize uses status 2 when all trajectory files fail to parse.

Find the available options

--help shows the common options. --help-all also shows advanced options.

daydream --help
daydream --help-all

Daydream does not have a --version option. The current package metadata reports version 0.27.0. Read the installed package metadata when you must confirm the version.

uv tool list

Fix `daydream: command not found`

Install the current main branch as a uv tool:

uv tool install git+https://github.com/existential-birds/daydream@main
uv tool update-shell

Start a new shell after uv tool update-shell changes the shell path.

For a source checkout, run Daydream through the project environment:

cd DAYDREAM_CHECKOUT
uv sync
uv run daydream --help

The module entry point is also available:

uv run python -m daydream --help

Do not expect a bare daydream command after only uv sync. The source environment is not a global tool installation.

Check the Python version

Daydream requires Python 3.12.13 or a later compatible 3.12 release. The package metadata permits later Python feature releases.

python3 --version

Let uv select and install a compatible interpreter when the local interpreter is too old.

Fix target and diff errors

Daydream requires the top-level directory of a Git worktree. Find the top-level directory before you run a review:

git rev-parse --show-toplevel
cd REPOSITORY_ROOT
daydream .

The default fix flow rejects an in-place worktree on the base branch. Check out a feature branch or select a remote feature branch:

git switch FEATURE_BRANCH
daydream .

daydream --branch FEATURE_BRANCH REPOSITORY_ROOT

Use --base BASE_REF when Daydream selects the wrong base. Confirm that Git can resolve the base before another run:

git rev-parse --verify BASE_REF
git merge-base BASE_REF HEAD

Daydream reviews committed changes and tracked worktree changes. Daydream does not review a new untracked file. Add a new file to the Git index before review.

git add -N PATH_TO_NEW_FILE
git diff HEAD -- PATH_TO_NEW_FILE

Check the final review scope in .daydream/diff.patch.

Fix GitHub CLI and PR discovery

Daydream uses the GitHub CLI, gh, for repository and PR operations. Check the current authentication and repository:

gh auth status
gh repo view --json nameWithOwner
gh pr view --json number,headRefOid,baseRefName,state

Run these commands from the target repository. Authenticate gh for the GitHub host that owns the target repository.

--comment requires a resolvable PR. --findings-out also requires a resolvable PR because the artifact declares its target. Use --pr-number PR_NUMBER for a findings artifact when branch discovery is ambiguous. Comment mode still discovers the PR from the current branch.

Confirm that the local HEAD matches the PR head before posting:

git rev-parse HEAD
gh pr view PR_NUMBER --json headRefOid

Retry posting from merged findings

The source checkout contains a posting recovery utility. Use it when review completed but direct PR posting did not complete.

First, inspect REPOSITORY_ROOT/.daydream/deep/merged-items.json. Confirm that the PR still has the reviewed head commit. The utility does not accept a separate head-commit check.

Run the utility from the Daydream source checkout:

uv run python scripts/redrive_post.py REPOSITORY_ROOT --pr PR_NUMBER

The utility uses the normal finding classification and duplicate checks. It asks for confirmation before it writes to GitHub. The --yes option skips this confirmation and posts immediately.

A missing, unreadable, or malformed-JSON findings file returns status 1. A missing PR or posting failure also returns status 1. Posting is not atomic, so file comments can remain after final review creation fails.

Fix backend startup or credential errors

Select a backend with --backend claude, --backend codex, or --backend pi. The DAYDREAM_BACKEND and DAYDREAM_MODEL environment variables do not select a backend or model. Use CLI options or the repository configuration file.

Backend	Required local setup
`claude`	Configure authentication for the Claude Agent software development kit (SDK). `ANTHROPIC_API_KEY` is accepted for API-key use.
`codex`	Install the `codex` executable and complete the normal Codex CLI sign-in.
`pi`	Install the `pi` executable and configure the selected Pi provider and model.

Check subprocess backends before another run:

command -v codex
codex --version
command -v pi
pi --version

Pi can read credentials from its normal auth.json configuration. Pi can also read a provider-native environment variable. PI_API_KEY maps to NOUS_API_KEY for the nous provider. PI_API_KEY maps to ZAI_API_KEY for the zai provider. Set the native credential directly for another provider.

Check phase-specific backend settings when only one phase fails. See Configuration for the precedence rules.

Understand prompts in CI

Daydream enables non-interactive mode when standard input is not a terminal. The CI environment variable also enables this mode. The values 0, false, and an empty value do not enable the mode.

--non-interactive takes the safe default at each prompt. The safe default declines fixes and commits. Without --yes, Daydream does not repair and retry a failed test in unattended mode.

--yes answers yes to each applicable yes-or-no gate. Use both options for an unattended fix run that permits repository changes:

daydream --non-interactive --yes REPOSITORY_ROOT

This combination permits one automatic test repair and retry. A second failed test attempt stops the run.

--review and --comment do not have a fix gate. The CLI rejects --yes with either mode.

Fix a resume error

A language stack is a group of changed files that use the same language or framework. --start-at review starts a new review. In this option, ttt names the intent and alternative-review stage. Every non-feedback resume processes the exploration step first. The step reuses an exact cache or follows the exploration tier for the current diff. After exploration, --start-at ttt runs intent analysis, alternative review, and all later stages. --start-at per-stack reuses the saved intent and alternative-review files. It reruns each language-stack review and all later stages.

--start-at merge reuses parsed finding records and starts the finding arbitration and merge stages. --start-at fix reuses merged findings and starts at the fix approval step. Shallow mode supports only review and fix. The command-line interface rejects parse and test because the current flow has no matching stages.

Daydream records the reviewed diff in .daydream/deep/diff-key. A resume fails when the current diff does not match that key. A resume also fails when required artifacts are older than the key.

The resume fails when worktree changes exist outside .daydream and .review-output.md. The resume also fails when the artifact set has no diff key.

Use this recovery procedure:

Save any work that you need from .daydream/deep/.
Check git status --short.
Commit or move unrelated work through your normal Git procedure.
Run Daydream again without --start-at.

Do not change diff-key to force a resume. The key prevents findings from another diff from reaching the fix phase.

Recover a remaining temporary worktree

Daydream normally removes a temporary worktree after the recorder closes. A cleanup warning includes the worktree path when removal fails.

List the registered worktrees:

git -C REPOSITORY_ROOT worktree list

Copy required artifacts from the remaining worktree before removal. Inspect the remaining worktree for source changes:

git -C WORKTREE_PATH status --short

Confirm the exact path from git worktree list before you use the force-removal command. Then unlock and remove the exact worktree path:

git -C REPOSITORY_ROOT worktree unlock WORKTREE_PATH
git -C REPOSITORY_ROOT worktree remove --force WORKTREE_PATH
git -C REPOSITORY_ROOT worktree prune

Recover from test failures

Daydream asks a test agent to select and run the project test suite. Read the reported command and test output before you change source code.

An environmental failure stops before an automatic repair attempt. Examples include an unavailable database, cache, network service, or runner dependency. Restore the required service and rerun the command.

An ordinary unattended test failure writes handoff.md before exit status 1. The handoff contains verified facts, failure output, changed files, and artifact paths. Look in the live or archived run directory for the handoff.

An interactive abort can offer to copy the handoff to the system clipboard. Daydream uses pbcopy, xclip, xsel, or clip.exe when one of these programs is available. A clipboard failure does not remove the handoff file.

The fix phase captures .daydream/recommended.patch before tests start. Use the patch to inspect the proposed changes after a test failure.

git apply --stat .daydream/recommended.patch

Do not apply the patch until you inspect the patch and the final worktree. The patch can include a fix that Daydream later reverted. Run git apply --check only from a clean worktree at the matching pre-fix revision.

A temporary-worktree run can lose its handoff when no archive or dump exists. Keep archive output enabled for unattended temporary-worktree runs.

Recover partial fixes

Inspect these paths after a fix-group failure:

.daydream/deep/fix-failures.json
.daydream/deep/fix-leftover-untracked.json
.daydream/partial-fixes/
.daydream/deep/generated-file-violations.json

An exception in a file group stops the run. Daydream restores the group when a trusted pre-fix snapshot exists. Daydream saves a patch or orphan file before that restore.

Inspect one recovery patch before applying it:

git diff
git apply --check .daydream/partial-fixes/RECOVERY_FILE.patch
git apply .daydream/partial-fixes/RECOVERY_FILE.patch

A file group can reach its configured time or serial-fix limit. Daydream keeps completed changes and skips the remaining findings in that group. Daydream continues to tests and marks the archive status as partial.

The leftover-untracked file lists new untracked paths that remain after a failed parallel fix. Daydream cannot identify which file group created each path. Review each path before you stage or remove it.

Recover a partial merge report

An unparseable merge across language stacks exits with status 1. Daydream writes a partial merged-items.json and a partial rendered report. Daydream also writes a __merge__ entry in per-stack-failures.json.

Retry the merge from saved stack records:

daydream --start-at merge REPOSITORY_ROOT

Use the partial findings without another merge only after manual review:

daydream --start-at fix REPOSITORY_ROOT

The second command displays a warning that the merge across language stacks is partial.

Investigate archive and upload warnings

Archive, evaluation, and Hugging Face (HF) upload failures are nonfatal. A Daydream command can return status 0 after one of these warnings.

Check free space and permissions for the archive root:

ls -ld ~/.daydream/archive
df -h ~/.daydream/archive

Set DAYDREAM_ARCHIVE_DIR when the default root is not writable. Check for manifest.json and evaluation.json in the run directory.

An HF upload requires HF_TOKEN and the huggingface_hub package. A missing token or package skips the upload. An existing public dataset remains public and produces a warning.

--no-archive --dump-artifacts DIR still assembles and indexes central archive data. Do not use this combination when local central storage is prohibited.

Artifact dumps can contain sensitive repository and tool data. Inspect a dump before you attach the dump to a CI job or support request.

Validate an extension

Run the extension validator without a target repository:

daydream ext validate

Status 0 means that built-ins and the discovered extension resolve. Status 1 means that loading or registry resolution failed. Status 2 means that the extension command syntax was invalid.

Check DAYDREAM_EXT_DIR first when the validator loads an unexpected extension. Without that variable, Daydream tries to import daydream_ext.

See Extensions for API version 6 requirements.

Recover a partial bot setup

daydream setup can make external changes before a later step fails. Possible changes include a GitHub App, secrets, a variable, a branch, a commit, a push, or a PR. Setup does not roll back these external changes.

Run the read-only setup check after a failure:

daydream setup REPOSITORY_ROOT --repo OWNER/REPOSITORY --verify

For organization scope, replace --repo with --org ORGANIZATION. The check always reports secret names, the bot variable, and workflow files. The check also reports App installation and permissions when local App credentials are available. Set DAYDREAM_APP_ID and DAYDREAM_APP_PRIVATE_KEY to enable the App checks.

Inspect the daydream/setup-bot branch and its PR before another setup run. A normal rerun reuses stored credentials when local credentials are also available. Use --force only when you intend to register another App configuration.

Fix benchmark credential errors

Set the environment credentials before a benchmark run.

The Harbor benchmark uses OpenRouter for the reviewer and the judge. Set the OpenRouter credential in the shell environment that starts daydream benchmark. The commands never write credentials into the workspace. The legacy martian judge route is removed.

See Benchmarking for corpus and result recovery.

Quote bot logins in zsh

The zsh shell treats square brackets as a filename pattern. Quote a bot login that contains [bot]:

export BOT_LOGIN='coderabbitai[bot]'

An unquoted value can fail in zsh before a command starts.

Protect diagnostic data

Do not paste a complete artifact bundle into a public issue. The bundle can contain source code, PR text, prompts, reasoning, tool output, and diffs.

Daydream redacts common secret patterns from trajectory text. The redactor cannot recognize each private value. Remove sensitive data before you share selected diagnostics.

Back to Daydream