Feature: Support per-instance config directory for multi-agent environments

Summary

Running multiple Claude Code instances in parallel on the same machine causes crashes due to lock file contention on the shared ~/.claude/ directory.

Environment

• OS: Windows 11 (also affects Linux/WSL)
• Claude Code version: Latest
• Use case: 8 developer agents running in parallel from separate workspace directories

Problem

All Claude Code instances share a single ~/.claude/ directory:

~/.claude/
├── history.jsonl
├── history.jsonl.lock    ← All instances compete for this
├── settings.json
├── .credentials.json
└── projects/

When multiple agents run simultaneously, they compete for history.jsonl.lock, causing:

Error: EBADF: bad file descriptor, realpath 'C:\Users\asafe\.claude\history.jsonl.lock'
    at async realpath (node:internal/fs/promises:1173:10)
    at async mi1._addToNodeFs (file:///cli.js:448:10239)

This crashes agents unexpectedly and disrupts parallel workflows.

Proposed Solution

Support an environment variable to specify a custom config directory per instance:

# Agent 1
CLAUDE_CONFIG_DIR=~/.claude-agent1 claude

# Agent 2  
CLAUDE_CONFIG_DIR=~/.claude-agent2 claude

# Or alternatively
CLAUDE_HOME=~/.claude-agentx claude

Each instance would have isolated:

• History files and locks
• Settings
• Credentials (or symlinked to shared)
• Project caches

Workarounds Attempted

• Cleaning stale lock files (rm ~/.claude/*.lock)
• Increasing file descriptor limits (ulimit -n 4096)
• Staggering agent launches

These reduce frequency but don't eliminate the issue.

Related Issues

• #4473 - Lock file error and agent timeout issues
• #3531, #3944, #4014 - Related lock/concurrency issues

Use Case

Multi-agent development environments where several Claude Code instances work on different repositories/branches simultaneously. Each agent has its own:

• Git worktree
• Workspace directory
• Terminal session

But they all collide on the shared ~/.claude/ config directory.

---

Thank you for considering this feature. Happy to provide additional details or test proposed solutions.