Multi-Instance Shell State Corruption: Shell commands fail when running concurrent Claude Code instances

Multi-Instance Shell State Corruption in Claude Code

Summary

Claude Code experiences critical shell execution failures when multiple instances run simultaneously due to shared state directory conflicts and race conditions in shell snapshot management.

Environment

• Claude Code Version: Latest (npm @anthropic-ai/claude-code)
• OS: WSL2 Ubuntu 22.04.3 LTS
• Shell: bash 5.2.21(1)-release
• Node.js: v18+

Problem Description

When running multiple Claude Code instances concurrently, shell commands fail persistently with:

/home/david/.claude/shell-snapshots/snapshot-bash-1752999626115-sz1uwp.sh: No such file or directory

Root Cause Analysis

1. Shared State Directory Conflicts:

• All instances write to the same ~/.claude/ directory
• No process isolation or file locking mechanisms
• Shell snapshots, session state, and configuration files are shared across instances

2. Shell Snapshot Race Conditions:

Instance A: Creates snapshot-bash-1752999626115-sz1uwp.sh
Instance B: Runs cleanup, deletes "old" snapshot from Instance A  
Instance A: Tries to source deleted snapshot → FAILURE

3. Session State Corruption:

• Multiple instances updating ~/.claude.json simultaneously
• Shell snapshot references getting overwritten/corrupted
• Memory and state files experiencing concurrent write conflicts

Reproduction Steps

1. Open two terminals
2. Start first Claude Code instance:

``bash
# Terminal 1
claude --model claude-sonnet-4 --continue
``

1. Start second Claude Code instance:

``bash
# Terminal 2
claude --model claude-opus-4 --continue
``

1. Execute bash commands in first instance:

``bash
# In Claude Code Terminal 1
ls /home/user # This will fail
``

1. Observe the error:

``
/home/user/.claude/shell-snapshots/snapshot-bash-[TIMESTAMP].sh: No such file or directory
``

Evidence from Debug Session

Active Instances Observed:

$ ps aux | grep claude
david    11352  claude --model claude-opus-4 (pts/8, running 43+ minutes)
david    25907  claude --model claude-sonnet-4 (pts/6, running 7+ minutes)  
david    28489  claude --debug --print (pts/6, running 4+ minutes)

Shell Snapshot Directory State:

$ ls -la ~/.claude/shell-snapshots/
total 8
drwxr-xr-x  2 david david 4096 Jul 20 05:50 .
drwxr-xr-x 30 david david 4096 Jul 20 05:49 ..
# Empty directory, but instances still reference deleted snapshots

Workaround That Works:

• Desktop Commander MCP server commands work fine (bypasses Claude's shell management)
• Direct process execution via MCP tools functions correctly

Impact

• Critical Functionality Loss: All bash-based tools become unusable
• Silent Failure Mode: No clear error indication to users
• Session Persistence: Issue persists across command attempts
• Unpredictable Behavior: Affects seemingly random instances

Proposed Solutions

Immediate Fix (Backward Compatible)

1. Process-Specific State Directories:

~/.claude/sessions/<PID>/
├── shell-snapshots/
├── temp-files/
└── session-state.json

2. File Locking:

// Pseudocode
const lockFile = path.join(claudeDir, '.session.lock');
await fs.lock(lockFile, { timeout: 5000 });

3. Session Isolation:

• Each instance manages only its own shell state
• Cleanup only removes own snapshots on exit
• Unique namespace per process

Long-term Architecture Improvements

1. Session Management API:

interface SessionManager {
  createSession(processId: string): Session;
  cleanupSession(processId: string): void;
  listActiveSessions(): Session[];
}

2. Graceful Degradation:

• Detect conflicts and fall back to stateless execution
• Automatic recovery from corrupted state
• Better error reporting to users

3. Health Checks:

• Periodic validation of shell snapshot references
• Automatic cleanup of orphaned files
• Session state consistency verification

Temporary User Workarounds

Immediate Recovery:

# Kill all Claude instances
pkill -f claude

# Clear shared state
rm -rf ~/.claude/shell-snapshots/*
rm -f ~/.claude/.*.tmp*

# Restart one instance at a time

Prevention:

• Run only one Claude Code instance at a time
• Use different user accounts for concurrent usage
• Implement custom process isolation via containers

Related Issues

This appears to be a fundamental architecture issue where Claude Code assumes single-instance usage but doesn't enforce or gracefully handle multi-instance scenarios.

Additional Context

• Issue discovered during MCP server debugging session
• Affects both --continue and --debug modes
• Problem persists across Claude Code restarts until manual cleanup
• Shell snapshot cleanup mechanism appears to be global rather than process-specific

Suggested Priority

High Priority - This affects basic functionality and creates a poor user experience with no clear error messaging or recovery path.