daydream

Daydream is a code-review agent that produces structured training data from its own runs. It reviews diffs using stack-specific Beagle skills, applies fixes, validates via test suite, and records every agent interaction as an ATIF v1.6 trajectory. A bitemporal corpus pipeline then scores, labels, and projects those trajectories into JSONL datasets for SFT and RL fine-tuning.

The goal is an open-weight code-review model (Qwen2.5-Coder-7B, QLoRA) trained on daydream's own trajectory archive, benchmarked against commercial code-review bots on a held-out PR replay corpus.

Quick Start

Requires Python 3.12.13+, uv, and Claude Code CLI.

git clone https://github.com/existential-birds/daydream.git
cd daydream
uv sync

Install the Beagle plugin:

claude plugin marketplace add https://github.com/existential-birds/beagle
claude plugin install beagle

Optional: GitHub CLI (gh) for PR feedback and --comment mode. Codex CLI for --backend codex. Pi CLI for --backend pi (z.ai GLM models).

Golden paths

Two near-zero-flag entry points cover the common cases:

daydream /path/to/project            # review → fix → test (deep multi-stack)
daydream --comment /path/to/project  # review → post inline PR comments, then exit

daydream /path is the default verb; daydream review /path is identical. The remaining surface is opt-in:

daydream --review /path/to/project            # write a report to terminal/markdown, no fixes
daydream --shallow /path/to/project           # single-stack review → parse → fix → test loop
daydream --yes /path/to/project               # auto-apply fixes without prompting
daydream --loop /path/to/project              # repeat review-fix-test until clean (or 5 rounds)
daydream feedback 42 --bot "<bot-login>[bot]" /path/to/project  # fix bot PR comments

Run daydream --help for the common flags and daydream --help-all for the full advanced surface (--start-at, --ignore-path, --worktree, --trajectory, …).

To update: git pull && uv sync

Architecture

Daydream runs a deep multi-stack review pipeline (exploration, intent analysis, alternative review, per-stack Beagle skill reviews, arbiter pass, cross-stack merge, recommendation verification), with a --shallow single-skill mode for simpler projects. Every run is recorded as an ATIF v1.6 trajectory and archived (unless --no-archive is passed). A bitemporal corpus pipeline harvests, scores, and projects those trajectories into JSONL datasets for SFT and RL fine-tuning.

Full architectural details about the review pipeline stages, trajectory recording format, corpus pipeline, training roadmap, and benchmarking methodology are documented on the project page.

CLI Reference

Output Modes

Flag	Behavior
(default)	Deep multi-stack review, fix, test loop
--shallow	Single-stack review, parse, fix, test
--review	Write report to terminal/markdown, then exit
--comment	Post inline PR comments, then exit

Additional Commands

daydream summarize <path>                          # print run-info markdown for a trajectory/run dir
daydream setup /path/to/repo --repo OWNER/REPO    # one-command self-hosted review bot setup
daydream setup /path/to/repo --verify             # read-only install audit (checks secrets, workflows, App)
daydream post-findings findings.json --pr 7 --head-sha <sha> --repo owner/repo  # Phase B: validate + post
daydream --review --findings-out findings.json --pr-number 7 /path  # Phase A: emit findings artifact
daydream feedback 42 --bot "<bot-login>[bot]" /path  # ingest and fix bot PR comments
daydream ext validate                              # resolve-check the daydream_ext extension registry

Corpus Commands

The data-pipeline verbs live under the corpus namespace:

daydream corpus harvest                              # annotate all archived runs (reward + label)
daydream corpus harvest --dry-run
daydream corpus build --out /path/to/out.jsonl       # project labeled runs to JSONL
daydream corpus build --out out.jsonl --min-reward 0.5 --include-all-labels
daydream corpus build --out out.jsonl --as-of 2026-05-01T00:00:00Z  # pinned snapshot
daydream corpus label <session_id> --outcome accepted  # manual outcome label override

Common Options

daydream -s python /path/to/project           # force a specific Beagle skill
daydream --backend codex /path/to/project     # override backend (claude, codex, pi)
daydream --model claude-haiku-4-5 /path/to/project  # overrides ALL phases (beats config-file overrides)
daydream --loop 3 /path/to/project            # repeat up to 3 review-fix-test rounds
daydream --yes /path/to/project               # auto-apply fixes without prompting

Advanced flags (hidden from --help, shown by --help-all, all still parse):

daydream --start-at fix /path/to/project      # resume from a specific phase
daydream --trajectory /tmp/run.json /path/to/project
daydream --ignore-path vendor /path/to/project
daydream --worktree /path/to/project          # force ephemeral worktree
daydream --no-eval /path/to/project           # skip the deterministic evaluation analysis (on by default)
daydream --no-archive /path/to/project        # skip run archival
daydream --non-interactive /path/to/project   # run unattended; take every prompt's safe default

--non-interactive takes each prompt's safe default: on test failure it writes a handoff.md and exits non-zero instead of looping, otherwise it declines fixes and exits 0. It is orthogonal to --yes: --non-interactive controls whether daydream may block on stdin, while --yes pre-decides every yes/no gate as "yes". A non-TTY or CI environment (CI set) auto-enables non-interactive mode without the flag.

