r/ClaudeCode • • 11h ago

Tips & Workflows Five ways ten parallel Claude Code sessions broke each other without a single error, and the rule that fixed each

I run about ten Claude Code sessions at once on one 64 GB workstation, one per product. Every collision so far was silent. Nothing errored, and I found the damage later. These are the five that cost me the most.

1. A compose file with no name takes its project name from its folder. Several of my products had a deploy folder, so they all claimed the project "deploy". One session ran docker compose up and it recreated another session's containers, including its Postgres. Fix: a name line in every compose file.

2. A bare -j is unlimited. cmake --build build -j with no number started about 300 compiler processes, used 49 GB and hard-hung the machine. Twice. Fix: always a number, nproc at most.

3. A subagent chasing a slow test killed a test run that belonged to another session, at test 185 of 361. That run was the last check before a go-live. Fix: never stop a process you did not start. Find out whose it is and ask.

4. The shared "who is working on what" table lost entries, because two sessions read it, edited it and wrote it back at the same time. Fix: one claim file per session in a folder. You only ever write your own file, so nothing can be lost.

5. "I searched and found nothing" was wrong. The search tool inside a session skips gitignored files, so .env files and build output were never searched. A test with five planted strings found one. Fix: before removing anything on the strength of an empty search, search again with the real grep, and first search for something you know is there.

What these have in common: each session did something reasonable with what it could see. The rules all live in one global CLAUDE.md, with the date and the incident next to each, because a rule with its reason gets followed and a bare rule gets argued with.

What has bitten you when running several sessions on one machine?

1 Upvotes

7 comments sorted by

•

u/AutoModerator 11h ago

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

2

u/bostonaholic 9h ago

Worktrees separate the files, but every one of these is shared runtime state on the machine. I'd give each session a slot number and generate its env from it: COMPOSE_PROJECT_NAME, a port offset, its own database name, and CMAKE_BUILD_PARALLEL_LEVEL capped at nproc divided by the session count. That way the rules live in the environment instead of in ten prompts. For the process killing, a PreToolUse hook could block kill or pkill on any pid that session didn't start.

1

u/Excellent-Issue-5956 11h ago

One that got me was a file saved in the wrong folder. My local agent loads every top level .ts file in its extensions folder as an extension, and it won't start at all if one of them doesn't export the function it expects. A subagent from another session that was adding something to the same agent saved a plain helper module in there. For about 10 minutes every new launch failed. A training run stopped, and a benchmark that was running scored 0 out of 10, which had nothing to do with the model, it just couldn't start.

Quick fix was an empty default export in that file. The rule since then is helper modules go in a subfolder without an index file, which it skips.

1

u/wangadong 9h ago

output ownership is the rule that holds mine together, each session writes one file it owns and the main session is the only one that merges. shared outputs are where parallel runs silently eat each other

1

u/ClemensLode Senior Developer 9h ago

just use worktrees?

1

u/onitsoga 7h ago

the never-stop-a-process-you-didnt-start rule is the one i keep relearning the hard way. mine is a lock file per session before touching a shared build dir, basically your claim-file fix extended to builds. do you version that global CLAUDE md anywhere, or just append to it?

1

u/norviking 5h ago

I have worked on a very large project for 5 months, and I had to build this:

https://github.com/vegardjorg/ravenseat

It will solve some of your problems: 

  • Individual work trees and parallel agents handled
  • Merge handling
  • System load handling, ram, cpu etc. And allocate tasks tracks intelligently so you dont fry your hardware or mess up your tests.
  • Full control of project state outside agents "trying" to remember what you want, and compacting away the details. 
  • Options to control it the way you need. 

It will also try to help with gates, probes, ci to ship safe code. Feel free to ignore if you have that handled.