Agent Teams tmux backend: race condition on pane spawn causes silent agent failure
Bug description
When using Agent Teams with the tmux backend, spawned agents consistently fail to start. The tmux send-keys command that launches the claude process is sent to the new pane before the shell has finished initializing (loading .bashrc/.profile). The claude binary starts in a half-initialized environment, exits silently, and the pane is left at a bare shell prompt.
This happens 100% of the time on my system. Every agent must be manually relaunched after the initial spawn fails.
Steps to reproduce
- Have a
.bashrcthat takes more than ~0.5s to load (common with tools like nvm, direnv, conda, starship, etc.) - Create an agent team:
TeamCreate - Spawn a teammate using the
Tasktool withteam_nameparameter - Observe the tmux pane: the
claudecommand appears,.bashrcfinishes loading after the command was sent, and the pane shows a bare shell prompt with no running agent
Expected behavior
The agent should start reliably in the new tmux pane. The spawn logic should wait for the shell to be fully initialized before sending the claude command.
Actual behavior
The claude command is sent via tmux send-keys immediately after tmux split-window, before .bashrc completes. Evidence from tmux capture-pane:
cd /path && CLAUDECODE=1 ... /path/to/claude --agent-id name@team ...
Fine ~/.bashrc ← bashrc finishes AFTER the command was sent
sandro@bluffx:~/project$ ← bare prompt, claude exited silently
The command is even sent twice (the system retries?), but both attempts fail for the same reason.
Suggested fix
Add a shell-readiness check between tmux split-window and tmux send-keys. For example:
# After creating the pane, poll until the shell prompt is ready
pane_id=$(tmux split-window -d -P -F '#{pane_id}' ...)
while ! tmux capture-pane -t "$pane_id" -p | grep -qE '[\$#>] *$'; do
sleep 0.5
done
# Now it's safe to send the command
tmux send-keys -t "$pane_id" "$claude_command" Enter
Workaround
I wrote a shell script that bypasses the Task tool for spawning: it creates tmux panes manually, waits ~8 seconds for shells to initialize, registers agents in the team config JSON, and then sends the claude commands. This works 100% of the time.
Environment
- Claude Code: v2.1.39
- OS: Ubuntu Linux 6.14.0-37-generic
- Shell: bash with moderately heavy
.bashrc(~2-3s init time) - tmux: installed and working
- Agent Teams:
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Impact
This bug makes Agent Teams unusable without manual intervention on every spawn. Users with any non-trivial .bashrc will hit this consistently. It affects all agent types and team sizes.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