[BUG] FreeBSD not supported - bash commands hang indefinitely (v2.0.29)

[ramanujsingh]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Claude Code v2.0.29 is completely unusable on FreeBSD 11.4 because all bash commands hang indefinitely. The root cause is that FreeBSD platform binaries are missing from the bundled distribution.

What Should Happen?

Expected Behavior

Bash commands should execute and return output, similar to how they work on macOS, Linux, and Windows.

Actual Behavior

• All bash commands hang indefinitely
• No child processes are spawned (verified with ps -axj)
• Claude Code becomes completely unusable
• User must kill the hung commands manually

Error Messages/Logs

### Root Cause Analysis

I performed extensive investigation and found that:

1. **Missing Platform Binaries:**
   
   ls /home/build/.nvm/versions/node/v20.19.5/lib/node_modules/@anthropic-ai/claude-code/vendor/ripgrep/
   

   **Present:**
   - arm64-darwin/ (macOS ARM)
   - arm64-linux/ (Linux ARM)
   - x64-darwin/ (macOS Intel)
   - x64-linux/ (Linux x86-64)
   - x64-win32/ (Windows)

   **Missing:**
   - x64-freebsd/ (FreeBSD) ❌

2. **Debug Log Evidence:**
   From `/home/build/.claude/debug/latest`:
   
   [ERROR] Error: spawn .../vendor/ripgrep/x64-freebsd/rg ENOENT
   
   Claude Code tries to use `x64-freebsd/rg` but the file doesn't exist.

3. **Bundled Architecture:**
   - Claude Code uses a single 1.1MB bundled `cli.js` file
   - Searched entire file: ZERO references to `node-pty`, `freebsd`, or PTY-related code
   - Platform support is hardcoded at build time, not runtime

### Proof That FreeBSD Can Work

To prove this is a build issue and not a platform limitation, I tested node-pty compilation on FreeBSD:


cd /home/build/.nvm/versions/node/v20.19.5/lib/node_modules/@anthropic-ai/claude-code
npm install node-pty
node -e "const pty = require('node-pty'); console.log('node-pty loaded'); const shell = pty.spawn('/bin/echo', ['test']); shell.on('data', d => console.log('Output:', d));"


**Result:**

node-pty loaded
Output: test


This proves:
- FreeBSD 11.4 CAN compile and run node-pty successfully
- Node v20.19.5 works fine with PTY on FreeBSD
- The issue is purely with Claude Code's build process, not platform compatibility

### Comparison with Gemini CLI (Working)

Google's Gemini CLI v0.11.0 works perfectly on the same FreeBSD system because:

1. **Dynamic Loading:** Uses unbundled JavaScript files that import modules at runtime
2. **Native Compilation:** npm compiles node-pty during installation for the current platform
3. **No Pre-built Binaries Required:** Relies on npm's native module compilation

Evidence:

gemini  # Works perfectly on FreeBSD
ls /home/build/.nvm/versions/node/v20.19.5/lib/node_modules/@google/gemini-cli/node_modules/node-pty/build/Release/pty.node
# File exists - compiled during npm install


### Failed Workaround Attempts

1. ✗ **Shell configuration fixes** - Commented out problematic .bashrc/.profile lines (no effect)
2. ✗ **Installing node-pty locally** - Compiled successfully but Claude Code bundle doesn't load it
3. ✗ **Node version incompatibility theory** - Disproven by Gemini CLI working with Node v20

### Impact

Claude Code is **completely unusable** on FreeBSD systems. This affects:
- FreeBSD desktop users
- Developers using FreeBSD for development/testing
- Organizations running FreeBSD infrastructure

### Suggested Fix

**Option 1: Add FreeBSD to Build Process (Recommended)**

1. Add x64-freebsd to supported platforms in build configuration
2. Include FreeBSD binaries in vendor/ripgrep/x64-freebsd/
3. Add platform detection for FreeBSD in bundling logic
4. Test on FreeBSD 11.4+ and 13.x


**Option 2: Change to Dynamic Loading Architecture**

1. Move from single bundled file to modular structure (like Gemini CLI)
2. Allow npm to compile native modules during installation
3. Benefits: Automatic support for any platform Node.js supports
4. Future-proof: New platforms work without code changes


### Additional Information

**Process Monitoring:**

# When running Claude Code with hung bash command:
ps -axj | awk '$3 == <claude-pid>'
# Result: Zero child processes (bash never spawned)


**Debug Command:**

DEBUG=* NODE_DEBUG=* claude --dangerously-skip-permissions 2>&1 | tee /tmp/claude_debug.log


