CLI binary not accessible in terminal - missing bin field in package.json

[bzeeman]

Bug Report: Claude CLI Binary Not Accessible in Terminal

Report Date: 2025-11-19 Extension: Claude Code v2.0.45 Platform: code-server (VS Code Server) Issue Tracker: https://github.com/anthropics/claude-code/issues

---

Summary

The Claude Code extension bundles a claude CLI binary but does not make it accessible in the integrated terminal. Users cannot run claude commands despite the binary being present in the extension directory.

Environment

Tested on two independent systems:

1. doctorwho.local: Debian 13, code-server, user: codeserver
2. homeassistant.local: Home Assistant OS, Studio Code Server add-on v6.0.0

Extension Details:

• Name: anthropic.claude-code
• Version: 2.0.45 (linux-x64)
• Installation: Both via VS Code extension marketplace
• Installed: 2025-11-18

Expected Behavior

Based on the extension README which states:

"Unleash Claude's raw power directly in your terminal"

Expected: The claude CLI command should be accessible in the integrated terminal after extension installation.

Actual Behavior

1. Extension installs successfully
2. ~/.claude/ directory is created with credentials
3. Binary exists at: ~/.local/share/code-server/extensions/anthropic.claude-code-2.0.45-linux-x64/resources/native-binary/claude
4. But: Running claude in terminal returns: command not found
5. But: Running which claude returns nothing

Reproduction Steps

1. Install Claude Code extension in VS Code/code-server
2. Complete authentication/setup
3. Open integrated terminal
4. Run: claude --version
5. Result: bash: claude: command not found

Root Cause Analysis

Investigation findings:

1. No bin field in package.json

"scripts": {},
"dependencies": {},

Expected (for CLI tools):

"bin": {
  "claude": "./resources/native-binary/claude"
}

2. No installation hooks

• No postinstall scripts
• No setup scripts (.sh files)
• Empty scripts section in package.json

3. No PATH configuration

• Extension doesn't modify user PATH
• No symlinks created
• No VS Code terminal integration setup

4. No documentation

• README mentions "terminal" but provides no setup instructions
• No mention of manual PATH configuration required
• No command palette action to "Add Claude to PATH"

Impact

Severity: Medium-High

Affected users:

• Anyone using code-server (common for remote development)
• Users expecting advertised "terminal" functionality
• Multi-system setups where manual configuration is tedious

Workaround exists (but shouldn't be necessary):

# Manual fix required on each system
mkdir -p ~/bin
ln -sf ~/.local/share/code-server/extensions/anthropic.claude-code-*/resources/native-binary/claude ~/bin/claude
echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Proposed Solutions

Option 1: Add bin field to package.json (Recommended)

{
  "bin": {
    "claude": "./resources/native-binary/claude"
  }
}

This is standard practice for npm packages that provide CLI tools.

Option 2: Add postinstall script

Create scripts/postinstall.sh that:

• Creates symlink in appropriate location
• Adds to PATH in shell rc files
• Handles multiple shells (bash, zsh, fish)

Option 3: VS Code Command Palette action

Add command: Claude Code: Add CLI to PATH

• Guides user through setup
• Creates symlinks
• Updates shell configuration

Option 4: Document manual setup

At minimum, update README with:

## CLI Setup

To use the `claude` command in your terminal:

1. Add to your PATH:
   ```bash
   echo 'export PATH="$HOME/.local/share/code-server/extensions/anthropic.claude-code-2.0.45-linux-x64/resources/native-binary:$PATH"' >> ~/.bashrc
   source ~/.bashrc

2. Verify: claude --version

## Additional Context

**Why this matters:**
- Extension advertises terminal/CLI functionality
- README specifically mentions "terminal" multiple times
- Binary is bundled (215MB extension size includes it)
- `.claude/` directory suggests CLI usage is intended
- Other VS Code extensions with CLIs handle this properly (e.g., `gh`, `az`, `gcloud`)

**Systems affected:**
- ✅ Confirmed on code-server (Debian 13)
- ✅ Confirmed on Home Assistant Studio Code Server
- ⚠️ Likely affects all VS Code Server / remote development scenarios

## Evidence

**Binary exists:**
```bash
$ find ~/.local/share/code-server/extensions -name claude -type f
/home/codeserver/.local/share/code-server/extensions/anthropic.claude-code-2.0.45-linux-x64/resources/native-binary/claude

$ ~/.local/share/code-server/extensions/anthropic.claude-code-2.0.45-linux-x64/resources/native-binary/claude --version
2.0.45 (Claude Code)

But not in PATH:

$ which claude
# (no output)

$ claude --version
bash: claude: command not found

package.json lacks CLI registration:

"scripts": {},
"dependencies": {},
// No "bin" field present

---

Recommendation

Priority: This should be fixed in the next release.

Preferred fix: Add bin field to package.json (Option 1) - this is the standard, automated solution.

Short-term: Document the manual workaround in README.

---

Reporter Information

• GitHub: (your GitHub username)
• Email: (your email if you want updates)
• Systems tested: 2 independent installations
• Willing to test fixes: Yes

---

Thank you for your attention to this issue!