dotfiles

Personal dotfiles managed with chezmoi. macOS/Linux + fish.

New machine

macOS

brew install chezmoi
git clone git@github.com:maheshrijal/dotfiles.git ~/code/dotfiles
chezmoi init --source ~/code/dotfiles
chezmoi apply

Linux

sudo apt-get update
sudo apt-get install -y build-essential procps curl file git gpg
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
sh -c "$(curl -fsLS get.chezmoi.io)" -- -b ~/.local/bin
git clone git@github.com:maheshrijal/dotfiles.git ~/code/dotfiles
~/.local/bin/chezmoi init --source ~/code/dotfiles
~/.local/bin/chezmoi apply

init reads .chezmoiroot (→ home/) and generates ~/.config/chezmoi/chezmoi.toml, pinning sourceDir to the clone.

Node.js and pnpm paths

Node.js versions are selected by fnm; the fish config does not pin a machine-specific Node installation. Install and select a Node version separately with fnm.

Fish adds PNPM_HOME to PATH without duplicates. It defaults to ~/Library/pnpm on macOS and ${XDG_DATA_HOME:-~/.local/share}/pnpm on Linux. An existing non-empty PNPM_HOME is preserved; machine-local overrides can live in ~/.config/fish/conf.d/*.local.fish. This config sets paths; it does not install pnpm. When migrating an already-running shell with the old exported Mac path, run set -e PNPM_HOME before sourcing ~/.config/fish/config.fish, or open a fresh SSH session.

Git signing

Git commit signing is deliberately deferred on new machines. Bootstrap first, then import or create a GPG key. Once gpg --list-secret-keys --keyid-format=long shows the signing key, add it to ~/.config/chezmoi/chezmoi.toml:

[data]
    gitSigningKey = "YOUR_KEY_FINGERPRINT"

Then run chezmoi apply. The generated Git config will only set user.signingkey, gpg.program, commit.gpgsign, and tag.gpgsign when that machine-local key is present.

Day-to-day

chezmoi edit ~/.config/fish/config.fish   # edit source, not the live file
chezmoi diff                              # preview pending changes
chezmoi apply                             # write changes to $HOME
chezmoi cd                                # jump to the source repo, then git push

chezmoi re-add picks up changes you made directly to a live tracked file.

Repo layout

Dotfiles live under home/ — chezmoi's source root, set via the .chezmoiroot file — so the repo root holds only meta (README, .gitignore). The home/ tree mirrors $HOME exactly (private_ prefixes just preserve 0700 perms).

What's tracked (→ target in $HOME)

• ~/.config/fish/ — config.fish, conf.d/, autoloaded functions/
• ~/.config/starship.toml
• ~/.config/git/config (XDG; commit signing enabled only when gitSigningKey is configured) + ~/.config/git/ignore
• ~/.config/vim/vimrc (XDG; needs Vim ≥ 9.1.0327)
• ~/.Brewfile — Homebrew package manifest (see below)
• ~/.codex/AGENTS.md and ~/.claude/CLAUDE.md — portable working agreements
• ~/.pi/agent/AGENTS.md and ~/.config/opencode/AGENTS.md — symlinks to the Codex agreement

Agent working agreements

Edit home/dot_codex/AGENTS.md for Codex, Pi, and OpenCode. Chezmoi manages relative symlinks from Pi and OpenCode to ~/.codex/AGENTS.md, so all three read the same file. Keep Claude separate in home/dot_claude/CLAUDE.md. App settings and other agent state stay local.

Preview and apply only these files:

chezmoi diff ~/.codex/AGENTS.md ~/.claude/CLAUDE.md ~/.pi/agent/AGENTS.md ~/.config/opencode/AGENTS.md
chezmoi apply ~/.codex/AGENTS.md ~/.claude/CLAUDE.md ~/.pi/agent/AGENTS.md ~/.config/opencode/AGENTS.md

Review live changes before applying. To capture edits made to either installed file, use chezmoi re-add ~/.codex/AGENTS.md ~/.claude/CLAUDE.md, then review and commit the source diff.

Packages

~/.Brewfile lists the Homebrew formulae to install. The run_onchange_after_install-packages.sh script runs brew bundle install --global --no-upgrade on every chezmoi apply, so a fresh machine installs everything missing, and the script re-runs automatically whenever the Brewfile changes. --no-upgrade means it only installs what's absent — it never upgrades or uninstalls. Add/remove a brew "..." line and chezmoi apply to sync.

What's deliberately NOT tracked (see .chezmoiignore)

• Other contents of ~/.claude/ and ~/.codex/ — app settings, credentials, sessions, and other machine-local state stay excluded; only the working agreement files above are synced
• fish_variables — machine-local universal vars (incl. transient tokens)
• fish/completions/ — auto-generated by tools, except the tracked AWS CLI bridge
• Machine-local / environment-specific configs — kept out of this repo and applied only on the machines that need them.