Dotfiles

Why this is different. You won't find these three things in mathiasbynens/, holman/, or paulirish/. First, wallpaper-driven terminal themes. We use K-Means clustering in CIELAB and enforce WCAG AAA contrast. Second, first-class agent governance. That covers MCP policy, A2A discovery, signed attestation logs, and bounded profiles (ask / plan / apply / audit). Third, verified multi-shell parity across zsh, fish, bash, nushell, and PowerShell. The suite is tested on macOS, Linux, WSL2, and Apple Silicon CI runners. Signed commits are enforced. The installer is idempotent. The CLI heals itself.

Install

Verified install (recommended). Pin to a release tag. Download the installer. Check its SHA256 against the value published with the release. Then run it. See docs/security/INSTALL_VERIFICATION.md for the per-release hash and how it's generated.

curl -fsSL -o /tmp/dotfiles-install.sh \
  https://raw.githubusercontent.com/sebastienrousseau/dotfiles/v0.2.511/install.sh
echo "d5a04c5e2813a93a63c8ecce9655cf3d107f6068862c6eba84a92cf22f801c7e  /tmp/dotfiles-install.sh" \
  | shasum -a 256 -c
bash /tmp/dotfiles-install.sh

Trust-source one-liner (skips the SHA check — fine for sandboxes and ephemeral CI, not recommended for primary workstations):

bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"

Then verify and explore:

dot doctor        # verify installation
dot learn         # interactive tour

The install needs git and curl. The verified path also needs shasum or sha256sum. The script runs on macOS, Ubuntu, Debian, Arch, WSL2, and GitHub Codespaces.

Silent install (no prompts):

DOTFILES_SILENT=1 DOTFILES_NONINTERACTIVE=1 \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/dotfiles/main/install.sh)"

Docker sandbox:

docker run --rm -e DOTFILES_NONINTERACTIVE=1 ubuntu:24.04 bash -c \
  'apt-get update -qq && apt-get install -y -qq git curl sudo >/dev/null 2>&1 \
  && git clone --depth 1 https://github.com/sebastienrousseau/dotfiles.git ~/.dotfiles \
  && bash ~/.dotfiles/install.sh \
  && export PATH="$HOME/.local/bin:$PATH" \
  && dot doctor'

Why this repo is different

Most dotfiles repos are personal collections. This one ships as workstation infrastructure. It's signed, attested, multi-platform, AI-aware, and self-healing.

Architecture

The CLI is idempotent. Run it once or a hundred times. Same machine state.

graph TD
    A[User Shell] --> B{dot CLI}
    B --> C[Lifecycle: sync / apply / rollback / heal]
    B --> D[Diagnostics: doctor / drift / benchmark / score]
    B --> E[AI & Agents: ai / mcp / agent / mode]
    B --> F[Themes: theme / theme rebuild]
    B --> G[Fleet & Attest: fleet / attest / bundle]

    C --> H[Chezmoi Source]
    F --> I[Wallpaper Discovery<br/>System + Custom]
    I --> J[K-Means CIELAB Engine]
    J --> K[themes.toml<br/>WCAG AAA enforced]
    K --> H

    H --> L[Zsh / Fish / Bash / Nushell / PowerShell]
    H --> M[Mise / Nix Toolchains]
    H --> N[MCP Policy / Agent Profiles]
    L --> O[~/.cache/shell Fast Init]

    G --> P[Signed Attestation Logs]

Wallpaper-Driven Themes

Drop a wallpaper. Get a theme.

dot theme rebuild discovers system wallpapers and your custom ones. On macOS it looks in /System/Library/Desktop Pictures/. On Linux it looks in /usr/share/backgrounds/. Custom wallpapers live in ~/Pictures/Wallpapers/. K-Means clustering in CIELAB color space extracts dominant colors. The engine then generates a 16-color terminal palette, enforces WCAG AAA contrast, and assembles themes.toml on its own.

dot theme              # interactive picker (paired themes only)
dot theme tahoe-dark   # switch directly
dot theme toggle       # swap dark↔light within current family
dot theme rebuild      # regenerate from current wallpapers

On theme switch, every managed surface updates. Terminals: Ghostty, Alacritty, Kitty, WezTerm, Warp, iTerm2, tmux. Editors: Neovim and VS Code. The theme also sets GTK and icon themes, the macOS accent and dark-mode toggle (with a forced UI refresh), the browser color mode, and the wallpaper. On Linux, the engine auto-converts HEIC to PNG via magick or heif-convert.

