Dreamcoder OS

Personal Arch Linux dotfiles for the Dreamcoder identity: a visual layer on top of ML4W/Gentleman Dots focused on readability, eye comfort, and a premium coding experience.

Philosophy

Dreamcoder is not a neon rice. It is a workbench:

• health first: no pure black/white primary backgrounds, strong contrast, low glare;
• daily comfort: larger terminal type, calmer prompt density, automatic day/night mode;
• identity second: Cocoa/Lúcuma warmth, diagnostic cyan, restrained editorial colors;
• ML4W-compatible: Dreamcoder owns colors and hooks, ML4W/Gentleman can keep layout behavior.

Quick commands

./scripts/dreamcoder install      # first install / full reapply
./scripts/dreamcoder repair       # after ML4W or Gentleman updates
./scripts/dreamcoder doctor       # inspect current health/status
./scripts/dreamcoder verify       # symlinks + starship + theme health
./scripts/dreamcoder preview      # regenerate docs/dreamcoder-theme-preview.md
./scripts/dreamcoder auto         # apply light/dark for current time
./scripts/dreamcoder light        # force light mode
./scripts/dreamcoder dark         # force dark mode
./scripts/set-wallpaper.sh <file> # set wallpaper and refresh Dreamcoder

Installation

git clone git@github.com:Dreamcoder08/Dreamcoder_dots.git ~/Documents/PROYECTOS/dreamcoder-dots
cd ~/Documents/PROYECTOS/dreamcoder-dots
./scripts/dreamcoder install

install.sh stows the Dreamcoder modules, installs ML4W/Waypaper hooks, enables the day/night timer, applies the current mode, and verifies the setup.

Post-update repair

After updating ML4W, Gentleman Dots, Waypaper, or Hyprland configs, run:

cd ~/Documents/PROYECTOS/dreamcoder-dots
./scripts/dreamcoder repair

This reapplies hooks, restows modules, restarts the timer, refreshes the current theme, and runs verification.

Theme system

• Day: warm light mode, paper-like surfaces, dark graphite text.
• Night: softened graphite mode, warm text, lower glare than pure black.
• Wallpaper adaptive: wallpaper colors can tint accents, but contrast guardrails stay mandatory.
• opencode/Codex: only dreamcoder.json is generated and selected; stale opencode theme JSONs are removed by the sync script.

Important files:

themes/dreamcoder/tokens.json        # canonical design tokens: colors + guardrails
themes/dreamcoder/tokens.schema.json # schema for the token contract
scripts/dreamcoder                   # unified CLI entrypoint
scripts/sync-dreamcoder-theme.py     # generator for terminals/opencode/overlays
scripts/theme-auto.sh                # time-based light/dark orchestrator
scripts/wallpaper-hook.sh            # robust wallpaper + Dreamcoder refresh hook
scripts/verify-theme-health.py       # contrast and eye-comfort guardrails
scripts/generate-theme-preview.py     # Markdown palette/contrast preview
Systemd/.config/systemd/user/*       # day/night user timer

Design-token architecture

Dreamcoder has one canonical palette contract: themes/dreamcoder/tokens.json. The generator reads these tokens first, then emits terminal, Codex/opencode, Waybar, Rofi, Hyprland, and prompt outputs. This keeps the system coherent after ML4W/Gentleman updates and prevents each app from drifting into a different palette.

The token file includes hard guardrails: canonical opencode theme dreamcoder, no harsh pure black/white primary backgrounds, AA minimum token contrast, and AAA target contrast for main text.

Visual health policy

Dreamcoder prioritizes long-session comfort over trendy contrast extremes:

• no pure black or pure white as primary backgrounds;
• warm off-white light mode to reduce glare;
• softened dark mode instead of harsh black/white inversion;
• AAA-level main text contrast where practical;
• AA-or-better semantic token contrast for code, markdown, and diffs;
• typography and spacing tuned for fewer micro-adjustments.

Troubleshooting

./scripts/dreamcoder doctor

Common fixes:

• Looks dark during the day: run ./scripts/dreamcoder auto; check GTK in doctor.sh.
• Wallpaper with spaces does not load: use ./scripts/set-wallpaper.sh <file> or re-run ./scripts/dreamcoder repair.
• ML4W update overwrote hooks: run ./scripts/dreamcoder repair.
• opencode theme looks old: ensure ~/.config/opencode/tui.json uses dreamcoder, then run ./scripts/dreamcoder auto.
• Theme feels too intense: run DREAMCODER_ADAPTIVE=0 ./scripts/dreamcoder auto to disable wallpaper tinting for that run.

Structure

Shell/       Starship and shell ergonomics
Kitty/       Kitty config and Dreamcoder colors
Ghostty/     Ghostty config and Dreamcoder theme
Warp/        Warp Terminal themes
Fastfetch/   Fastfetch config
Codex-App/   Codex/opencode theme exports
themes/      ML4W/Gentleman portable color overlays
scripts/     install, repair, doctor, theme, wallpaper, verification
Systemd/     user timer/service for automatic day/night mode

Verification

./scripts/dreamcoder verify
./scripts/verify-theme-health.py

A healthy setup should report linked configs, valid Starship, active timer, and passing visual-health guardrails. Use ./scripts/dreamcoder preview after palette edits to refresh the auditable preview gallery.