humanerd-drew/opencode-drewgent/shell-init-side-effect-gating
Claude Code and agent skill by humanerd-drew/opencode-drewgent
- community
Checking that the SKILL.md file is still in the repository.
Audit and fix shell init files (zsh/bash) where a side effect (bg fetch, daemon, cache) runs in a context where its consumer (RPROMPT, prompt, key binding) is gated OFF. Trigger when user shows [N] PID job notification on shell login, asks to silence one, or asks to modify .zshrc/.zshenv/.zprofile/.zlogin/.bashrc. Fix pattern - move side effect to consumer's wrapper function, or apply the same gate, or silence with `&!` only after diagnosis.
Install
npx vskill@latest install humanerd-drew/opencode-drewgent/shell-init-side-effect-gatingSKILL.md
The same SKILL.md was published earlier as humanerd-drew/opencode-drewgent/shell-init-side-effect-gating.
Skill: Shell Init Side-Effect Gating
When to load
Trigger when:
- User asks to add or modify
.zshrc/.zshenv/.zprofile/.zlogin/.bashrc/.bash_profile - User shows a
[N] PIDjob notification or other unexpected background process on shell login - User asks to silence a
[N] PIDnotification (audit first, don't just slap&!on it) - Reviewing existing shell init for cleanup or refactor
Steps
- Find all `&` in shell init:
``bash grep -nE '&\s*$' ~/.zshenv ~/.zshrc ~/.zprofile ~/.zlogin 2>/dev/null ``
- For each backgrounded process, identify its consumer (RPROMPT, prompt segment, alias, key binding, function called from elsewhere).
- Check the consumer's gate — is it conditional on a marker file, TTY,
$DISPLAY,uname, etc.?
- Compare gates:
- Consumer gated, side effect not → leak
- Both gated the same way → fine
- Both ungated → fine
- Side effect gated, consumer not → consumer might be missing optimization
- Decide on fix (in this priority order):
- A. Move side effect to consumer's entry point (e.g., wrapper function) — preferred
- B. Apply same gate to side effect — if gate is static at source time
- C. Silence with `&!` — only if leak is acceptable and noise is the only complaint
- D. Make consumer unconditional — only if re-evaluating design intent confirms broad usefulness
- Verify:
``bash zsh -c 'source ~/.{{AGENT_NAME_LOWER}}/.zshrc_aliases; sleep 0.3; jobs -l' 2>&1 `` Should report no jobs (or only the ones you intended).
- Document the change in
P4-cortex/growth/patterns/shell-init-side-effect-gating.md.
Anti-patterns
- ❌ Adding
&"for performance" without checking the consumer's gate - ❌ Slapping
&!on every&to silence notifications - ❌ Treating
[N] PIDas "noise to silence" — it's a symptom pointing at a real issue - ❌ Moving the side effect to a wrapper without checking that the wrapper actually gates the consumer
Pitfalls
- Marker timing: marker files are often created by wrappers AFTER .zshrc source. So you can't gate bg-init by
[[ -f $marker ]]at source time — marker doesn't exist yet. Fix: move side effect to the wrapper itself.
- Subshell evaluation:
eval "$(brew shellenv)"and similarevalof generated shell code can hide&if upstream changes. Re-check afterbrew upgrade.
- System /etc files: macOS
/etc/zprofile(path_helper) and/etc/zshrc(sources/etc/zshrc_$TERM_PROGRAM) should be checked, not just user files.
- Multiple `&` mystery: if
[N] PIDshows N=3 but only one&in user files, the others come from system /etc files, login hooks, or subshell evals. Audit those too.
PYTHONPATH Trailing Colon
A closely related class of shell-init side effect: PYTHONPATH entries with a trailing separator leak the CWD into sys.path, shadowing modules. See references/pypath-trailing-colon.md.
Detection
Fix
Subprocess Protection
When spawning Hermes CLI from cron/background runners, explicitly set PYTHONPATH in the child process env to prevent inherited PYTHONPATH leaks:
Reference
See P4-cortex/growth/patterns/shell-init-side-effect-gating.md for:
- Full case study (2026-06-03 .zshrc_aliases leak)
- Generalization beyond shell init
- Verification recipe
Linked References
references/pypath-trailing-colon.md— PYTHONPATH trailing colon pitfall with full diagnostics, fix pattern, and provenance.
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/software-development/shell-init-side-effect-gating/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/humanerd-drew/opencode-drewgent/shell-init-side-effect-gating)