parallel-resource-isolation

A Claude Code skill that proactively detects and resolves resource conflicts when multiple Claude instances work on the same project in parallel.

Full skill reference: SKILL.md.

Problem

When two or more Claudes run simultaneously (e.g., in different worktrees), they collide on:

• Ports — both try to start a dev server on :3000, one fails and kills the other's process
• Databases — both write test data and assert on counts, getting each other's rows
• Playwright browsers — both fight over the same browser lock/temp directory, causing hangs

Install

Prerequisites:

• Claude Code installed
• macOS or Linux (uses lsof — Windows is not supported)
• Node + npx for Playwright workflows
• psql and Supabase CLI for DB-isolation workflows
• Stack: Next.js + Supabase + Playwright (other stacks need adapter work — see Limitations)

Clone into your skills directory:

git clone https://github.com/techiejd/claude-skill-parallel-resource-isolation.git ~/.claude/skills/parallel-resource-isolation

Or grab just SKILL.md with curl:

mkdir -p ~/.claude/skills/parallel-resource-isolation && \
  curl -fsSL https://raw.githubusercontent.com/techiejd/claude-skill-parallel-resource-isolation/main/SKILL.md \
  -o ~/.claude/skills/parallel-resource-isolation/SKILL.md

To update later: cd ~/.claude/skills/parallel-resource-isolation && git pull (clone install only).

Verify it works

Open Claude Code in two worktrees of the same project. In each, ask Claude to start the dev server. The second should report something like:

⚡ Parallel isolation:
  Dev server: port 3001 (3000 was in use)

If both Claudes try port 3000 and one kills the other's process, the skill didn't load — re-check the directory path.

Solution

Pure Scout approach — each Claude observes system state, silently adapts, and reports what it chose. No coordination files, no lock files, no shared state. (Lockfiles require crash cleanup; observation is stateless and self-healing.)

Resource	Detection	Adaptation	Cleanup
Dev server port	lsof -i :<port>	PORT=<next_free>	None
Supabase DB	Check if tests write/assert	parallel_<epoch>_ schema	Drop schema after tests
Playwright browser	Check for lock contention	TMPDIR or PLAYWRIGHT_BROWSERS_PATH	Auto-cleaned

Limitations

• Platform: macOS / Linux only. lsof is not available on Windows.
• Stack: Built for Next.js + Supabase + Playwright. Other stacks (Vite, SvelteKit, Drizzle, plain Postgres) will install successfully but get no adaptive behavior until a stack adapter is added — see Contributing.
• DB isolation requires Supabase CLI. The DB workflow uses npx supabase db push and is tied to Supabase's schema-per-environment pattern.
• Sub-second epoch collisions. Two Claudes spawning in the same wall-clock second can pick identical parallel_<epoch>_ schema names. Rare in practice; flag if observed.

Test methodology

Validated through subagent pressure scenarios across RED/GREEN/REFACTOR cycles — agents instructed to start dev servers, run e2e tests, and write to the DB without seeing each other. Without the skill, agents kill each other's processes and use shared DB state. With the skill, all three resource types are isolated.

Star this project

Stars are the signal I use to decide whether to keep investing in a skill. If parallel-resource-isolation saved you a port collision or a corrupted-DB debug session, star the repo — it's the difference between this getting more stack adapters and going stale.

Contributing

Issues and PRs welcome — especially stack adapters (Vite, SvelteKit, plain Postgres, Vitest). When proposing an adapter, describe the failure mode in the new stack and what lsof/env-var pattern resolves it. See SKILL.md for the existing patterns.

License

MIT