[BUG] Claude Code Installation Failure Report - Replit Environment

Preflight Checklist

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

What's Wrong?

Claude Code Installation Failure Report - Replit Environment

Date: 2026-01-21
Environment: Replit Workspace
Issue: New installation method breaks credential persistence
Status: Resolved via rollback to npm installation

---

Executive Summary

The new Claude Code installation method (curl -fsSL https://claude.ai/install.sh | bash) is incompatible with Replit's workspace architecture, causing credential persistence failures and requiring repeated authentication. The legacy npm installation method (npm install -g @anthropic-ai/claude-code) works correctly because it respects Replit's persistent storage conventions.

---

Root Cause Analysis

Replit's Directory Persistence Model

Replit workspaces have two distinct storage areas:

| Directory | Persistence | Purpose |
|-----------|-------------|---------|
| /home/runner/workspace/ | ✓ PERSISTENT | User project files, persists across restarts |
| /home/runner/ (except workspace) | ✗ EPHEMERAL | Runtime directories, wiped on restart |

New Installation Method Failure

The install.sh script installs Claude Code to standard Linux locations:

# Where install.sh places files:
/home/runner/.local/share/claude/versions/2.1.14/   # Binary (EPHEMERAL)
/home/runner/.local/bin/claude                       # Symlink (EPHEMERAL)
/home/runner/workspace/.claude/.credentials.json     # Credentials (PERSISTENT)

Problem: The binary and symlink are placed in /home/runner/.local/, which is wiped on every Replit workspace restart. While credentials persist, the claude command disappears, forcing reinstallation and re-authentication.

Why npm Installation Works

npm in Replit is configured with a custom global prefix pointing to the workspace:

$ npm config get prefix
/home/runner/workspace/.config/npm/node_global

This means npm installs binaries to:

# Where npm places files:
/home/runner/workspace/.config/npm/node_global/lib/node_modules/@anthropic-ai/claude-code/
/home/runner/workspace/.config/npm/node_global/bin/claude
/home/runner/workspace/.claude/.credentials.json

# All in /home/runner/workspace/ = ALL PERSISTENT ✓

PATH configuration includes npm's bin directory:

/home/runner/workspace/.config/npm/node_global/bin:/home/runner/.local/bin:...

---

Evidence

Installation Path Comparison

New Method (curl | bash):

$ which claude
/home/runner/.local/bin/claude

$ readlink -f $(which claude)
/home/runner/.local/share/claude/versions/2.1.14

# After workspace restart:
$ which claude
bash: claude: command not found  # ✗ BINARY LOST

npm Method:

$ which claude
/home/runner/workspace/.config/npm/node_global/bin/claude

$ readlink -f $(which claude)
/home/runner/workspace/.config/npm/node_global/lib/node_modules/@anthropic-ai/claude-code/cli.js

# After workspace restart:
$ which claude
/home/runner/workspace/.config/npm/node_global/bin/claude  # ✓ STILL WORKS

Credentials Persistence

Both methods store credentials in the same location:

$ ls -la ~/.claude/.credentials.json
lrwxrwxrwx 1 runner runner 30 Jan 21 04:49 /home/runner/.claude -> /home/runner/workspace/.claude

$ cat ~/.claude/.credentials.json
{"claudeAiOauth":{"accessToken":"sk-ant-oat01-...","expiresAt":1768999930411,...}}

The credentials DO persist with both methods because ~/.claude is symlinked to /home/runner/workspace/.claude/. However, without a working claude binary, credentials cannot be used.

---

User Experience Impact

Symptoms with New Install Method

1. Initial installation appears successful

• claude --version works immediately after install
• Authentication completes successfully

1. After workspace restart:

• claude: command not found
• Forced to re-run curl -fsSL https://claude.ai/install.sh | bash
• Often triggers re-authentication flow
• Credentials exist but binary is missing

1. User confusion:

• "Something changed" - system was working, now broken
• "Less user-friendly" - constant setup required
• "Secure connection isn't saving" - binary loss mimics credential loss

Working Behavior with npm Method

1. Installation:

• npm install -g @anthropic-ai/claude-code
• One-time authentication

1. After workspace restart:

• claude command still available
• Credentials still valid (until token expiry)
• No re-authentication required
• Zero maintenance required

---

Rollback Procedure

Use this procedure for any Replit app affected by the new installation method:

Step 1: Remove New Installation

# Remove ephemeral installation files
rm -rf /home/runner/.local/share/claude
rm -rf /home/runner/.local/bin/claude
rm -rf /home/runner/workspace/.local/share/claude
rm -rf /home/runner/workspace/.local/bin/claude

# Verify removal
which claude  # Should show: command not found or npm path

Step 2: Revert .profile Changes (if modified)

Check if .profile was modified:

cat ~/.profile | grep -A2 "workspace.*local.*bin"

If found, remove the workspace .local/bin PATH addition:

# Edit ~/.profile and remove these lines:
# Prioritize workspace .local/bin for Replit persistence
if [ -d "/home/runner/workspace/.local/bin" ] ; then
    PATH="/home/runner/workspace/.local/bin:$PATH"
fi

Step 3: Install Correct npm Package

IMPORTANT: Use the scoped package name, NOT the unscoped one:

# CORRECT:
npm install -g @anthropic-ai/claude-code

# INCORRECT (this is just a placeholder package):
npm install -g claude-code  # ✗ DON'T USE THIS

Step 4: Verify Installation

# Check binary location (should be in workspace)
which claude
# Expected: /home/runner/workspace/.config/npm/node_global/bin/claude

# Check version
claude --version
# Expected: 2.1.14 (Claude Code)

# Verify credentials exist
ls -la ~/.claude/.credentials.json
# Expected: file exists with recent timestamp

# Test persistence check
echo "$(which claude)" | grep -q workspace && echo "✓ Will persist" || echo "✗ Will NOT persist"
# Expected: ✓ Will persist

Step 5: Verify After Restart

After next Replit workspace restart:

# Should work without any reinstallation
claude --version

# If credentials expired, re-authenticate once:
claude
# Then use /login command

---

Technical Details

npm Configuration in Replit

Replit configures npm with workspace-persistent defaults:

$ npm config list
prefix = "/home/runner/workspace/.config/npm/node_global"

This is typically set in:

• /home/runner/.npmrc
• Or via environment variables in Replit's initialization

.claude Symlink Structure

$ ls -la /home/runner/.claude
lrwxrwxrwx 1 runner runner 30 Jan 21 04:49 /home/runner/.claude -> /home/runner/workspace/.claude

This symlink ensures both installation methods use the same credentials location in the persistent workspace directory.

Why install.sh Doesn't Detect Replit

The install script follows standard Linux conventions:

1. Uses ~/.local/bin for binaries (FHS standard)
2. Uses ~/.local/share for application data
3. Assumes ~/ is persistent storage

These assumptions are valid for:

• Traditional Linux systems
• macOS
• WSL on Windows
• Standard Docker containers

But break on Replit due to its unique two-tier storage model.

---

Recommendations

For Replit Users

1. Always use npm installation method for Claude Code in Replit
2. Document this in project README so team members don't use curl|bash
3. Add to project setup scripts:

``bash
# setup.sh
npm install -g @anthropic-ai/claude-code
``

For Claude Code Team

1. Detect Replit environment in install.sh:

``bash
if [ -n "$REPL_ID" ] || [ -n "$REPL_SLUG" ]; then
echo "Replit detected. Please use: npm install -g @anthropic-ai/claude-code"
exit 1
fi
``

1. Update documentation to include Replit-specific instructions

1. Consider Replit-aware installation:

• Check for /home/runner/workspace directory
• Install to workspace if Replit detected
• Or delegate to npm installation

---

Affected Environments

This issue affects any cloud IDE or container environment with:

• Ephemeral home directories
• Persistent project/workspace directories
• Examples:
• Replit (confirmed)
• Gitpod (likely)
• GitHub Codespaces (likely)
• Cloud9 (possible)
• Temporary Docker containers (if not using volumes)

Environment Detection

To check if your environment is affected:

# Test 1: Check if workspace directory exists separately from home
ls -la /workspace 2>/dev/null || ls -la /home/runner/workspace 2>/dev/null

# Test 2: Check npm prefix
npm config get prefix | grep -q workspace && echo "✓ npm configured for workspace" || echo "⚠ npm uses home directory"

# Test 3: After restart, check if .local persists
touch ~/.local/test-persistence
# Restart workspace
ls ~/.local/test-persistence 2>/dev/null && echo "✓ .local persists" || echo "✗ .local is ephemeral"

---

Conclusion

For Replit environments:

• ✅ USE: npm install -g @anthropic-ai/claude-code
• ❌ AVOID: curl -fsSL https://claude.ai/install.sh | bash

The npm method aligns with Replit's workspace persistence model and provides zero-maintenance operation across workspace restarts.

---

Appendix: Quick Reference

One-Line Rollback Command

rm -rf ~/.local/share/claude ~/.local/bin/claude /home/runner/workspace/.local/{share/claude,bin/claude} 2>/dev/null; npm install -g @anthropic-ai/claude-code && echo "✓ Rollback complete"

Verify Installation Health

cat << 'EOF' > /tmp/verify-claude.sh
#!/bin/bash
echo "=== Claude Code Installation Health Check ==="
echo ""
echo "Binary location: $(which claude 2>/dev/null || echo 'NOT FOUND')"
echo "Version: $(claude --version 2>/dev/null || echo 'NOT AVAILABLE')"
echo "Credentials: $(ls ~/.claude/.credentials.json 2>/dev/null && echo 'EXISTS' || echo 'MISSING')"
echo ""
echo "Persistence check:"
which claude 2>/dev/null | grep -q workspace && echo "  ✓ Binary in workspace (will persist)" || echo "  ✗ Binary NOT in workspace (will be lost on restart)"
readlink ~/.claude 2>/dev/null | grep -q workspace && echo "  ✓ Credentials in workspace (will persist)" || echo "  ✗ Credentials NOT in workspace (will be lost on restart)"
echo ""
EOF
chmod +x /tmp/verify-claude.sh
/tmp/verify-claude.sh

Add to .bashrc for Automatic Health Check

Add this to your project's .bashrc or startup script:

# Claude Code health check (only warn, don't block)
if ! which claude &>/dev/null || ! which claude 2>/dev/null | grep -q workspace; then
  echo "⚠ WARNING: Claude Code not properly installed for Replit"
  echo "Run: npm install -g @anthropic-ai/claude-code"
fi

---

Report End

What Should Happen?

Upgrading to the non-deprecated/standard version should work in the Replit environment. A LOT of people are using it this way.

Error Messages/Logs

Steps to Reproduce

1. access a replit project
2. install Claude Code via npm (npm install -g @anthropic-ai/claude-code)
3. Uninstalling the npm version and overwriting with curl -fsSL https://claude.ai/install.sh | bash breaks claude code's functinoality in replit. exhaustive descriptoin and reasoning attached above.

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

2.1.13

Claude Code Version

v2.1.15

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Other

Additional Information

_No response_