A declarative, reproducible CachyOS workstation managed with chezmoi: system packages, COSMIC desktop applications, developer toolchains, shell/editor configuration, and root-level system services. Operational rules and verification gates for AI agents are defined in AGENTS.md.
- Install CachyOS with a working internet connection (
gitandchezmoiship by default). - Have your SSH private key ready, or generate a new one.
Only private_dot_ssh/config is tracked; private keys are excluded by .gitignore and must be restored separately.
Option A — copy from backup:
mkdir -p ~/.ssh; and chmod 700 ~/.ssh
cp /path/to/backup/id_ed25519 ~/.ssh/
cp /path/to/backup/id_ed25519.pub ~/.ssh/
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pubOption B — generate a new key (then add the public key to GitHub/GitLab/servers):
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_ed25519chezmoi init --apply https://github.com/flasheddy/dotfiles.git # replace with your repo URLThis copies all dotfiles to ~/.config/, ~/.ssh/config, ~/.gitconfig, etc., then runs the repository's run_onchange lifecycle hooks in order: packages → toolchains → system services.
The first run can take a long time — AUR builds, Flatpak downloads, and toolchain bootstrapping all happen sequentially. Keep the machine plugged in and online.
sudo reboot # reboot into COSMIC
sudo systemctl status keyd # verify keyd
sudo keyd list-keys
rustup show; uv --version; bun --version; go version
printf '%s\n' $PATH # toolchain bins on PATH
chezmoi status # no unexpected driftabbr --show # Show all abbreviations in the terminalAdd dictate toggle on Super+Space in COSMIC Settings.
Managed via dot_local/bin/symlink_* (tracked in toolchains/local-bin.txt): hx → /usr/bin/helix.
Flow A — via the source directory (safest; chezmoi always knows about the changes):
cd ~/.local/share/chezmoi
hx dot_config/fish/config.fish
chezmoi applyFlow B — edit the live file directly:
hx ~/.config/fish/config.fish
chezmoi re-add ~/.config/fish/config.fish
chezmoi applySystem / AUR package: append to the manifest matching its origin, then chezmoi apply — hook 00 detects the changed checksum and installs it (native via pacman, AUR via paru/yay).
- Native (official CachyOS/Arch repos) →
packages/00-system-base.txt(core/drivers/networking),10-desktop-environment.txt(desktop/fonts/GUI),20-dev-stacks.txt(compilers/runtimes/dev tools), or30-terminal-utilities.txt(terminals/editors/CLI). - AUR-only →
archive/pacman-foreign.txt. Never add AUR names topackages/*.txt: they feedpacman -Sdirectly, and an unknown name aborts the whole run (AGENTS.md §1.2). Verify origin:pacman -Si <pkg>(native) vsparu -Si <pkg>(AUR).
Language CLI tool: append to toolchains/uv.txt (Python), cargo.txt (Rust), bun.txt (JS/TS), or go.txt (Go), then chezmoi apply — hook 10 installs it.
aup --help # for more info
aup # update toolchains before system packagescd ~/.local/share/chezmoi
hx system/keyd/default.conf
chezmoi apply # restart keyd.serviceThis workstation is maintained with AI agents (Antigravity CLI, OpenCode) working directly in the chezmoi source directory: drift audits, config edits, package/toolchain manifest maintenance, hook updates — always under strict operating rules.
The binding contract for all agents is AGENTS.md. Point any agent at it before letting it touch this repository or the live system. It carries the chezmoi execution model (§1–§2), the repository enforcement and verification gates (§1.3), the refinement and maintenance protocol (§2.3), and the operator git workflow (§2.4).
chezmoi diff compares generated target state with live destination files, so
it includes source changes that have not yet been applied when they affect
managed targets. Use it with chezmoi status; the source of truth remains
~/.local/share/chezmoi. If you edited a live file and want to keep it, run
chezmoi re-add <file> before applying.
All run_onchange_*.sh.tmpl files use Go templates for checksums. Validate templates and all configs with the repository linter before pushing:
just lint # checks hook templates, git hooks, fish syntax, TOML, typos, and whitespace
just check # full pre-push verification gate (hygiene, lint, secrets, drift)run_onchange_ hooks only execute when their rendered content changes. To force one manually:
chezmoi execute-template < run_onchange_after_20-setup-system.sh.tmpl | bashOr temporarily rename the file to run_once_after_..., apply, then rename it back.
- Fix the manifest/template that caused the failure.
- Re-run
chezmoi apply. - If needed, run the rendered hook manually with
bashto see the exact error.
This repository intentionally does not track SSH private keys. If git status ever shows an untracked key in private_dot_ssh/, do not stage it — the directory is protected by private_dot_ssh/.gitignore.
Personal dotfiles. Use at your own risk.