Add configurable delay for tmux send-keys when spawning team agents
Problem
When spawning team agents in tmux panes, Claude Code creates the pane and immediately sends the claude command via tmux send-keys. If the user's shell initialization (.zshrc) takes longer than the time between pane creation and send-keys, the command gets swallowed or partially interpreted.
This is a race condition: the shell isn't ready to accept input when the command arrives.
Root Cause
Heavy .zshrc setups (oh-my-zsh, nvm, mise, pyenv, starship, direnv, etc.) can take 1-2+ seconds to initialize. The send-keys fires before this completes.
Observed Behavior
- Tmux pane is created successfully
- Agent's Claude session does not start
- Pane shows a bare shell prompt
- User must manually run the
claude --agent-id ...command in the pane
Proposed Solution
Add a configurable delay (in milliseconds) before send-keys is issued to a new tmux pane. Something like:
// .claude/settings.json or .claude/settings.local.json
{
"team": {
"tmuxSendKeysDelayMs": 5000
}
}
A default of 2-3 seconds would cover most shell setups. Power users could tune it down; heavy shell configs could increase it.
Alternative Approaches
- Poll for shell readiness: Instead of a fixed delay, poll the pane for a prompt character (e.g.,
$,>,%) before sending the command - Environment variable signal: Have the spawner wait for a specific env var or file to appear, and users add a signal at the end of their shell rc (more robust but requires user setup)
Environment
- macOS (Darwin 25.3.0)
- Shell: zsh with oh-my-zsh
- Shell init time: ~1.5 seconds
- Claude Code 2.1.74
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