README.md

Dotfiles and System Configuration

This repository manages user configuration across macOS and Linux virtual machines with chezmoi.

Architecture

The repository manages two environments:

macOS Host

• Homebrew manages command-line tools, applications, and Nerd Fonts through Brewfile.
• The script run_onchange_brew.sh.tmpl runs brew bundle install when the Brewfile hash changes.
• The script run_onchange_osx.sh.tmpl configures macOS system defaults and creates the Emacs application symlink.
• Ghostty serves as the primary terminal emulator.

Linux VM (Ubuntu)

• The script run_onchange_setup_box.sh.tmpl installs system tools, desktop fonts, and development runtimes.
• The script run_onchange_linux-resource-control.sh.tmpl installs cgroup memory caps, systemd-oomd swap watch, and zram.
• Window managers include Sway and i3.
• Docker container environments run through the dockerise/justfile.

Repository Structure

• dot_agents/skills/: Custom agent skills.
• dot_config/: Configurations for Doom Emacs, i3, Sway, Kitty, Yazi, and Mise.
• dot_cursor/: Cursor CLI status line integration.
• dot_local/bin/: User executable scripts.
• dot_local/share/: Standalone harnesses and toolchains.
• dot_spacemacs.d/: Spacemacs configuration files.
• bin/: Utility scripts for tmux, clipboard, and macOS apps.
• okf/: Knowledge bundle with architecture notes, playbooks, and post-mortems.
• Brewfile: Declarative package specification for macOS.

Built-in Toolchains and Agent Tools

pi-job harness

The repository includes a deterministic job harness for YAML task files.

• Source: dot_local/share/pi-job-harness/
• Installed path: ~/.local/share/pi-job-harness/
• PATH install: run_onchange_install-pi-job.sh.tmpl owns ~/.local/bin/pi-job through an editable uv tool install
• Documentation: dot_local/share/pi-job-harness/README.md

mermaid-validate

This tool runs parse-only validation against Mermaid diagrams using the official grammar parser.

• Source: dot_local/share/mermaid-validate/
• Installed path: ~/.local/share/mermaid-validate/
• CLI wrapper: dot_local/bin/executable_mermaid-validate -> ~/.local/bin/mermaid-validate
• Documentation: dot_local/share/mermaid-validate/README.md

Agent Instructions and Skills

Global agent instructions reside in AGENTS.md. Claude Code configuration symlinks to this file through dot_claude/symlink_CLAUDE.md.tmpl. Owned skills reside in dot_agents/skills/. Chezmoi installs that tree to ~/.agents/skills/. Third-party skills are listed in dot_config/agent-skills/global.txt. run_onchange_install-agent-skills.sh.tmpl installs that list with npx skills add -g. Run skills-global update to refresh the installed copies.

Cursor CLI Status Line

The script dot_cursor/executable_statusline.sh provides a status line for Cursor agent sessions. The setup script run_onchange_cursor-statusline.sh merges the status line key into ~/.cursor/cli-config.json. Do not add ~/.cursor/cli-config.json directly to chezmoi.

Oh My Pi

Managed file: dot_omp/private_agent/private_config.yml. This is ~/.omp/agent/config.yml. The custom status line pins session (resume id) and cost on the right. Do not add the ~/.omp directory. Sessions, caches, and sqlite files stay local.

Shell, Editors, and Tools

• Shell: Zsh with the default prompt, Zoxide, FZF, and Direnv.
• Runtimes: Mise manages language runtimes such as Node, Bun, Go, and Babashka.
• Emacs: Doom Emacs in dot_config/doom and Spacemacs in dot_spacemacs.d.
• Neovim: LazyVim starter configuration.
• Multiplexer: Tmux with TPM plugins installed by run_once_install-tmux-plugins.sh.

Homebrew and mise

Darwin apply uses Brewfile plus run_onchange_brew.sh.tmpl. Mise owns shared language versions and portable CLIs through dot_config/mise/config.toml. Both OS load that mise file. mise activate in dot_zshrc prepends shims after Homebrew shellenv, so overlapping tools follow mise.

Known overlaps: fd, jq, yazi, go, direnv, kubectl, 1password-cli, antigravity-cli. Pin tools that lack a short name in the installed mise registry with an explicit backend (aqua:, github:). Brew keeps a host fallback. Mise keeps the versioned shim.

Manual Applications

When you configure a new machine, install these macOS applications manually:

• AltTab
• Parallels Desktop
• Dropbox
• Slack
• Proxyman

Homebrew casks manage all other desktop applications and Nerd Fonts.

Documentation

The okf/ directory holds all documentation as an Open Knowledge Format v0.2 bundle. Start at okf/index.md. Run okf-validate from the repo root to check frontmatter, sources paths, links, and index reachability. Chezmoi does not deploy okf/ (see .chezmoiignore).

• Parallels Host-Reachable IP Guide
• Tmux Choose-Tree Activity Guide
• Linux Resource Control Guide
• eza, ls aliases, and the mise registry

History

• June 2026: Replaced nix-darwin with Homebrew and chezmoi on macOS.
• September 2025: Standardized development environment on Ubuntu virtual machines.
• June 2023: Migrated to nix-shell and nix-darwin.
• January 2020: Restructured dotfiles to use chezmoi.
• May 2015: Adopted Spacemacs with Evil mode.