Add configurable delay for tmux send-keys when spawning team agents

Resolved 💬 3 comments Opened Mar 13, 2026 by cds-amal Closed Mar 17, 2026

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

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