Detailed Analysis
A macOS user reports a configuration issue with Claude's experimental agent teams feature, specifically that the expected tmux split-pane interface fails to render despite following what appears to be a reasonable setup procedure. The user has enabled the feature via the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag in their `settings.json`, launched a tmux session manually, and invoked Claude with the `--teammate-mode tmux` flag. However, the split panes that should visually represent individual agents running in parallel do not appear, even though multiple agents are visible within the primary chat interface. The disconnect between agent activity being registered in the chat and the absence of corresponding pane-level visualization suggests the issue lies in how Claude's tooling is initiating or attaching to the tmux session.
The most likely source of the problem is a session attachment conflict. By running `tmux new-session -s agents` before invoking Claude, the user is creating and immediately attaching to a tmux session from within their terminal. When Claude then attempts to spawn subpanes or create new windows under the `--teammate-mode tmux` flag, it may be launching a separate session or targeting an environment that is not properly nested or referenced. Claude's agent team tooling likely expects to be the process that initializes and controls the tmux session structure, rather than being invoked inside an already-attached session the user created manually. The correct workflow may require either letting Claude create the session autonomously or launching Claude in a way that passes control of the session hierarchy to the tool itself.
This issue is emblematic of the early-stage friction that accompanies experimental features in rapidly evolving AI developer tooling. The `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag signals that this capability is not yet part of Claude Code's stable, documented feature set — meaning documentation is sparse, edge cases around terminal multiplexers and session management are not yet ironed out, and user-facing error messaging may be insufficient to diagnose failures. macOS-specific behavior around terminal emulators, shell environment inheritance, and tmux session scoping can further complicate what appears to be a straightforward invocation.
Broadly, the desire for split-pane visual interfaces for multi-agent workflows reflects a meaningful shift in how developers are beginning to conceptualize AI-assisted programming. Rather than interacting with a single AI instance sequentially, users are increasingly expecting to orchestrate parallel agent threads — each handling discrete subtasks — with real-time observability across those threads. Anthropic's exploration of tmux as a rendering substrate for this experience is pragmatic: tmux is already a standard tool in developer environments, requires no new UI infrastructure, and maps naturally onto the mental model of concurrent processes. The challenge, as this report illustrates, is that exposing multi-agent orchestration through a terminal multiplexer requires precise control over session lifecycle that is difficult to achieve gracefully when users bring their own session configurations to the table. Resolving this class of issue will be important as Anthropic moves the feature toward general availability.
Read original article →