Team agents fail to start: tmux send-keys race condition with shell initialization

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/23465
2. https://github.com/anthropics/claude-code/issues/23456
3. https://github.com/anthropics/claude-code/issues/23415

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

This is exactly the issue I have, I don't understand why it uses send-keys instead of just a command

I also see this issue, I suspect that zsh users with oh-my-zsh or other plugins that take half a second or a second to initialize are receiving the command before the shell has initialized.

I experiment the same issue with bash. Maybe a big .bashrc (that's the explanation of Claude Code itself)

great diagnosis!
i have the same condition, i had to switch to just using agents without the tmux panes.
I tried trimming back on zsh stuff but still doesn't start.

there's no way to 'up-arrow' and run the command either.

guess there's no easy way to modify those commands to run in a vanilla shell?

Same condition, using zsh. Apparently using starship makes the shell initialization slow enough (like maybe 1s latency in init) that this issue manifests. When telling about this issue to the main context, it applies wait times and then it works properly with invoking the agent teams in tmux panels. This clearly seems to be a timing issue.

to add insult to injury... claude will keep asking me to install tmux or the iterm extensions
sometimes they will run as background tasks but often it will keep prompting.

I'm using

claude --teammate-mode in-process

and added this to both local and ~/.claude/settings.json

{
  "teammateMode": "in-process"
}

any other workarounds to force parallel but background?

https://code.claude.com/docs/en/agent-teams.md

Hey! I ran into a similar pattern in our bug knowledge base and thought this might help.

What's happening: Race condition between tmux send-keys and shell initialization - the command is sent before zsh/bash has finished loading .zshrc/.bashrc and plugins, causing the command to be lost

What worked for us:

Add a delay or shell readiness check before sending keys, or use tmux's command execution parameter instead of send-keys

Steps:

1. Option 1: Add a configurable delay (1-3 seconds) between tmux split-window and send-keys
2. Option 2: Replace send-keys approach with tmux split-window -c 'command' to execute directly
3. Option 3: Send a shell readiness probe before the actual command
4. Option 4: Use tmux new-session or new-window with command parameter instead of send-keys
5. Add environment variable TMUX_DELAY_MS for users with slow shell initialization

// Replace this pattern:
// tmux split-window
// tmux send-keys 'command' Enter

// With this:
const delay = process.env.TMUX_DELAY_MS || 2000;
await new Promise(resolve => setTimeout(resolve, delay));
// OR better:
tmux split-window 'command'
// OR:
tmux split-window -c 'bash -c "command"'

Hope this helps! Let me know if it doesn't match your case — happy to dig deeper. 🦞

_Disclosure: This analysis is from Confucius Debug, an AI-powered community KB for agent bugs. Please verify before applying._

---
_{🦞 Confucius Debug — community knowledge base for AI agent bugs. Free to search via MCP.}

@sstklen where would those changes be added?

it looks like typescript, not any env settings. are you suggesting modifying the claude code .. code?
or is this an additional post-hook we can run after a pane is triggered to open?

or is this a bot generated comment?

Fair question, @dcsan — I should have been clearer. Those TypeScript snippets describe what the fix would look like inside Claude Code's source. They're not something you can patch yourself since the tmux spawning logic is in the compiled binary.

For practical workarounds right now:

• --teammate-mode in-process — you mentioned you're already using this, which bypasses tmux entirely. This is the most reliable option.
• Trim shell init — if you do want tmux mode, stripping heavy plugins (oh-my-zsh, starship, etc.) from your .zshrc can help the shell initialize before send-keys fires.
• Lightweight .zshrc guard — add [[ -n "$TMUX" ]] && return early in .zshrc to skip heavy init when spawned inside tmux panes.

The real fix needs to come from Anthropic's side (using tmux split-window 'command' instead of send-keys). Apologies for the confusion in my earlier comment.

yes i did some claudigging today

Use a faster shell for tmux panes

this was the fix that finally worked for me:
in ~/.tmux.conf:

  set-option -g default-shell /bin/zsh
  # But for new panes, use a fast shell:
  set-option -g default-command "bash --norc --noprofile"

set other shell

i found this got processes killed

  # Before running claude, override the default shell tmux uses
  export SHELL=/bin/bash
  claude

zsh quick exit

add this to the top of your .zshrc
but actually cc runs with a different env vars and ... had issues

# Skip heavy init for tmux-spawned Claude agent panes
if [[ -n "$CLAUDE_AGENT" || -n "$CLAUDE_CODE_AGENT" ]]; then
  # minimal PATH setup only
  # echo "claude startup"
  return
fi

Option 3: tmux hook to add a delay

(This is heavy-handed and may affect other tmux usage.)

Add to ~/.tmux.conf:

  # Add slight delay after pane creation before accepting input
  set-hook -g after-split-window "run-shell 'sleep 0.3'"

This forces a 300ms pause after every split-window, giving the shell time to init before send-keys arrives.

Wait for the official fix

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.