Full guide: docs/guides/THEMING.md

The dot CLI

Over 80 commands grouped by intent. Run dot help for the full reference.

Start Here

A Claude Code skill is also shipped — /skills discovers dotfiles-bootstrap and runs dot init with profile-aware safety defaults.

Daily Use

Inspect & Repair

AI & Agents

Configuration

Fleet & Performance

Full reference: docs/reference/UTILS.md · Complete manual: docs/manual/ or dot manual

Documentation

The .dotfiles Manual is published in nine formats: HTML (single and multi-page), PDF, EPUB, ASCII text, compressed variants, and Markdown source. It auto-builds on every change.

• Online — https://sebastienrousseau.github.io/dotfiles/manual/
• Terminal — dot manual text | less
• PDF — dot manual pdf
• Offline copy — dot manual --offline (uses the bundled snapshot, no network)
• Sources — docs/manual/

First 5 Minutes

1. Check — dot doctor validates tools, paths, and security
2. Explore — dot learn walks through shells, secrets, themes, and performance
3. Customize — edit ~/.config/chezmoi/chezmoi.toml for per-machine settings (Profiles)
4. Toggle features — flip features in .chezmoidata.toml (Feature Flags)
5. Apply — dot sync applies the config and the next interactive shell hydrates caches via _cached_eval

See the Migration Guide for version upgrades.

What's Included

• Zsh loads in stages through small modules, not one big startup script
• Fish uses _cached_eval and deferred loading for fast interactive use
• Bash ships full parity with zsh for tooling and aliases
• Nushell handles structured terminal workflows (Tier-3 compatible)
• PowerShell keeps cross-platform and WSL sessions on the same baseline. A pwsh parity contract runs in CI on every PR
• Starship, Zoxide, Atuin, and fzf for navigation and command recall
• Starship Transient Prompt collapses past prompts to a single glyph in scrollback on fish. The zsh hook is in place for when upstream Starship lands the matching function (ADR-010)

• Mise manages language versions in user space (no system pollution)
• Nix Flakes for strict reproducible builds when speed isn't the priority
• Pueue queues long-running tasks instead of spawning extra terminal tabs
• Neovim ships as a full Lua-based editor, not a starter template
• Lazygit for terminal git workflow without a GUI
• Build caches (Cargo, Go, pip, uv, Zig) redirect to /tmp/builds/ and clear on reboot
• _cached_eval caches expensive tool init output with mtime and realpath invalidation. Set EVALCACHE_DISABLE=true to bypass for debugging

• Agent profiles (dot mode) — switch between ask, plan, apply, and audit
• Pattern library (dot patterns) — architect, hardener, and refactor patterns bundled in dot_config/ai/patterns/
• MCP policy enforcement (dot mcp) — validate the Model Context Protocol registry against policy
• AI commit messages (dot commit) — conventional commits generated from the staged diff
• AI fleet cockpit (dot ai) — install and run Codex, Copilot, Antigravity, Aider, OpenCode, and friends from one Bubble Tea TUI; dot ai serve serves your Claude subscription locally to any Anthropic/OpenAI-protocol tool. See docs/AI.md
• Attestation logs — every agent session is logged with a policy hash and an outcome

• Age and SOPS keep secrets encrypted at rest and out of plaintext history
• SSH ED25519 signing plus trust metadata back signed commits and verifiable changes
• Gitleaks, policy checks, and compliance workflows
• Workstation attestation (dot attest) records machine state, policy, prompt, and model metadata in tracked JSON
• Telemetry controls and local-first defaults — you own your data
• SBOM (CycloneDX) and Grype CVE scanning in CI
• JSON Schema for .chezmoidata.toml — taplo runs the schema in CI on every PR, so typos in feature flags or profile names fail before merge
• OIDC Trusted Publishing — npm releases authenticate via OIDC, not a long-lived NPM_TOKEN. Provenance is attached to every published tarball

For security hardening options, see the Security docs.

Comparison

chezmoi is the underlying templating engine. This repo is the opinionated reference implementation.

THE ARCHITECT ᛫ Sebastien Rousseau THE ENGINE ᛞ EUXIS ᛫ Enterprise Unified Execution Intelligence System

License

Licensed under the MIT License. See LICENSE for details.