Agent teams install incompatible binary on NixOS, breaking Claude Code until manual cleanup

[otavio]

Description

When using Claude Code's agent teams feature on NixOS, the teammate spawning mechanism
downloads and installs a standard (unpatched) Linux binary into ~/.local/bin/ and
~/.local/share/. This binary is incompatible with NixOS because NixOS does not follow
the Filesystem Hierarchy Standard (FHS) — there is no /lib64/ld-linux-x86-64.so.2
dynamic linker, and system libraries are not at standard paths.

The teammate process fails to start. Worse, the incompatible binary in ~/.local/bin/
can shadow the working Nix-managed binary in PATH, preventing Claude Code itself from
starting until the user manually removes the files from ~/.local/.

Environment

• OS: NixOS
• Claude Code version: 2.1.39
• Installation method: Nix flake using ryoppippi/claude-code-overlay, which patches the binary with autoPatchelfHook
• Feature flag: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Steps to reproduce

1. Install Claude Code on NixOS using the Nix overlay (patches the ELF binary for NixOS)
2. Enable agent teams: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
3. Use TeamCreate or Task tool to spawn a teammate
4. Teammate fails — an unpatched binary is installed to ~/.local/bin/ and ~/.local/share/
5. Claude Code itself may fail to start afterward (the unpatched ~/.local/bin/claude shadows the Nix-managed one)

Expected behavior

Teammate processes should reuse the same Claude Code binary that the lead process is
running. No additional binary should be downloaded or installed into the user's home
directory.

Actual behavior

The teammate spawning mechanism downloads a standard Linux binary to ~/.local/bin/
and ~/.local/share/. On NixOS this binary cannot execute (missing dynamic linker).
The only recovery is to manually rm the files from ~/.local/.

Workaround

After the failure, manually remove the incompatible files:

rm -rf ~/.local/bin/claude ~/.local/share/claude*

Then Claude Code starts normally again using the Nix-managed binary.

Analysis

The Nix overlay properly handles the primary Claude Code binary:

• autoPatchelfHook patches the ELF interpreter and RPATH to use Nix store paths
• wrapProgram sets DISABLE_AUTOUPDATER=1 and DISABLE_INSTALLATION_CHECKS=1

The primary binary works correctly. The issue occurs specifically when agent teams are
used — some code path installs a fresh, unpatched binary to ~/.local/ despite
the DISABLE_* flags being set. Since Claude Code is closed source, the exact internal
mechanism that triggers this installation is not known.

Request

The teammate spawning flow should not install a new binary when a working claude is
already available in PATH. On NixOS (and other non-FHS distributions like Guix), any
binary downloaded for standard Linux will fail to execute due to missing dynamic linker
and libraries.

Ideally, the DISABLE_AUTOUPDATER and DISABLE_INSTALLATION_CHECKS flags should be
respected across all code paths, including teammate spawning — or an override mechanism
(e.g., an environment variable like CLAUDE_CODE_BINARY) should be provided so
package managers can control which binary is used.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] Claude's code has been switched from npm to a native installer, but it no longer runs on NixOS. #23846
2. Installation just hangs forever on nixos #24258
3. [BUG] [SECURITY] Claude binary distribution auto-installs itself to ~/.local without asking for user permission #21619

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

[otavio]

This is not duplicated because this was not happening before I enabled the teammates' support. So it might change behavior when we enable the experimental feature.