The Art of Maintenance-Free macOS Automation.
.zen is an opinionated, privacy-first dotfiles framework designed to bootstrap a fresh Mac into a powerhouse development machine in minutes. It separates Public Configuration (this repo) from Private State (your Gist), giving you the best of open-source sharing and secure personal backup.
How does zen-load orchestrate your setup? Here is the decision tree it follows:
flowchart TD
Start([Start zen-load]) --> Sudo{Sudo Auth}
Sudo -->|Success| Init[Init Dependencies]
Init --> CheckBrew{Brew Installed?}
CheckBrew -->|No| InstallBrew[Install Homebrew Core]
CheckBrew -->|Yes| CheckStow{Stow Installed?}
CheckStow -->|No| InstallStow[Brew Install Stow]
CheckStow -->|Yes| InstallDF[Install/Link dfsync]
InstallDF --> Resolve[Resolve Conflicts<br/>Backup ~/.zshrc...]
Resolve --> PromptShell{ Prompt: <br/>Stow Shell Env? }
PromptShell -->|Yes| ActivateShell[dfsync_activate<br/>zshrc, starship...]
ActivateShell --> PullShell{Confirm Pull?<br/>Overwrite Repo?}
PullShell -->|Yes| RestoreShell[Update .zen/stow/...]
PullShell -->|No| SkipShellRest[Keep Git Version]
RestoreShell --> StowShell[Stow: zsh, starship]
SkipShellRest --> StowShell
PromptShell -->|No| Next1
StowShell --> Next1[Next Module]
Next1 --> PromptApp{ Prompt: <br/>Other Apps? }
PromptApp -->|Yes| ActivateApp[dfsync_activate<br/>vscode, wezterm...]
ActivateApp --> PullApp{Confirm Pull?}
PullApp -->|Yes| RestoreApp[Update .zen/stow/...]
PullApp -->|No| SkipAppRest
RestoreApp --> StowApp[Stow: vscode, wezterm]
PromptApp -->|No| Next2
Next2 --> PromptSys{ Prompt: <br/>Apply Defaults? }
PromptSys -->|Yes| ActivateSys[dfsync_activate<br/>System Configs...]
ActivateSys --> PullSys{Confirm Pull?}
PullSys -->|Yes| RestoreSys[Update manifests/private/...]
RestoreSys --> ApplyDef[defaults.sh<br/>LaunchAgents]
PromptSys -->|No| Done
Done([Zen Load Complete])
classDef prompt fill:#f9f,stroke:#333,stroke-width:2px;
classDef action fill:#bbf,stroke:#333,stroke-width:1px;
classDef auto fill:#dfd,stroke:#333,stroke-width:1px;
class Start,Done action
class PromptShell,PromptApp,PromptSys prompt
class Init,CheckBrew,InstallBrew,CheckStow,InstallStow,InstallDF,Resolve auto
Unlike massive Ansible playbooks or opaque scripts, .zen uses GNU Stow. Your config files live in ~/.zen/stow/ and are symlinked to their target locations.
- Want to change a config? Edit it properly in
~/.zen. - Want to remove a package?
stow -D package. - Conflict?
zen-loadautomatically detects and backs up existing files before linking.
Most dotfiles repos expose your secrets or force you to use a separate private repo. .zen uses a hybrid approach:
- Public Repo: Contains templates, scripts, generic configs (
.zshrc,wezterm.lua). - Private Gist: Contains YOUR specific overrides and secrets (API keys, private env vars).
- The Magic:
zen-loadintelligently merges them. It pulls your private state from Gist (viadfsync) over the public templates, then symlinks the result.
Need to store API keys or work-specific aliases that shouldn't be in the public repo? .zen checks for optional Private Overrides that are ignored by git but synced by dfsync:
- Shell:
~/.zshrc.local(Sourced automatically by .zshrc) - WezTerm:
~/.config/wezterm/wezterm-private.lua(Merged automatically) - Git:
~/.gitconfig.local
Just create these files, and zen-save will back them up to your private Gist!
zen-load is not "all-or-nothing". It asks you what you want to install:
- 📦 Shell Engine: Zsh, Starship, Git, Binaries.
- 💻 Terminal: WezTerm (GPU-accelerated, Lua-configured).
- 🚀 Neovim: LazyVim-based Power User setup (Lua, LSP, Treesitter).
- 📝 Editor: VS Code (Settings, Keybindings, Extensions).
- 🍎 System: macOS Defaults, Dock layout, Finder tweaks.
git clone https://github.com/snvishna/.zen.git ~/.zen
~/.zen/stow/bin/.local/bin/zen-loadzen-load will launch an interactive wizard:
- Dependencies: Automatically installs Homebrew and Stow if missing.
- dFsync: Downloads the latest cloud sync tool.
- Restore: Asks for your Gist ID (optional).
- New User? Leave blank. A new Gist will be created when you first push.
- Existing User? Enter ID. It will pull your private configs.
- Modules: Prompt-by-prompt installation of Shell, Terminal, Editor, and System tweaks.
- New machine? Run
zen-loadto restore environment.
- Made changes? Run
zen-saveto snapshot state.
flowchart TD
Start([Start zen-save]) --> Init[Init Paths & Logs]
Init --> DumpBrew["Dump Homebrew<br/>(Brewfile)"]
DumpBrew --> DumpNPM["Dump NPM Globals<br/>(npm_globals.txt)"]
DumpNPM --> DumpVS["Dump VS Code Exts<br/>(extensions.txt)"]
DumpVS --> DumpApps["Audit /Applications<br/>(installed_apps.txt)"]
DumpApps --> DumpSys["Snapshot macOS Defaults<br/>(macos_full_dump.txt)"]
DumpSys --> DumpPriv["Snapshot Private Configs<br/>(Raycast, Rectangle Plists)"]
DumpPriv --> Sync{Flag: --local?}
Sync -->|Yes| Finish([Snapshot Complete])
Sync -->|No| Push["dfsync push<br/>(Sync to Gist)"]
Push --> Finish
classDef action fill:#bbf,stroke:#333,stroke-width:1px;
classDef decision fill:#f9f,stroke:#333,stroke-width:2px;
class Start,Finish action
class Sync decision
| Key / Command | Action |
|---|---|
| Up Arrow | Atuin Magical History Search (Sync & Full-text) |
Cmd + R |
Atuin History Search |
Ctrl + T |
FZF File Search |
ffa |
Find File All (includes gitignored files) |
fta |
Find Text All (includes gitignored text) |
fzf-all |
Run FZF including all ignored files |
| Shortcut | Action |
|---|---|
Cmd + S |
Switch Workspace (Launcher) |
Cmd + Shift + N |
New Workspace (Prompt Name) |
Cmd + Opt + W |
Kill Current Workspace (Safety: Switches to default first) |
Cmd + Shift + [ / ] |
Cycle Workspaces |
| Feature | Description |
|---|---|
| Zen Glass | Custom WezTerm config with 90% opacity, blur, and "Editor-like" bindings (Cmd+C/V). |
| Smart Shell | Zsh + Starship with autosuggestions, fzf-tab completion, and localized history. |
| Neovim Power | LazyVim foundation with seamless WezTerm navigation (Ctrl+hjkl), Obsidian notes, and full LSP. |
| Time Travel | Atuin replaces shell history, syncing commands across machines securely. |
| Auto-Heal | zen-save automatically snapshots your installed apps (Brewfile, installed_apps.txt) and macOS defaults. |
| Conflict-Free | Robust conflict resolution moves old config files to ~/.zen/graveyard/ instead of breaking. |
| Limited Mode | Automatically detects non-root environments and gracefully skips privileged tasks (like permission fixes). |
| Rolling Release | zen-load always fetches the latest stable dfsync binary to ensure compatibility. |
- Setup Guide: Detailed installation & customization.
- Architecture: Deep dive into Stow & Symlinks.
- Tracker: Roadmap & Changelog.
Maintained by the .zen team.