configuring-zsh

name	configuring-zsh
description	Configure and troubleshoot Zsh shell. Use when editing .zshenv, .zprofile, .zshrc, .zlogin, or .zlogout, setting up powerlevel10k prompt, configuring oh-my-zsh or sheldon plugin manager, fixing PATH or environment variables, debugging slow shell startup, setting up completions/compinit/fpath, or working with zsh-autocomplete, zsh-autosuggestions, or zsh-syntax-highlighting plugins.

Zsh Shell Configuration

Quick Reference

Topic	Reference
Startup file order	startup-files.md
oh-my-zsh patterns	oh-my-zsh.md
powerlevel10k setup	powerlevel10k.md
sheldon plugin manager	sheldon.md
Plugin load order	plugins.md
Performance tuning	performance.md

Workflow Decision Tree

Need to...	Action
Set env vars / PATH / locales	Read startup-files.md → edit .zshenv or .zprofile
Configure aliases, keybinds, completions, prompt	Edit .zshrc
Fix performance issues	Read performance.md → profile startup
Add/configure plugins	Read plugins.md + relevant manager reference

Chezmoi Integration

• Edit Zsh configs in the chezmoi source (this repo), not directly in ~
• Respect {{ ... }} template blocks in files
• Source naming: dot_zshrc → ~/.zshrc, private_dot_config/sheldon → ~/.config/sheldon
• For chezmoi workflows, see managing-chezmoi skill

Default Guardrails

• Keep .zshenv idempotent and fast; no external commands
• No aliases/functions in .zshenv
• Use typeset -gx VAR=... or export VAR=... with defensive checks
• Set fpath before compinit; run compinit once only
• Document plugin load order (especially zsh-autocomplete + zsh-syntax-highlighting)

Common Tasks

Task	Approach
Add env var	.zshenv (everywhere) vs .zprofile (login) vs .zshrc (interactive)
Fix PATH	Ensure ordering, remove duplicates, avoid PATH=$PATH:... in multiple files
Enable completions	Set fpath → compinit once → cache if needed
Add plugin	Choose manager → ensure correct load order
Setup p10k	Instant prompt block first in .zshrc → source ~/.p10k.zsh after plugins