Per-phase model and backend overrides are no longer CLI flags. Set them in the config file (see Configuration).

Configuration

Per-phase model/backend selection and global defaults live in a config file, read from the target repo root at two sources, merged per-key (the dotfile wins on scalar conflicts):

• pyproject.toml under [tool.daydream] (lower precedence)
• .daydream.toml at the repo root, using bare top-level keys (higher precedence)

# pyproject.toml  →  [tool.daydream]
[tool.daydream]
model = "claude-opus-4-8"     # global default across phases
backend = "claude"            # global default backend

[tool.daydream.phases.fix]    # per-phase override
backend = "codex"
model = "gpt-5.5"

[tool.daydream.phases.review]
model = "claude-opus-4-8"

# .daydream.toml  (top-level keys; no [tool.daydream] prefix)
model = "claude-opus-4-8"

[phases.fix]
backend = "codex"

Phase names are the flow-step config keys (exploration, intent, wonder, per_stack_review, arbiter, merge, review, parse, fix, test, verify, pr_feedback, …); any name is accepted, including phases a fork defines through the extension seam, which lists the per-flow key tables. Resolution precedence, highest first:

CLI > config file (phase, then global) > built-in per-backend default.

So --model beats a [tool.daydream.phases.*] override, which beats the per-backend table in daydream/config.py. The same order applies to backend selection via --backend / config / the claude fallback. (There is no environment-variable tier. DAYDREAM_MODEL/DAYDREAM_BACKEND are not read.)

Cost Pricing

When a backend does not report a USD cost directly (notably Codex), daydream synthesizes cost from token counts using a price table. Anthropic-backed runs use the cost the Claude SDK already supplies and typically do not pass through this path.

Per-model cost is resolved in this order, highest first:

backend-reported cost_usd > user prices.toml > built-in price table > - (with footnote).

A model present in neither the user file nor the built-in table renders - with the "not in the price table" footnote rather than a fabricated cost.

To override or extend the built-in prices, create ~/.daydream/prices.toml. The DAYDREAM_PRICES_FILE environment variable overrides that path (a test seam and power-user escape hatch). The schema is one [prices."<model>"] table per model; each requires input and output (USD per 1M tokens) and accepts an optional cached_input that defaults to input. All prices must be non-negative. Overrides replace a built-in entry wholesale per model. There is no per-field merge.

# ~/.daydream/prices.toml: USD per 1M tokens. User entries override built-ins per-model.
[prices."gpt-5.5"]
input = 4.50
cached_input = 0.45
output = 27.00

[prices."my-custom-model"]
input = 2.00
output = 8.00        # cached_input optional → defaults to input

GitHub App Identity

By default, GitHub reads and writes (PR comments, feedback replies) run under whatever identity the gh CLI is authenticated as. To post as a bot you own, supply GitHub App credentials via environment variables:

export DAYDREAM_APP_ID=12345                                   # from the App settings page
export DAYDREAM_APP_PRIVATE_KEY="$(cat daydream-bot.private-key.pem)"  # raw PEM content, not a file path

When both are set, each run mints a short-lived installation access token scoped to the target repository and injects it into every gh subprocess. Posts are attributed to <app-slug>[bot], and the active identity (bot or human) is displayed before any GitHub action.

One-time setup: create a GitHub App (minimum permissions: Pull Requests read/write, Contents read, Metadata read), generate a private key from the App settings page, and install the App on the target repository's org or user.

In GitHub Actions:

env:
  DAYDREAM_APP_ID: ${{ vars.DAYDREAM_APP_ID }}
  DAYDREAM_APP_PRIVATE_KEY: ${{ secrets.DAYDREAM_APP_PRIVATE_KEY }}

Behavior notes:

• Neither var set → ambient gh identity, exactly as before (the App identity is opt-in).
• Setting only one of the two vars aborts with an error naming the missing one.
• Posting runs (--comment, --review, feedback) abort if the owner/repo cannot be determined or token minting fails. daydream never silently falls back to posting under your personal identity. Non-posting runs fall back to the ambient identity and continue.
• The private key and minted tokens are redacted from logs and trajectory files.

Self-hosted Review Bot

Daydream can run as a self-hosted PR review bot in your own repository's GitHub Actions, posting under your own GitHub App identity. The daydream setup command automates most of the install (App registration via manifest flow, secret deposit, workflow PR); clicking Install on the new App stays manual because GitHub requires it. See the setup guide for details.

Output Files

Path	Description
.daydream/runs/<id>/trajectory.json	ATIF v1.6 trajectory (customize with --trajectory)
.daydream/runs/<id>/trajectories/	Forked sub-trajectories from parallel fan-outs
.daydream/diff.patch	Unified diff captured at run start
.daydream/deep/	Deep pipeline artifacts: intent, per-stack reviews, merged report
.review-output.md	Review findings (removed with --cleanup)
~/.daydream/archive/runs/<id>/	Archived run: manifest, trajectory, review output, evaluation, deep artifacts
~/.daydream/archive/index.db	SQLite index for cross-project querying

Development

make install
make hooks      # install git hooks
make lint       # ruff linter
make typecheck  # mypy
make test       # pytest
make check      # all CI checks

License

Apache License 2.0. See LICENSE for details.