Shows shell snapshot creation succeeds but actual bash execution never starts.

### Related Files

I've created a comprehensive technical analysis document available at:
`/tmp/claude_code_freebsd_analysis.md` (on my local system)

If needed, I can provide:
- Full debug logs
- System call traces (truss output)
- Detailed architecture comparison between Claude Code and Gemini CLI
- Complete reproduction steps

### Request

Please add FreeBSD to the list of supported platforms in the Claude Code build process. FreeBSD is a widely-used operating system in development and server environments, and node-pty has proven compatibility with it.

---

### Labels to Add (if available)

- `bug` - This is a bug preventing core functionality
- `platform-support` - Platform-specific issue
- `enhancement` - Could also be considered a feature request for FreeBSD support
- `help wanted` - If community contributions are welcome

---

### Priority

**High** - Core functionality (bash execution) is completely broken on an entire OS platform.

Steps to Reproduce

1. Install Claude Code on FreeBSD 11.4:

   npm install -g @anthropic-ai/claude-code

2. Launch Claude Code:

   claude --dangerously-skip-permissions

3. Try to run any bash command (e.g., ls, pwd, date)

4. Observe that the command hangs indefinitely with no output

Claude Model

Sonnet (default)

Is this a regression?

Yes, this worked in a previous version

Last Working Version

worked with node v18

Claude Code Version

v2.0.29

Platform

Anthropic API

Operating System

Other

Terminal/Shell

Other

Additional Information

• Operating System: FreeBSD 11.4-RELEASE
• Node.js Version: v20.19.5 (installed via NVM)
• Claude Code Version: 2.0.29
• Installation Method: npm install -g @anthropic-ai/claude-code

After investing hours to fix this issue, claude code told to file bug with you. Below is the content provided by claude code to file this issue:

---

Title

FreeBSD not supported - bash commands hang indefinitely (v2.0.29)

---

Issue Description

Summary

Claude Code v2.0.29 is completely unusable on FreeBSD 11.4 because all bash commands hang indefinitely. The root cause is that FreeBSD platform binaries are missing from the bundled distribution.

Environment

• Operating System: FreeBSD 11.4-RELEASE
• Node.js Version: v20.19.5 (installed via NVM)
• Claude Code Version: 2.0.29
• Installation Method: npm install -g @anthropic-ai/claude-code

Steps to Reproduce

1. Install Claude Code on FreeBSD 11.4:

   npm install -g @anthropic-ai/claude-code

2. Launch Claude Code:

   claude --dangerously-skip-permissions

3. Try to run any bash command (e.g., ls, pwd, date)

4. Observe that the command hangs indefinitely with no output

Expected Behavior

Bash commands should execute and return output, similar to how they work on macOS, Linux, and Windows.

Actual Behavior

• All bash commands hang indefinitely
• No child processes are spawned (verified with ps -axj)
• Claude Code becomes completely unusable
• User must kill the hung commands manually

Root Cause Analysis

I performed extensive investigation and found that:

1. Missing Platform Binaries:

   ls /home/build/.nvm/versions/node/v20.19.5/lib/node_modules/@anthropic-ai/claude-code/vendor/ripgrep/

   Present:

   • arm64-darwin/ (macOS ARM)
   • arm64-linux/ (Linux ARM)
   • x64-darwin/ (macOS Intel)
   • x64-linux/ (Linux x86-64)
   • x64-win32/ (Windows)

   Missing:

   • x64-freebsd/ (FreeBSD) ❌

2. Debug Log Evidence:
   From /home/build/.claude/debug/latest:

   [ERROR] Error: spawn .../vendor/ripgrep/x64-freebsd/rg ENOENT
   

   Claude Code tries to use x64-freebsd/rg but the file doesn't exist.

3. Bundled Architecture:

   • Claude Code uses a single 1.1MB bundled cli.js file
   • Searched entire file: ZERO references to node-pty, freebsd, or PTY-related code
   • Platform support is hardcoded at build time, not runtime

Proof That FreeBSD Can Work

To prove this is a build issue and not a platform limitation, I tested node-pty compilation on FreeBSD:

cd /home/build/.nvm/versions/node/v20.19.5/lib/node_modules/@anthropic-ai/claude-code
npm install node-pty
node -e "const pty = require('node-pty'); console.log('node-pty loaded'); const shell = pty.spawn('/bin/echo', ['test']); shell.on('data', d => console.log('Output:', d));"

Result:

node-pty loaded
Output: test

This proves:

