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 [email protected]: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-copilot – GitHub Copilot CLI
• install-cursor – Cursor
• install-cursor-cli - Cursor CLI terminal agent via the native installer (~/.local/bin). Use update-cursor-cli to update it, or uninstall-cursor-cli to remove it. Its updater also runs through update-all.
• 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-java - Amazon Corretto 25 LTS JDK via Homebrew (macOS). Sets JAVA_HOME and PATH, preserving an existing valid JAVA_HOME. Use uninstall-java to remove it; update-brew handles patch updates.
• 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

• dotenv – dotenv [-e environment] [--] command [args...] runs an executable with variables from .env, .env.local, and, with -e, .env.{environment} and .env.{environment}.local, in that order. Only the current directory is searched; missing files are skipped. Later values override earlier ones and inherited environment variables without changing your shell.

  Files accept KEY=value, optional export, blank lines, comments, and LF or CRLF endings. Keys use letters, digits, and underscores and cannot start with a digit. Surrounding whitespace is ignored; outer single or double quotes are removed. Inline comments require whitespace before #; a # inside quotes or attached to a value is literal. Values are literal: variables, command substitutions, backticks, and escapes are never expanded. Multiline values and concatenated quoted fragments are unsupported. Invalid or unreadable files abort execution with a location-only diagnostic, without printing values. Loaded variables can still affect the executable's behavior.

  Examples: dotenv -- bun run dev or dotenv -e production -- bun run start.

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.