[BUG] .claude.json race condition — reported 8 times since June 2025, all closed without resolution

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?

Preflight Checklist

• [x] I have searched existing issues — this has been reported at least 8 times since June 2025 (see table below). All were closed without a fix.
• [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.json is repeatedly corrupted by concurrent Claude Code sessions due to non-atomic file writes with no locking. Running 3-5 terminal sessions simultaneously results in truncated/invalid JSON multiple times per day, requiring manual recovery or restart.

This is a well-documented race condition that has been reported at least 8 times across all platforms since June 2025. Every report identifies the same root cause and proposes the same fix. All have been closed without resolution:

| Issue | Title | Date | Platform | Status |
|-------|-------|------|----------|--------|
| #2593 | .claude.json is truncated directly, and so occasionally gets corrupted | Jun 2025 | macOS | Closed as not planned |
| #2810 | Claude Code Configuration File Corruption | Jul 2025 | Linux | Closed |
| #3117 | Claude code corrupts ~/.claude.json on mac while running 5 concurrent sessions | Jul 2025 | macOS | Closed |
| #7243 | The .claude.json elephant in the room: Is this "vibe coding" in production? | Sep 2025 | Cross-platform | Closed as not planned |
| #7273 | Corrupt .claude.json spams a bunch of stupid files and ruins previous config | Sep 2025 | Windows | Closed as not planned |
| #15608 | Config file corruption when multiple Claude Code processes run concurrently | Dec 2025 | Windows | Closed |
| #18998 | Severe .claude.json corruption in multi-project environments (30+ concurrent sessions) | Jan 2026 | Linux/WSL2 | Open (no response) |
| #26717 | EOF error, corrupted json file | Feb 2026 | Windows | Closed |

The same pattern also affects .credentials.json — see #27933 (OAuth token refresh race, filed 3 days ago).

Root Cause

Claude Code truncates and rewrites .claude.json in place on every update. With multiple processes:

1. Session A reads .claude.json
2. Session A truncates the file and begins writing
3. Session B reads the partially-written (now invalid) file
4. Corruption detected, backup/restore cycle triggered

There is no file locking, no atomic write, and no per-session isolation.

What Should Happen

Writes to .claude.json should be atomic: write to a temp file, fsync, then rename into place. This is standard practice for config file management and prevents partial reads entirely. Per-session or per-project config isolation (e.g. --config flag or ~/.claude/sessions/) would further eliminate contention for multi-instance workflows.

Steps to Reproduce

1. Open 3+ Claude Code terminal sessions pointing at different projects
2. Use them normally
3. Within hours (sometimes minutes), at least one session will report .claude.json is corrupted

Error Messages/Logs

Claude configuration file at C:\Users\<user>\.claude.json is corrupted: JSON Parse error: Unexpected EOF
The corrupted file has been backed up to: C:\Users\<user>\.claude.json.corrupted.<timestamp>
A backup file exists at: C:\Users\<user>\.claude.json.backup
You can manually restore it by running: cp "C:\Users\<user>\.claude.json.backup" "C:\Users\<user>\.claude.json"

Environment

• OS: Windows 11
• Claude Code Version: 2.1.59 (but issue spans all versions since at least 1.0.35)
• Shell: PowerShell
• Concurrent sessions: 3-5 typical
• Platform: Anthropic API

Additional Context

This bug disproportionately affects power users — the exact audience Claude Code is built for. Running multiple sessions across projects is a core workflow, not an edge case. The fix (atomic write via temp + rename) is a few lines of code and has been a solved problem for decades. I'm currently running a file watchdog script that monitors .claude.json and auto-restores from backup on corruption, which is not a thing a user should need to do.

I'm filing this as a new issue because every prior report has been closed without a fix or explanation. If there's a technical reason this can't be addressed, I'd genuinely like to understand it.

What Should Happen?

.claude.json should remain valid JSON at all times, regardless of how many Claude Code sessions are running concurrently. Writes should be atomic (temp file → fsync → rename) so that no process ever reads a partially-written file. Ideally, per-session or per-project config isolation (e.g. --config flag or ~/.claude/sessions/) would eliminate file contention entirely for multi-instance workflows, which is a core use case for Claude Code's target audience.

Error Messages/Logs

Steps to Reproduce

1. Open 3+ Claude Code terminal sessions pointing at different projects
2. Use them normally (doesn't require any specific action — just regular usage)
3. Within hours (sometimes minutes), at least one session will report .claude.json is corrupted with "Unexpected EOF" or similar JSON parse error
4. Recovery prompt appears with backup restore instructions

No specific trigger required — the race condition is inherent to any concurrent access pattern. Higher session count and heavier usage increase frequency.

Claude Model

Not sure / Multiple models

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.59

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Windows Terminal

Additional Information

_No response_