ZDOTFILES

Compact Zsh setup that wires in Antidote for plugins and Starship as the prompt. Everything is driven by a single zshrc.sh so you can drop it into any machine quickly.

Install

1. Clone the repo (defaults to ~/.zdotfiles):

   git clone git@github.com:jcyamacho/zdotfiles.git "$HOME/.zdotfiles"

2. Source the main file from your ~/.zshrc:

   source "${ZDOTFILES_DIR:-$HOME/.zdotfiles}/zshrc.sh"

Customizing

• Keep the repo elsewhere by setting ZDOTFILES_DIR before sourcing.
• Change the editor used by helper commands by exporting EDITOR.
• Adjust where self-managed tools install by overriding CUSTOM_TOOLS_DIR.
• Set GIT_WORKTREE_BASE to change where gwt-new creates worktrees (see git-worktree).

Starship

Starship is the required prompt and installs automatically on first load. Set STARSHIP_CONFIG before sourcing zshrc.sh to override the default ~/.config/starship.toml.

• update-starship updates Starship and reloads the shell.
• starship-config edits the active configuration and reloads the shell.
• starship-preset-custom applies the custom starship.toml.
• starship-preset-nerd-fonts, starship-preset-no-nerd-font, and starship-preset-plain-text apply built-in Starship presets.

Disable alias suggestions (ZSH_DISABLE_YOU_SHOULD_USE)

By default, zsh-you-should-use reminds you when you type a command that has an alias. To disable these suggestions:

# In ~/.zshrc, before the source line:
export ZSH_DISABLE_YOU_SHOULD_USE=1
source "${ZDOTFILES_DIR:-$HOME/.zdotfiles}/zshrc.sh"

Plugins

Antidote reads .zsh_plugins.txt and builds a static .zsh_plugins.zsh. The default setup enables:

• Always-on shell UX: prompt theme (see above), zsh-autosuggestions, syntax highlighting (F-Sy-H), and “you-should-use”.
• Local plugin helpers: small plugins/* scripts that add install-*, update-*, uninstall-*, and *-config helpers.

Many integrations are conditional (they only activate when the underlying binary exists) to keep startup fast and avoid errors.

Installable Tools

These are the install-* helpers (run the command to install; integrations load on reload/next shell start). Tools are grouped by how useful they are for the default shell experience.

Recommended (not installed by default)

Run install-recommended to install every missing tool in this group.

• install-fzf – fzf fuzzy finder (enables fzf-tab if present)
• install-zoxide (or install-z) – zoxide smarter cd
• install-atuin – Atuin synced, searchable history
• install-carapace – Carapace completions
• install-jq – jq
• install-yazi – yazi terminal file manager (Ctrl+o, and y to cd on exit)

Optional

• install-aspire - Aspire CLI for distributed apps
• install-bat – bat cat clone
• install-btop - btop resource monitor
• install-bun – Bun runtime
• install-claude-code – Claude Code CLI
• install-code – VS Code
• install-codex – OpenAI Codex CLI
• install-cmux – cmux native macOS terminal for AI agents
• install-cursor – Cursor
• install-deno – Deno runtime
• install-direnv – direnv + hook
• install-docker – Docker CLI
• install-dotnet - .NET SDK developer platform (dotnet)
• install-dotenvx – dotenvx a secure dotenv
• install-varlock – varlock AI-safe .env files
• install-fabric – Fabric
• install-flutter – Flutter SDK
• install-fnm (or install-node) – fnm + LTS activation
• install-gemini – Gemini CLI
• install-ghostty – Ghostty terminal + config restore
• install-wezterm – WezTerm terminal + config restore
• install-gh – GitHub CLI
• install-go – Go + golangci-lint
• install-herdr - Herdr agent multiplexer that lives in your terminal
• install-just – just command runner
• install-lsd – lsd + config/theme
• install-memo - memo durable memory CLI; includes Claude and Codex memo context hook helpers
• install-mise – mise
• install-nub - Nub all-in-one toolkit for Node.js
• install-ollama – Ollama
• install-openspec – OpenSpec workflow CLI (openspec)
• install-opencode – OpenCode
• install-orbstack - OrbStack Docker Desktop alternative
• install-pi - Pi minimal terminal coding harness
• install-television – Television fuzzy finder; binds Ctrl+T to channel-aware completion (Ctrl+R goes to Atuin when present). Also installs fd and bat, which its channels shell out to
• install-rbenv (or install-ruby) – rbenv
• install-rust – rustup
• install-uv (or install-python) – uv + Python tooling (python)
• install-viteplus – Vite+ unified web toolchain
• install-worktrunk – Worktrunk git worktree management
• install-zed – Zed
• install-zsh-bench – zsh-bench benchmark for interactive zsh
• install-zellij – Zellij terminal workspace (zellij)
• install-zig – Zig
• install-antigravity – Antigravity
• install-agent-browser – agent-browser browser automation CLI
• install-fonts – Homebrew font casks

Utility Plugins

Additional helper functions (no external tool required):

• git – g, gaa, gf, gcb, gcmsg, gc!, ggl, ggp shorthands plus git-pull-all and git-hook
• git-worktree – gwt-* helpers for managing Git worktrees

Utility Functions

Shell helpers from _utils.zsh:

• mkcd <dir> – create a directory and cd into it
• edit <file> – open a file in $EDITOR (defaults to vim)
• home – cd to $HOME
• zsh-config – edit ~/.zshrc and reload
• kill-port <port> – kill the process listening on a given port
• zdotfiles-cache-clean – remove all zdotfiles caches and reload
• cls – alias for clear
• rmf – alias for rm -rf
• cd.. – alias for cd ..

Gist Sync

Sync files and directories to/from private GitHub Gists. See github-cli for details on save-file-to-gist, load-file-from-gist, and related functions.

Updating

• reload – reload the configuration.
• update-zdotfiles – pull the latest repo changes and reload.
• update-antidote – update Antidote and reload.
• update-all – run all registered updaters and reload.

The updates Array

update-all iterates over the updates array and calls each registered function. Plugins register their updaters like this:

_update_mytool() {
  info "Updating mytool..."
  # update logic here
}

updates+=(_update_mytool)

Use an internal _update_* function (no reload) so update-all can batch updates and reload once at the end. Tools installed via Homebrew don't need individual updaters since update-brew runs brew upgrade --greedy.

Performance

• Benchmark before/after changes with zsh-startup-bench.
• Use zsh-startup-profile for a quick zprof-enabled timing run.
• Quick sanity check without launching an interactive shell: zsh -lic exit.