Daydream reviews a Git repository with an installed coding agent. Version 0.27.0 supports Claude, Codex, Pi, and Osprey backends. Claude is the default backend.

Prerequisites

Install these programs before you install Daydream:

Python 3.12.13 or a later Python 3 release.
uv.
Git.
One supported coding agent.

Run Daydream from the exact root of a Git worktree. A parent directory is not valid. A subdirectory is not valid.

Use these commands to check the repository root:

REPOSITORY_ROOT="$(git rev-parse --show-toplevel)"
cd "$REPOSITORY_ROOT"
test "$PWD" = "$REPOSITORY_ROOT"

The test command must exit with status 0.

Install a coding agent

Claude

Claude is the default backend. Install Claude Code. Make sure that the claude command is on PATH.

Start Claude Code and complete its login flow:

claude

You can use an Anthropic application programming interface (API) key instead. Export ANTHROPIC_API_KEY in the shell that starts Daydream.

Codex

Install Codex. Make sure that the codex command is on PATH.

Authenticate Codex:

codex login

Select Codex for one run with --backend codex.

Pi

Install Pi. Daydream requires the JavaScript Object Notation (JSON) event stream from @earendil-works/pi-coding-agent.

Install @earendil-works/pi-coding-agent with npm:

npm install --global @earendil-works/pi-coding-agent

Configure a provider with Pi. For the default Nous provider, set NOUS_API_KEY. You can also set PI_API_KEY in the Daydream environment. Do not store a provider key in the repository.

Select Pi for one run with --backend pi.

Osprey

Install Osprey. Make sure that the osprey command is on PATH. You can set OSPREY_BINARY to name a different Osprey program. Osprey is a subprocess backend. It emits the same event stream as the other backends.

Select Osprey for one run with --backend osprey.

See Configuration for backend model and effort rules.

Install Beagle review skills

Daydream uses Beagle skills for stack-specific review. Install beagle-core and each stack plugin that your repository needs.

For Claude Code, add the Beagle marketplace and install plugins:

claude plugin marketplace add https://github.com/existential-birds/beagle
claude plugin install beagle-core@existential-birds
claude plugin install beagle-python@existential-birds
claude plugin install beagle-react@existential-birds

Available stack plugins are beagle-python, beagle-react, beagle-elixir, beagle-go, beagle-rust, and beagle-ios.

For Codex, Pi, or another agent that reads Agent Skills, install the skills with the Skills command-line interface:

npx skills add existential-birds/beagle

The Skills command requires Node.js and npx.

Daydream assigns a file to a generic reviewer when no dedicated stack matches the file. Daydream also reads the Claude plugin registry. A reported missing stack plugin sends that stack to the generic reviewer.

Install the Claude plugins when you use Claude with other backends on the same computer.

The --stack option forces one stack review. Daydream also detects stacks from changed files. A deep review always includes a structural assignment. Daydream uses the Beagle structural skill when that skill is available.

Install Daydream with uv

Prerequisites

Confirm that Python and uv meet the requirements:

python3 --version
uv --version

Steps

Install Daydream from the current main branch:

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

Check the installed command:

daydream --help

Result

The daydream command is available on PATH.

Errors

If the shell cannot find daydream, run uv tool update-shell. Start a new shell after uv updates the shell path.

If uv selects an older Python release, install Python 3.12.13 or later. Then repeat the install command.

Run Daydream from source

Use a source checkout when you need the Daydream repository on disk.

Steps

Clone the current main branch into a separate directory:

DAYDREAM_SOURCE="$PWD/daydream-source"
git clone --branch main --depth 1 https://github.com/existential-birds/daydream.git "$DAYDREAM_SOURCE"

Run Daydream through uv:

uv run --project "$DAYDREAM_SOURCE" daydream --help

Use the same prefix for each source run:

REPOSITORY_ROOT="$(git rev-parse --show-toplevel)"
uv run --project "$DAYDREAM_SOURCE" daydream review "$REPOSITORY_ROOT" --review --non-interactive

Result

uv creates or updates the source environment. uv then starts Daydream from the source checkout.

GitHub command-line interface requirements

The GitHub command-line interface (CLI) is available as gh. The gh command is optional for a local report-only review. Install and authenticate gh for these operations:

Detect pull request (PR) metadata and its base branch.
Post a review or inline comments.
Process review bot feedback.
Run setup for a GitHub App.
Harvest benchmark or corpus data from GitHub.

Authenticate and check access:

gh auth login
gh auth status

The authenticated account needs access to the target repository. Posting also needs permission to create PR reviews or comments.

Run a report-only first review

The following procedure prevents pull request posting and fix application. The procedure stores the report in the repository root. It stores the trajectory outside the repository.

Prerequisites

Check out the branch that you want to review. Run the procedure from the exact Git root.

Steps

Create a temporary output directory:

REPOSITORY_ROOT="$(git rev-parse --show-toplevel)"
RUN_OUTPUT="$(mktemp -d)"

Run a report-only review:

daydream review "$REPOSITORY_ROOT" \
  --review \
  --non-interactive \
  --trajectory "$RUN_OUTPUT/trajectory.json" \
  --no-archive

Use --backend codex, --backend pi, or --backend osprey to select a different backend.

Result

Daydream writes the review report to $REPOSITORY_ROOT/.review-output.md. Daydream does not post the report. Daydream does not run fix or test phases.

Daydream does not change reviewed source files. Daydream writes working artifacts under $REPOSITORY_ROOT/.daydream. The trajectory is $RUN_OUTPUT/trajectory.json.

Non-interactive mode keeps .review-output.md when no cleanup option is set.

Errors

Exit status 1 reports a runtime or validation error. Exit status 2 reports invalid command syntax. Exit status 130 reports an interrupt.

If Daydream rejects the target path, change to the exact Git worktree root.

If authentication fails, authenticate the selected coding agent in the same shell environment.

Select an output mode

Use one of these review modes:

Mode	Command option	Result
Deep review and optional fixes	No mode option	Reviews across stacks. Daydream can post findings and apply fixes after confirmation.
Report only	`--review`	Writes `.review-output.md`. Daydream does not run fix or test phases.
PR review	`--comment`	Posts findings to the detected PR. Daydream does not apply fixes.
Shallow review and fixes	`--shallow`	Uses one stack assignment. Daydream can fix and test the result.
Findings artifact	`--findings-out FINDINGS_FILE`	Writes a findings artifact. Daydream stops before posting and fixing.

--review and --comment are mutually exclusive. --yes is not valid with either option. Use --non-interactive with --review to decline the optional PR post.

--findings-out requires a resolvable PR because the artifact must declare its target. Use --pr-number PR when branch-based PR detection is not available.

See the CLI reference for all modes and flags.

Update Daydream

Reinstall the current main branch when you need to repair or refresh the tool environment:

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

Check the installed command after the update:

daydream --help

Uninstall Daydream

Remove the uv tool environment:

uv tool uninstall daydream

uv tool uninstall daydream does not remove repository run data. The command does not remove the central archive at ~/.daydream/archive.

Back to Daydream