Config¶

📋 This guide covers where every config file lives, when it runs, how overrides work, and how to extend the framework with your own code.

🔗 Related documents¶

The framework is opinionated by default but fully overridable. You should never need to edit framework files — everything is customizable from your config directory. Same basename in config replaces the framework file; different name adds.

Quick start (first time)¶

1. Create your config dir: Run zsh setup.zsh from the framework repo (or use the cloner); this creates ~/.config/zshand/ with template files.
2. Or copy from samples: cp -r samples/user-config/* ~/.config/zshand/ then edit to taste.
3. Set env and secrets: Edit env.zsh (EDITOR, PATH, framework flags) and secrets.zsh (API keys; keep chmod 600).
4. Rebuild after changes: Run zr (or zfull if using full bundle) then exec zsh.

When each file or directory runs¶

See also: Architecture (boot sequence) · Startup (what runs before core)

📁 Config Directory¶

All user configuration lives under a single XDG-compliant directory:

~/.config/zshand/                   ($ZSHAND_CONFIG_DIR)

Override the location by setting ZSHAND_CONFIG_DIR in your environment before the shell starts (e.g., in ~/.zshenv).

📂 Directory structure¶

~/.config/zshand/
├── 🌍 env.zsh             Environment variables (auto-exported)
├── 🔒 secrets.zsh         API keys and tokens (chmod 600)
├── 📝 aliases.zsh         Custom aliases (loaded after framework)
├── 🛤️ path.txt            Additional PATH entries (one per line)
├── ⚙️ config.toml         Framework behavior (see reference below)
├── 📦 packages.toml       Package lists, tools, deactivation (see below)
├── ⌨️ keybindings.toml    Widget keybindings (optional; or use [keybindings] in config.toml)
├── 📟 bin/                Personal scripts (added to $PATH)
├── 🛠️ functions/         Custom zsh functions
├── ⌨️ widgets/            Custom ZLE widgets
├── 🪨 hooks/              Custom integration hooks
├── ⚙️ rc.d/               Core overrides (same basename = replace)
├── 🚀 init.d/             Pre-initialization scripts
├── 🏁 post.d/             Post-initialization scripts
└── 🔌 plugins/            OMZ/P10k plugins (NN-name.zsh, optional plugins.txt)

Run zsh setup.zsh from the framework repo to create this structure with template files, or copy from samples/user-config/. Set ZSHAND_CONFIG_DIR (e.g. in ~/.zshenv) to use a different path.

📊 Load Order¶

Understanding when each file loads helps you decide where to put things. Note: config.toml is read by core/02_vars before it sources env.zsh and secrets.zsh, so TOML values can be overridden by those files.

┌─ Shell starts ─────────────────────────────────────────────┐
│  1. 🚀 init.d/*.zsh        Early overrides (before core)   │
│  2. ⚙️ config.toml         Read by 02_vars (before env)     │
│  3. 📦 packages.toml       Resolve packages + deactivation  │
│  4. 🌍 env.zsh             Environment variables            │
│  5. 🔒 secrets.zsh         API keys (auto-exported)         │
│  6. 🛤️ path.txt + bin/     PATH configuration               │
│  7. ⚙️ rc.d/*.zsh          Core overrides (merged with core)│
│  8. ⚙️ Framework core      02_vars → 04_path → ... → 90    │
│  9. 🪨 Framework hooks     Tool integrations                │
│ 10. 🛠️ functions/          Your custom functions            │
│ 11. ⌨️ widgets/            Your custom widgets              │
│ 12. 🪨 hooks/              Your custom hooks                │
│ 13. 📝 aliases.zsh         Your aliases (can override)      │
│ 14. 🏁 post.d/*.zsh        Final tweaks (after everything)  │
└─ Shell ready ──────────────────────────────────────────────┘

📦 Package Configuration (packages.toml)¶

Controls which packages, tools, and plugins are installed and active. Uses a 4-level cascade — framework defaults are always present; you only need to override what you want to change.

Quick examples¶

# ~/.config/zshand/packages.toml

# Disable a tool you don't want
[packages.defaults]
atuin = false      # Skips install, sets ZSHAND_ATUIN_IS_DEACTIVATED=1
neovim = false     # Uses vim instead

# Add extra packages for your OS
[packages.ubuntu]
htop = true
glances = true

# Add tools to mise
[tools.defaults]
deno = "latest"
bun = "latest"

# Override preferences
[preferences]
js_runtime = "bun"

How deactivation works¶

When a package is set to false:

1. It is not installed by the installer
2. ZSHAND_<NAME>_IS_DEACTIVATED=1 is exported at startup
3. Related hooks are skipped (e.g., hooks/02_atuin.zsh checks the env var)
4. Related aliases fall back (e.g., bat → cat, eza → ls)
5. Related widgets are unbound (e.g., fzf pickers)

Available sections¶

📎 See samples/user-config/packages.toml for the full reference with all options documented.

🌍 Environment Variables (env.zsh)¶

Machine-specific environment variables. This file is sourced with set -a (auto-export), so every variable is automatically exported.

# env.zsh — Machine-specific environment variables

EDITOR="nvim"
BROWSER="firefox"
MACHINE_ID="workstation"

# Framework controls
ZSHAND_DEBUG=0
ZSHAND_LAZY_LOAD=1
ZSHAND_AUTO_FULL=1

# Tool-specific
DOCKER_HOST="unix:///run/user/1000/docker.sock"

💬 The framework also writes ZSHAND="/path/to/zshand" into this file during setup. Don't remove it.

🔒 Secrets (secrets.zsh)¶

API keys, tokens, and sensitive credentials. Automatically secured with chmod 600 during setup. Never commit this file.

# secrets.zsh — Sensitive credentials (chmod 600)

GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
OPENAI_API_KEY="sk-xxxxxxxxxxxx"
AWS_ACCESS_KEY_ID="AKIAXXXXXXXX"
AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxx"
CLOUDFLARE_API_TOKEN="xxxxxxxxxxxxxxxx"

This file is protected by chmod 600 (owner-read-only). The framework re-enforces permissions on every startup via core/06_engine.zsh. Gitleaks scans also check that secrets never leak into the repo.

📝 Aliases (aliases.zsh)¶

Custom aliases loaded after framework aliases, so they can override:

# aliases.zsh — Custom aliases

alias ll='eza -lahF --icons'
alias gst='git status'
alias dc='docker compose'
alias k='kubectl'
alias tf='terraform'

# Override a framework alias
alias ls='eza --icons --group-directories-first'

🛤️ PATH (path.txt)¶

Additional directories to prepend to $PATH, one per line. Lines starting with # are ignored.

# path.txt — Additional PATH entries

/opt/custom/bin
~/.cargo/bin
~/.npm-global/bin
~/.local/share/mise/shims

Your bin/ directory is also automatically added to $PATH.

⚙️ Framework settings (config.toml)¶

config.toml is read very early (before env.zsh). Each section.key is exported as ZSHAND_SECTION_KEY (e.g. [performance].perf_budget → ZSHAND_PERF_BUDGET). Booleans become 1/0; ~ in paths is expanded.

Main sections (reference)¶

Full commented example: samples/user-config/config.toml. Changes take effect on next shell (no rebuild needed).

Minimal example¶

# config.toml

[general]
theme_config = "~/.p10k.zsh"

[performance]
perf_budget = 100
auto_mode = true

[lazy_loading]
lazy_load = true

🚀 Pre-Initialization (init.d/)¶

Scripts that run before the framework loads. Use this for:

• Machine-specific overrides that must be set early
• Environment variables that affect framework behavior
• Workarounds that need to run before core logic

# init.d/00_machine_overrides.zsh
export ZSHAND_LAZY_LOAD=1
export ZSHAND_AUTO_FULL=1

# init.d/10_work_vpn.zsh
[[ -f /etc/vpn-active ]] && export HTTP_PROXY="http://proxy:8080"

Naming: Use NN_ prefix for load order (00 = first, 99 = last).

🏁 Post-Initialization (post.d/)¶

Scripts that run after everything else. Use this for:

• Final overrides that need all framework functions available
• Customizations that depend on hooks being loaded
• Prompt tweaks that should be the absolute last thing

# post.d/00_final_env.zsh
# Set variables that depend on framework functions
export MY_PROJECT_DIR="$(git rev-parse --show-toplevel 2>/dev/null)"

# post.d/99_prompt_tweaks.zsh
# Final prompt customization (after P10k loads)
typeset -g POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(dir vcs)

⚙️ Core Overrides (rc.d/)¶

Replace any framework core file by placing a file with the same basename in rc.d/. The framework merges both directories and user files win:

Framework: $ZSHAND/core/14_aliases.zsh       ← default
User:      ~/.config/zshand/rc.d/14_aliases.zsh  ← loaded INSTEAD

Framework: $ZSHAND/core/10_options.zsh       ← default
User:      ~/.config/zshand/rc.d/11_my_options.zsh  ← loaded ALONGSIDE (odd number)

Rules:

• Same basename → replaces framework file entirely
• Different basename → adds to load sequence (use odd numbers)

Example — add PATH entries between 04_path and 06_engine:

# rc.d/05_my_path.zsh — loaded after 04_path, before 06_engine
path+=( /opt/my-tools/bin )

🛠️ Custom Functions (functions/)¶

Drop .zsh files here to add your own functions:

# functions/greet.zsh
greet() {
    print -P "%F{green}Hello, ${1:-world}!%f"
}

These are loaded after framework functions and can override them.

⌨️ Keybindings (keybindings.toml or config.toml)¶

Widget keybindings can live in a dedicated file keybindings.toml or in a [keybindings] section of config.toml. Loaded by startup/17_az_bindkey_from_toml.zsh after default bindings.

Format: "key" = "widget_name". Key names use lowercase with hyphens: ctrl+g, alt+m, f12. Empty value unbinds the key.

# keybindings.toml (or [keybindings] in config.toml)

[keybindings]
"ctrl+g" = "aicmit"       # AI commit
"ctrl+d" = "aidebug"     # AI debug
"ctrl+p" = "pastem"     # Smart paste
"ctrl+o" = "copym"      # Copy line
"alt+m"  = "manf"       # Man page search

See Widgets for built-in widget names. After changing keybindings, reload with exec zsh (no zr needed).

⌨️ Custom widgets (widgets/)¶

ZLE widgets for keyboard shortcuts:

# widgets/my_widget.zsh
my_widget() {
    BUFFER="echo hello"
    zle accept-line
}
zle -N my_widget

Bind in keybindings.toml or [keybindings] in config.toml:

[keybindings]
"ctrl+h" = "my_widget"

🪨 Custom hooks (hooks/)¶

Integration hooks for tools not covered by the framework:

# hooks/50_my_tool.zsh
if (( $+commands[my_tool] )); then
    eval "$(my_tool init zsh)"
fi

Use numbering (e.g. 50_) to control order; same basename as a framework hook replaces it. See Hooks.

🔌 Plugins (plugins/ and plugins.txt)¶

The framework loads plugins from ~/.config/zshand/plugins/. Files named NN-name.zsh (e.g. 50-zsh-autosuggestions.zsh) are loaded in numeric order and compiled into the full bundle. Syntax highlighting must load last — use prefix 99.

• Bundle P10k config: Copy ~/.p10k.zsh to plugins/05-p10k-theme.zsh for faster startup; run zr after changes.
• Add a plugin: Copy plugin source into plugins/NN-plugin-name.zsh or add a wrapper that sources the system path.
• Optional plugins.txt: List plugins with prefixes: none = immediate, ~ = lazy (after first prompt), + = deferred; - = disabled. If plugins.txt exists, only listed plugins load.

Full details and OS-specific paths: samples/user-config/plugins/README.md.

📟 Personal scripts (bin/)¶

Executable scripts placed here are automatically added to $PATH:

#!/usr/bin/env zsh
# bin/my_script
echo "Hello from my_script"

Make them executable: chmod +x ~/.config/zshand/bin/my_script

🔄 Complete Override (zshrc.zsh)¶

For total control, create ~/.config/zshand/zshrc.zsh. This completely replaces the framework — nothing else loads:

# zshrc.zsh — Complete framework replacement
# WARNING: This disables ALL framework features
source ~/.config/zshand/env.zsh
source ~/.config/zshand/aliases.zsh
# ... your custom setup

This is a full replacement — no framework code runs at all. Only use this if you need complete control over your shell setup.

🌍 Key environment variables¶

Set these before the framework loads (e.g. in ~/.zshenv or env.zsh). Many can also be set via config.toml (see table above).

❓ Troubleshooting¶

See Troubleshooting and Safe Mode for more.

🔗 Related documents¶