Dotfiles ···

Cross-platform (macOS + Linux) dotfiles managed with GNU Stow.

Each top-level directory is a Stow package whose contents mirror $HOME.

Packages

Package	Description
zsh	Zsh config, host-specific settings, SSH agent/cert scripts — README
shell	Shell-agnostic alias, path, and (gitignored) vars — README
nvim	Neovim (lazy.nvim) — README
starship	Starship prompt (kubernetes/teleport aware)
tmux	tmux config + tmux-sessionizer — README
ghostty / foot	Terminal emulators (macOS / Linux)
aerospace	AeroSpace tiling WM (macOS)
hypr	Hyprland compositor (Linux) — README
waybar / dunst / tofi / wal	Wayland bar, notifications, launcher, pywal (Linux)
yazi	Yazi file manager
sesh	sesh tmux session manager
rmpc	Music player client
opencode	opencode agents, config & MCP servers (engram, gitea-mcp)
ssh	Managed ~/.ssh/config (agent/keychain + CA host) — README
bin	Assorted helper scripts — README
xdg-dirs	XDG user directory config
MangoHud	Gaming HUD (Linux)
work	Work-laptop-only overrides (opt-in; gitignored secrets) — see Host-specific config
ca	SSH CA host signing script (sign-key) — CA host only, opt-in; see docs/ssh-cert-setup.md

Requirements

Essential

• GNU Stow
• zsh

Common CLI tools

• starship, fzf, ripgrep, fd
• lsd, lolcat, yazi
• zoxide (smart cd, used by .zshrc and sesh)
• neovim (uses lazy.nvim)

The install script installs these for you. Zsh plugins are also cloned automatically on first shell start into ~/.zsh/plugins (zsh-autosuggestions, zsh-syntax-highlighting, zsh-completions, fzf-tab).

Shell-integrated tools (fzf, zoxide, starship) are loaded conditionally in .zshrc; if any are missing you'll see a single ⚠ missing tools: line at shell startup instead of an error — run ./install to fix.

Install

Clone the repo (anywhere — the installer auto-detects its location):

git clone git@github.com:ahmzaa/dot.git ~/dot
cd ~/dot

Guided install (recommended)

Run the interactive installer:

./install

It will:

• Detect your OS and package manager — macOS (Homebrew, auto-installed if missing) or Linux (apt, pacman, or dnf).
• Install a curated set of core dependencies — git, stow, zsh, fzf, ripgrep, fd, lsd, lolcat, tmux, zoxide (starship, yazi, sesh and opencode are installed only if you select their package).
• Let you choose what to stow via a menu (uses fzf if available, otherwise a numbered prompt). Pick individual packages or a predefined group:
  • core — zsh, shell, nvim, starship, tmux, bin, ssh, xdg-dirs, yazi, sesh
  • desktop-linux — hypr, waybar, dunst, tofi, wal, foot, MangoHud
  • desktop-macos — aerospace, ghostty
  • work — the work package (CoreWeave laptop; opt-in, excluded from all)
  • all — everything except work
• Install per-package dependencies for your selection (e.g. Hyprland for the hypr package, the sesh binary for sesh, or the engram + gitea-mcp MCP servers for opencode).
• Check neovim — compares the packaged version against the latest stable release; if the packaged one is behind you can install the official prebuilt binary instead (into ~/.local).
• Stow your selection and, if you agree, set zsh as your login shell (adding it to /etc/shells first when needed).

It is safe to re-run; stow is applied with --restow.

Manual install

If you'd rather do it by hand:

# install deps with your package manager, then:
stow */          # everything
stow zsh nvim    # or specific packages
chsh -s "$(command -v zsh)"

Host-specific config

zsh detects the OS and hostname (zsh/.config/zsh/os-specific.sh) and sources a matching file from zsh/.config/zsh/hosts/ (each source is guarded so a missing host file is a no-op). See the zsh README for details.

The work package

Work-laptop-only configuration is isolated in its own Stow package so the rest of the repo stays generic. It is excluded from all and only installed if you explicitly pick the work group.

stow work        # on the work laptop only

It provides:

• work/.config/zsh/hosts/CW-DYQN400C5P-L — the work host file (sourced by os-specific.sh on that hostname). Sources ~/.config/work/secrets, exports OPENCODE_CONFIG (see below), and sets up fleet tooling.
• work/.config/opencode/opencode.work.jsonc — an overlay layered on top of the base opencode config via OPENCODE_CONFIG. opencode merges configs, so the base MCP servers stay active and work-only servers are added. Internal URLs come from {env:...} vars defined in the secrets file.
• work/.config/sesh/sesh.toml — a full sesh config (base + work sessions). Because sesh reads a single file, on the work laptop you stow work but not the base sesh package (the installer drops sesh automatically if you pick both).
• work/.config/work/secrets — gitignored; holds internal URLs/tokens. Copy secrets.example to secrets and fill it in on the work machine.

Running the CoreWeave installer

cw-fleet-tools assumes an oh-my-zsh shell rooted at ~/.zshrc. This repo uses neither: plugins come from ~/.zsh/plugins, and .zshenv points ZDOTDIR at ~/.config/zsh. Always run the work installer with both opt-outs:

CW_FT_SKIP_SHELL_SETUP=1 CW_FT_SKIP_ZSHRC=1 \
  ~/coreweave/cw-fleet-tools/scripts/setup/first-time-install_v2.sh

Running it bare does two damaging things:

• Deletes ~/.cw-fleet-tools/.skip_shell. recordSkipShell rewrites that flag every run and removes it unless --skip-shell is passed. Without it, setup/source sources setup/shell/source, which forces ZSH=$HOME/.oh-my-zsh, overrides plugins=(...), and re-runs starship init — double-wrapped ZLE widgets and FUNCNEST errors. Re-create it with: mkdir -p ~/.cw-fleet-tools && touch ~/.cw-fleet-tools/.skip_shell
• Rewrites ~/.zshrc. migrateZshrc hardcodes $HOME/.zshrc and is unaware of ZDOTDIR, so it writes a file zsh never reads and backs the old one up to ~/.zshrc.bak.<epoch>. Harmless but confusing — the real file is ~/.config/zsh/.zshrc.

Separately, never let the oh-my-zsh installer run with ZDOTDIR set. It renames $ZDOTDIR/.zshrc to .zshrc.pre-oh-my-zsh — which silently turns the stow symlink into a dangling leftover — and drops its own template in place. To recover: rm ~/.config/zsh/.zshrc && mv ~/.config/zsh/.zshrc.pre-oh-my-zsh ~/.config/zsh/.zshrc.

opencode & MCP servers

The opencode package ships the config, agents, plugins, and two local MCP servers referenced by opencode.jsonc:

• engram — persistent memory
• gitea-mcp — Gitea integration

Selecting opencode in the installer installs opencode itself, then downloads the official prebuilt binaries for both MCP servers into ~/.local/bin (falling back to go install). Both servers are referenced by bare command name, so they resolve from PATH on any machine.

After stowing, the installer runs engram setup opencode, which generates plugins/engram.ts. That file is not tracked by this repo — it is gitignored and regenerated per host, because engram bakes a host-specific binary path into it (a /nix/store/... path where engram comes from nix, ~/.local/bin elsewhere). Stow folds ~/.config/opencode into a symlink back into this repo, so the command writes through it; tracking the result meant a permanently dirty working tree that churned on every engram upgrade. On a fresh machine, run engram setup opencode (or the installer) to produce it.

Docs

• SSH agent & certificate setup

Questions?

support@ahmza.com