| name | tool-zsh |
| description | Use zsh for shell startup, profile troubleshooting, and non-interactive command validation. Trigger when the task touches shell behavior, aliases, completions, or prompt startup. |
tool-zsh
When To Use
- Diagnose zsh startup, alias, completion, and prompt-loading issues.
- Validate shell config changes before opening a new interactive session.
- Confirm behavior differences between login, interactive, and non-interactive modes.
Trusted Commands
echo "$SHELL"
zsh --version
zsh -ic 'echo zsh-ok'
zsh -lc 'echo login-shell-ok'
zsh -n ~/.zshrc
zsh -ic 'typeset -f precmd >/dev/null && echo has-precmd'
Safe Defaults
- Run
zsh -n before deploying .zshrc updates.
- Use isolated
zsh -ic checks instead of mutating the current shell.
- Keep snippets POSIX-friendly unless zsh-specific behavior is required.
Common Pitfalls
- Startup files differ by shell mode and can lead to false assumptions.
- Interactive-only commands in
.zshrc can break non-interactive scripts.
- User-specific paths and machine-local values make configs non-portable.
Output Interpretation
- No output from
zsh -n indicates valid shell syntax.
command not found often points to PATH differences by shell mode.
Why It Matters For Agents
- Many setup and prompt issues originate from shell init order.
- Quick non-destructive validation prevents broken shell sessions.
Repo Conventions
- Keep shell defaults cross-platform and user-agnostic.
- Avoid hardcoding usernames, home directories, or host-specific paths.
Trigger Examples
- Should trigger: "Fix a
.zshrc startup error in WSL."
- Should trigger: "Add a zsh alias for
fdfind as fd."
- Should not trigger: "Find references to a Python symbol across the repo."