• FreeBSD 11.4 CAN compile and run node-pty successfully
• Node v20.19.5 works fine with PTY on FreeBSD
• The issue is purely with Claude Code's build process, not platform compatibility

Comparison with Gemini CLI (Working)

Google's Gemini CLI v0.11.0 works perfectly on the same FreeBSD system because:

1. Dynamic Loading: Uses unbundled JavaScript files that import modules at runtime
2. Native Compilation: npm compiles node-pty during installation for the current platform
3. No Pre-built Binaries Required: Relies on npm's native module compilation

Evidence:

gemini  # Works perfectly on FreeBSD
ls /home/build/.nvm/versions/node/v20.19.5/lib/node_modules/@google/gemini-cli/node_modules/node-pty/build/Release/pty.node
# File exists - compiled during npm install

Failed Workaround Attempts

1. ✗ Shell configuration fixes - Commented out problematic .bashrc/.profile lines (no effect)
2. ✗ Installing node-pty locally - Compiled successfully but Claude Code bundle doesn't load it
3. ✗ Node version incompatibility theory - Disproven by Gemini CLI working with Node v20

Impact

Claude Code is completely unusable on FreeBSD systems. This affects:

• FreeBSD desktop users
• Developers using FreeBSD for development/testing
• Organizations running FreeBSD infrastructure

Suggested Fix

Option 1: Add FreeBSD to Build Process (Recommended)

1. Add x64-freebsd to supported platforms in build configuration
2. Include FreeBSD binaries in vendor/ripgrep/x64-freebsd/
3. Add platform detection for FreeBSD in bundling logic
4. Test on FreeBSD 11.4+ and 13.x

Option 2: Change to Dynamic Loading Architecture

1. Move from single bundled file to modular structure (like Gemini CLI)
2. Allow npm to compile native modules during installation
3. Benefits: Automatic support for any platform Node.js supports
4. Future-proof: New platforms work without code changes

Additional Information

Process Monitoring:

# When running Claude Code with hung bash command:
ps -axj | awk '$3 == <claude-pid>'
# Result: Zero child processes (bash never spawned)

Debug Command:

DEBUG=* NODE_DEBUG=* claude --dangerously-skip-permissions 2>&1 | tee /tmp/claude_debug.log

Shows shell snapshot creation succeeds but actual bash execution never starts.

Related Files

I've created a comprehensive technical analysis document available at:
/tmp/claude_code_freebsd_analysis.md (on my local system)

If needed, I can provide:

• Full debug logs
• System call traces (truss output)
• Detailed architecture comparison between Claude Code and Gemini CLI
• Complete reproduction steps

Request

Please add FreeBSD to the list of supported platforms in the Claude Code build process. FreeBSD is a widely-used operating system in development and server environments, and node-pty has proven compatibility with it.

---

Labels to Add (if available)

• bug - This is a bug preventing core functionality
• platform-support - Platform-specific issue
• enhancement - Could also be considered a feature request for FreeBSD support
• help wanted - If community contributions are welcome

---

Priority

High - Core functionality (bash execution) is completely broken on an entire OS platform.

[ramanujsingh]

Update: Node 18 also affected - All bash commands hang

I need to correct my initial report. After further testing, I can confirm that bash commands hang indefinitely with Node.js v18 on FreeBSD 11.4 and Claude Code v2.0.30

Test Environment:

• OS: FreeBSD 11.4-RELEASE
• Node.js: v18 (exact version unable to determine due to hanging)
• Claude Code: Using Bash tool with timeout parameter

Evidence - Multiple command types all hang:

1. date - Simple date command with 5-second timeout → Hangs indefinitely
2. node --version - Version check with 5-second timeout → Hangs indefinitely
3. uname -a - System info with 5-second timeout → Hangs indefinitely
4. which bash - Path lookup with 5-second timeout → Hangs indefinitely
5. echo "test" - Basic shell built-in with 5-second timeout → Hangs indefinitely

Observations:

• All commands start but never produce output or exit
• Commands remain in "running" status until manually killed
• Timeout parameter is completely ignored
• No child processes appear to be spawned
• Even the simplest commands (echo, date) that should execute instantly hang

Conclusion:
This is not a Node v20 regression as I initially thought. The bash command hanging is a fundamental FreeBSD compatibility issue that exists
across Node.js versions (both v18 and v20).

The root cause remains: missing FreeBSD platform support in the bundled binaries, particularly the absence of x64-freebsd variants for
vendored tools.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[support-samarapix]

Yes, issue still present.

[github-actions]

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.