Personal configuration for initializing a new Apple Silicon Mac, Ubuntu or Debian host, or WSL2 environment. The repository initializes machines; it is not a continuous multi-host synchronization system.
Complete machine setup is agent-assisted. The tracked deploy-dotfiles skill
audits the target, follows the installation contracts in this README, links
explicit GNU Stow packages, and verifies the result. The repository deliberately
does not provide or maintain a standalone bootstrap program.
Tracked dotfiles remain configuration source. Module-owned installers handle
the few operations that need deterministic local behavior, while ./check
provides scoped checks and the repository-wide validation gate. Stow runs from
the repository root, where .stowrc disables tree folding: a tool that creates a
new file writes beside the link instead of into the repository, but a tool that
rewrites a tracked file writes through its link. Treat such a rewrite as a
reviewed dotfiles change, never as silent machine state.
Terminal applications use their native Gruvbox themes or plugins rather than a generated shared theme. Prefer colors from the original Gruvbox palette; use Gruvbox Material only for roles the original palette does not provide or when a softer Material variant is intentional. Non-palette colors require a documented functional reason.
The tmux package keeps tmux-native snapshots of both palettes under
.config/tmux/palettes. Each snapshot pins its upstream source revision. Review
the upstream diff before updating a snapshot; palette updates are never applied
automatically.
Clone the repository, enter it, and start an agent that supports repository skills:
git clone https://github.com/hza2002/dotfiles.git ~/dotfiles
cd ~/dotfilesAsk the agent to use $deploy-dotfiles to initialize the machine. It presents
the applicable deployment contract and waits for approval before changing the
system. Git and a repository-skill-aware agent are the only entry-point
requirements; the skill handles platform-specific requirements and resumable
deployment.
The Zsh package targets Zsh 5.9 or newer on macOS and Linux. macOS uses the
system /bin/zsh; installing a second Homebrew Zsh is unnecessary.
.zshenvcontains the small environment shared by every Zsh invocation..zprofileinitializes the login environment andPATH..zshrcowns interactive behavior, plugins, aliases, key bindings, and platform-specific integrations..config/fzfcontains the fzf shell integration and preview script.
The shell initializes Starship when it is installed. Starship configuration is owned by its separate package because Yazi consumes it too.
Login shells expose the installed jenv shims to scripts and agents. Fnm selects the current project's Node version at startup and on directory changes; required versions must already be installed. Plugin updates only display reminders and run when explicitly requested.
Read these files for the current behavior. Plugin names, aliases, key bindings, and optional tool paths are intentionally not duplicated here.
The deployment contract for this package is:
- use the system Zsh and Homebrew dependencies on macOS, and apt on Ubuntu or Debian;
- install Eza as the interactive
lsreplacement; - install incompatible or unavailable Linux tools from pinned upstream releases
under
~/.local, with commands exposed through~/.local/bin; - install Oh My Zsh and the custom plugins below by following each upstream repository's current installation and update instructions;
- install Jenv, a default JDK, Gradle, Maven, Ant, and Miniconda;
- stop for user input instead of replacing an unknown existing installation.
| Plugin | Upstream repository |
|---|---|
autoupdate |
https://github.com/TamCore/autoupdate-oh-my-zsh-plugins |
fzf-tab |
https://github.com/Aloxaf/fzf-tab |
you-should-use |
https://github.com/MichaelAquilina/zsh-you-should-use |
zsh-abbr |
https://github.com/olets/zsh-abbr |
zsh-autosuggestions |
https://github.com/zsh-users/zsh-autosuggestions |
zsh-completions |
https://github.com/zsh-users/zsh-completions |
zsh-history-substring-search |
https://github.com/zsh-users/zsh-history-substring-search |
zsh-lazyload |
https://github.com/qoomon/zsh-lazyload |
zsh-syntax-highlighting |
https://github.com/zsh-users/zsh-syntax-highlighting |
zsh-vi-mode |
https://github.com/jeffreytse/zsh-vi-mode |
These repositories currently follow their upstream default branches; the
dotfiles do not pin their commits. .zshrc remains the source of
truth for which plugins are enabled.
The Starship package provides the shared Gruvbox prompt configuration used by Zsh and Yazi. Install Starship before linking the package on macOS, Ubuntu, Debian, or WSL.
The btop package selects its built-in gruvbox_dark_v2 theme and disables the
theme background so terminal transparency remains visible. Its tracked config
also disables automatic saves; persistent changes must be made in the dotfiles
instead of through btop's options menu. Install btop with Homebrew on macOS or
apt on Ubuntu or Debian.
The Bat package keeps the custom Gruvbox Material theme used by the shell and
file previews. Use Homebrew on macOS and apt on Ubuntu 24.04 or newer. Ubuntu's
package may expose only batcat; when bat is absent, deployment must link
~/.local/bin/bat to the installed batcat executable.
After linking the package, run bat cache --build and verify that
gruvbox-material-dark appears in bat --list-themes. The generated cache is
runtime data and must not be stored in this repository.
The GnuPG package configures pinentry for signed Git commits. It uses the native
macOS prompt in a regular local shell and the terminal prompt in tmux, over SSH,
and on Linux or WSL. Install GnuPG plus pinentry-mac on macOS, or GnuPG plus
pinentry-curses on Ubuntu or Debian.
A host that never signs commits, such as a headless server, does not need this
package: link it only where a signing key exists. The Zsh configuration tolerates
its absence because GPG_TTY is exported only when the shell has a terminal.
Before linking the package, create ~/.gnupg with mode 0700. After linking,
restart the agent with gpgconf --kill gpg-agent and verify a signed commit or
equivalent signing operation. Private keys, trust data, and the selected Git
signing key are machine state and must not be stored in this repository.
The tmux package targets tmux 3.4 or newer. Runtime gates keep one configuration
working across that range: 3.5 adds extended-keys-format csi-u, and 3.7
switches to message-format with styled prompt labels and hints. Older versions
fall back to the plain prompts instead of failing the load, and the copy-mode
tests branch on the formats the running tmux reports. tmux.conf
is an ordered entrypoint; the files in conf own
options, bindings, theme inputs, plugins, and final UI overrides. Ordinary
reloads skip plugin initialization, so restart tmux after changing theme inputs
or plugin declarations. The scripts directory includes a Ghostty-only cursor
sampling helper: when a selected TUI pane hides its hardware cursor, tmux briefly
exposes the pane center so Ghostty can animate the cursor trail to its destination.
TPM declares and loads hza2002/tmux-agent-sidebar. On development machines,
~/.config/tmux/plugins/tmux-agent-sidebar may instead link to the maintained
local working copy, so source and release builds are available immediately.
While that link is active, update the working copy directly rather than asking
TPM to update the sidebar because TPM follows the link into the checkout. Local
source changes and reviewed upstream merges take effect only after
cargo build --release; the runtime never checks or downloads GitHub Releases.
Copy mode targets the clipboard of the attached terminal client through OSC 52, including through SSH and nested tmux sessions. Unsupported terminal clients still retain the selection in tmux's paste buffer.
The deployment contract for this package is to install tmux, TPM, the TPM
plugins declared in conf/plugins.conf, sesh, and fzf; optionally replace the
TPM sidebar checkout with the maintained local working-copy link for development;
build its release binary with Cargo; then configure sidebar hooks for installed
agents. Macism is required only on macOS.
Clipboard integration does not require platform-specific packages; terminal
clients must permit OSC 52 writes.
The Yazi package targets Yazi 26.5.6 or newer on macOS and Linux. The five
tracked files under yazi/.config/yazi are configuration
source; plugins and flavors are generated runtime data and must not be stored in
the repository.
The deployment contract is to use Homebrew on macOS and Yazi's
official signed stable APT repository on Ubuntu or Debian. Install the complete
integration set: file, Git, Starship, Lazygit, Ouch, FFmpeg, 7-Zip, jq, Poppler,
fd, ripgrep, fzf 0.53 or newer, zoxide, resvg, and ImageMagick 7.1.1 or newer.
After Stow links the package, run ya pkg install to install the revisions and
hashes pinned in package.toml. Linux desktop
systems additionally need a supported clipboard helper; headless hosts do not.
The Neovim package targets Neovim 0.12 or newer. Use Homebrew on macOS and
Neovim's official stable release archive under ~/.local on Linux or WSL; do
not use the Ubuntu or Debian package. lazyvim.json
and the files under lua/plugins are the source
of truth for enabled language support and external toolchains.
The deployment contract is to install the base command-line dependencies, link
the package, and synchronize the revisions pinned in
lazy-lock.json with
nvim --headless "+Lazy! restore" +qa before any other Neovim launch: a first
launch that installs the newest revisions instead rewrites the lockfile through
its Stow link. Then let the deferred plugin builds, Mason packages, and
tree-sitter parsers finish. Plugin and tool installation must complete before the
module is reported as installed rather than being deferred to first launch, and
deployment verifies the pins by requiring a clean
git status --porcelain -- nvim/.config/nvim/lazy-lock.json plus a locked commit
in every installed plugin directory.
Automation projects and the Bin and IdeaVim packages are installed only on a
personal macOS workstation. Deployment must skip them on Linux, WSL, and
headless hosts. Automation is a collection of independently linked Stow
packages under automation/; currently it contains the chrome-icon project.
These tools require the Homebrew formulas uv and fileicon; the casks
google-chrome, microsoft-edge, and jetbrains-toolbox; and the
bing-rewards uv tool. gruvifier resolves gruvbox-factory@latest through
uvx when explicitly run.
Before bing can run, the Edge profiles Default and Profile 2 must exist,
be signed in to Bing, and the private ~/.config/bing-rewards/config.json must
select Edge as its browser. The directories ~/Pictures/icons and
~/Pictures/unreviewed are also user-owned machine state. Deployment must not
create, populate, or store any of these files in Git.
From the repository root, link Chrome Icon with
stow --dir automation --target "$HOME" chrome-icon, then run
~/.local/libexec/install-chrome-icon-agent to render the current home directory
into ~/Library/LaunchAgents/com.ghot.chrome-custom-icon.plist. Register that
generated plist in the current GUI domain and verify the LaunchAgent. The
generated plist is machine state and is not stored in Git. After installing the
selected JetBrains IDEs, install the IdeaVIM and IdeaVimExtension plugins in
each IDE, link IdeaVim, and reload .ideavimrc.
Deployment installs these commands but never runs bing, gruvifier, or
ricon. They respectively control Edge, modify images, and request elevated
access to change application icons, so each remains an explicit user action.
The Yabai package configures the macOS window-management stack. Deployment
requires the Homebrew formulas asmvik/formulae/yabai,
asmvik/formulae/skhd, felixkratz/formulae/borders, and jq. The qualified
formulas come from two non-core upstream maintainer taps; the agent must show
their sources and ask before adding them.
Grant Accessibility access to yabai and skhd, and Screen Recording access to yabai. The scripting addition also requires manually configuring the partial SIP mode documented for the installed yabai release from macOS Recovery. Deployment must pause for this step and must not attempt to change SIP.
After linking the Yabai package, run suyabai to install the validated,
hash-bound sudoers rule and load the scripting addition. Run it again whenever
Homebrew upgrades yabai; no shell update command calls it automatically. Start
the daemons with yabai --start-service, skhd --start-service, and
brew services start borders.
Apply later configuration changes with
yabai --restart-service, skhd --restart-service, and
brew services restart borders rather than executing yabairc directly, which
would append duplicate rules and signals to the running process.
The SketchyBar package is a macOS-only desktop module built around the configured
Yabai module and SketchyBar. Read the files under
sketchybar/.config/sketchybar for its current
behavior.
Deployment requires Xcode Command Line Tools; the Homebrew formulas
felixkratz/formulae/sketchybar, jq, switchaudio-osx, and fastfetch; and
the casks font-jetbrains-maple-mono and swiftdialog. The qualified formula
comes from a non-core upstream maintainer tap; the agent must show its source
and ask before adding it. The private XQzhaopaiti0517 font must be installed
manually. Deployment pauses when it is missing.
After installing dependencies and fonts, link the package with Stow, run
scripts/install-app-font,
start SketchyBar, and verify the bar and helper processes. The installer fetches
sketchybar-app-font and generates plugins/icon_map.sh. The compiled helper
and generated icon map are runtime files and are not stored in Git.
SketchyBar's Homebrew-managed stdout and stderr remain under
/opt/homebrew/var/log/sketchybar. Logs produced by this configuration are
kept together under ~/Library/Logs/sketchybar, with separate files for config
loading, the helper, and caffeinate. Caches, locks, and persistent state remain
in their owning runtime directories and are not stored in Git.
Ghostty is the macOS terminal client and starts the main tmux session in
~/repo/scratch, leaving ~/repo as the project overview.
Its deployment contract is Ghostty 1.3 or newer and the Homebrew cask
font-jetbrains-maple-mono. Read config for
the current terminal behavior and tmux key translations. The tracked cursor
shader is configuration source; the combined shader retains the smear shader's
upstream revision and MIT notice in its file header.
Raycast extensions are maintained as source under raycast/extensions.
Each extension is bundled with npm run build before its tests and lint checks;
the generated bundle and typings are local runtime output and are not tracked.
The Server extension discovers hosts from ~/.ssh/config, orders them by most
recent use, and opens the selected host in Ghostty, attaching to a tmux session
where the remote has one. Opening gives the window a space of its own through
yabai — the focused one when it is still empty, otherwise a new one directly
right of it. Comments above a Host line annotate the row.
Recent use comes from ~/.zsh_history and the extension's own Raycast storage.
Public addresses and country flags come from Cloudflare DNS-over-HTTPS and
ipwho.is, looked up when a host is selected and cached in Raycast storage for
an hour.
The optional overlay at ~/.config/server/config.json only excludes or renames
hosts and selects their tmux session. Host addresses, users, ports, and keys
remain in ~/.ssh/config and are not owned by this repository.
Use the narrowest relevant check for each touched component, including when
committing several components at once. Run the full ./check only for changes
to shared checking and linking behavior (the check script, .stowrc), or
when repository-wide validation is explicitly requested.
| Command | Scope |
|---|---|
./check |
All repository and component checks |
./check repo |
Cross-package Stow, repository syntax, agent layout |
./check sketchybar |
All SketchyBar tests |
./check sketchybar volume |
Volume classification and plugin boundary tests |
./check sketchybar front_app |
Only front_app_test.sh |
./check tmux |
Startup and copy-mode behavior |
./check tmux copy-mode |
Only copy-mode behavior |
./check zsh |
Zsh startup contract |
./check ghostty |
Ghostty configuration |
./check automation chrome-icon |
Chrome icon installer and plist files |
./check raycast network-control |
One extension's tests and lint |
./check raycast |
All extensions |
Component selections also check the package's Stow links, scoped syntax and
whitespace. SketchyBar accepts any existing *_test.sh stem, such as
caffeinate, temperature, or helper_supervisor; volume additionally runs
the shared plugin boundary tests. Use those shared tests when changing input
handling in Wi-Fi, Yabai, or volume plugins. Test scripts remain directly
runnable with /bin/bash path/to/test.sh for the smallest iteration loop.
Only selected checks require their tools. Platform-specific runtime checks run
only on supported systems; skipped checks are reported. A failing check does not
stop the run: failures are listed together at its end and it exits non-zero.
Raycast lint includes an online author lookup, so an extension's lint can fail
due to network access. No check installs dependencies, updates plugins, or
rewrites tracked configuration. Run ./check --help for selectors; unknown
selections fail.