Fix Claude Code Agent Bash Shell Hang

Claude Code agents spawn bash shells that source your .bashrc. If your shell config contains completion scripts, slow init commands, or hanging processes, every agent spawn becomes a cascading hang.

The Problem

Common culprits that hang in non-interactive agent shells:

• source <(ng completion script) — Angular CLI
• source <(kubectl completion bash) — Kubernetes
• eval "$(nvm.sh)" — Node Version Manager (slow init)
• eval "$(conda activate base)" — Conda environments
• eval "$(pyenv init -)" — Python version manager
• eval "$(rbenv init -)" — Ruby version manager

The Fix: Non-Interactive Guard

Add this as the first line of your .bashrc:

# Exit early for non-interactive shells (agents, scripts, cron)
case $- in
    *i*) ;;
      *) return;;
esac

Everything below this guard only runs in interactive shells. Agent-spawned shells skip all completion scripts, prompt customization, and slow init commands.

Detect Automatically: SessionStart Hook

A SessionStart hook can scan your .bashrc at the start of every session and warn if dangerous patterns exist without a guard:

#!/bin/bash
# bashrc-safety-check.sh — TRIGGER: SessionStart

BASHRC="$HOME/.bashrc"
[ ! -f "$BASHRC" ] && exit 0

# Already guarded?
if head -10 "$BASHRC" | grep -qE 'case \$- in|\[\[ \$- ==.*i'; then
    exit 0
fi

# Check for dangerous patterns
for pattern in 'source.*<.*completion' 'nvm\.sh' 'conda.*activate' 'pyenv.*init'; do
    if grep -q "$pattern" "$BASHRC" 2>/dev/null; then
        echo "⚠ .bashrc contains $pattern without non-interactive guard" >&2
        echo "Add: case \$- in *i*) ;; *) return;; esac" >&2
    fi
done
exit 0

npx cc-safe-setup

cc-safe-setup — Make Claude Code safe for autonomous operation