Agent Teams: teammate spawn fails after brew upgrade due to hardcoded Caskroom version path

Status Fixed / completed

Maintainer reply ✓ Yes — bogini

Activity 5 comments · opened Apr 16, 2026 · closed May 14, 2026

💡 Likely answer: A maintainer (bogini, collaborator) responded on this thread — see the highlighted reply below.

Description

When Claude Code is installed via Homebrew (brew install claude-code), Agent Teams appears to resolve and hardcode the absolute Caskroom path at spawn time:

/opt/homebrew/Caskroom/claude-code/<VERSION>/claude

After brew upgrade claude-code, the old version directory is removed, causing teammate spawn to fail because the hardcoded path no longer exists.

Steps to Reproduce

Install Claude Code via Homebrew
Start a session and create an Agent Teams team (TeamCreate)
Spawn a teammate (e.g., Agent with team_name)
If brew upgrade claude-code has changed the version since the binary path was resolved, the teammate fails to start

Expected Behavior

Agent Teams should use the stable symlink path (/opt/homebrew/bin/claude) or re-resolve the binary path at spawn time, rather than caching or hardcoding the resolved Caskroom path.

Actual Behavior

Teammate spawn fails (the child process cannot be started because the resolved path points to a removed version directory).

Workaround

Restart Claude Code after brew upgrade.

Environment

macOS (Apple Silicon)
Claude Code installed via Homebrew Cask
Symlink chain: /opt/homebrew/bin/claude → /opt/homebrew/Caskroom/claude-code/<VERSION>/claude

View original on GitHub ↗

5 Comments

github-actions[bot] · 6 months ago

Found 3 possible duplicate issues:

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

hisashi-chiba-ab · 6 months ago

Root Cause Analysis

Investigated the binary internals. The teammate spawn mechanism works as follows:

Binary structure

Claude Code is a single Rust/Mach-O binary (~190MB) embedding Bun/Node.js runtime.

Spawn path resolution

The internal child_process.fork() determines the executable path via:

options.execPath = options.execPath || process.execPath;
// ...
return spawn(options.execPath, args, options);

process.execPath returns the resolved (symlink-followed) path:

/opt/homebrew/Caskroom/claude-code/2.1.92/claude

not the stable symlink:

/opt/homebrew/bin/claude

Teammate spawn flow

Main process (PID)
  → process.execPath = /opt/homebrew/Caskroom/claude-code/2.1.92/claude
  → tmux send-keys "claude --resume <session-id>" (likely using resolved path)
  → New pane attempts to execute the versioned path

Why brew upgrade breaks it

brew upgrade claude-code installs new version (e.g., 2.1.93)
Old Caskroom directory (2.1.92/) is removed
Symlink updated: /opt/homebrew/bin/claude → .../2.1.93/claude
Running main process still holds process.execPath = .../2.1.92/claude
New teammate spawn fails — target binary no longer exists

Proposed fix

For tmux-based teammate spawning, use PATH lookup (claude) instead of process.execPath, or re-resolve the symlink at spawn time. This would make teammate spawning resilient to in-place upgrades.

bogini collaborator · 5 months ago

Confirmed and fixed — same root cause as #58560. The daemon now detects when its own binary has been deleted/replaced (e.g. brew upgrade) and exits cleanly so the next invocation uses the new version, instead of crash-looping on the deleted path.

Ships in v2.1.142.

claude[bot] contributor · 5 months ago

This issue was fixed as of version 2.1.142.

github-actions[bot] · 3 months ago

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.