Skip to content
SlashClone
DiscoverUse in ClaudeSubmit a link
Sign in
Made by@slashclone

Parallel sessions

@slashclone/parallel-sessions

Build faster with several Claude Code sessions at once. Splits a big plan into independent workstreams, writes a brief for each, runs each in its own git worktree and branch, and merges every pull request on green CI in a safe order. Works in the Claude Code desktop app and in the terminal.

SkillDevOpsv0.1.0 (latest)
Use in Claude Save Like Clone Comment
Activity
New: be the first to try it
  1. 1---
  2. 2name: parallel-sessions
  3. 3description: Split a big build into independent workstreams and run each one as its own Claude Code session, in its own git worktree and branch, ending in its own pull request, while one lead session plans, briefs, and merges them in a safe order. Use when a plan has several pieces that can be built at the same time, when someone asks to "fan out", "run these in parallel", or "split this up", or before starting any multi-stage build.
  4. 4---
  5. 5
  6. 6# Parallel sessions
  7. 7
  8. 8Goal: turn one long, serial build into several sessions that work at the same time without stepping on each other, and land every piece safely on the main branch.
  9. 9
  10. 10One **lead** session (the one the person is talking to) plans and coordinates. Each **workstream** runs in its own session, in its own git worktree (a separate folder on its own branch), and ends in its own pull request. Nothing ships until CI passes on it.
  11. 11
  12. 12## When to use it
  13. 13
  14. 14Use it when a plan has two or more pieces of real work (more than a handful of tool calls each) that pass the independence test below. Do not split:
  15. 15
  16. 16- quick things (a question, one edit, a few commands): do them in the lead session;
  17. 17- a final check that needs every piece together (run the full test suite, a demo): run it in the lead after the pieces merge;
  18. 18- pieces that must land in one change together.
  19. 19
  20. 20## The independence test
  21. 21
  22. 22A piece can run in its own session only if all of these hold:
  23. 23
  24. 241. It needs no other piece's result to start.
  25. 252. No other piece needs its result to start.
  26. 263. It touches no files another piece touches, apart from shared append-only logs (see Conflict rules).
  27. 274. It does not need uncommitted changes from the lead session.
  28. 28
  29. 29If two pieces share files, either merge them into one workstream or run them one after the other.
  30. 30
  31. 31## Steps
  32. 32
  33. 331. **Plan.** Read the project's own rules (CLAUDE.md, README, contributing docs) and the plan. List the pieces of work.
  34. 342. **Group.** Apply the independence test. Group pieces into workstreams, aiming for 3 to 6. More than about 6 at once gets hard for one person to steer.
  35. 353. **Settle decisions first.** Anything only the person can decide (a new dependency, a vendor, a price, a policy) gets asked now, in one batch, so no session stalls on it later. Record each answer in the brief that needs it.
  36. 364. **Write a brief per workstream** using the template below. The brief is all the session knows, so it carries the quality of the result.
  37. 375. **Start the sessions.**
  38. 38 - **Claude Code desktop app:** start one session per workstream, each with its own worktree, and give it the brief. Name each one so it is easy to refer to.
  39. 39 - **Terminal:** for each workstream, run `git worktree add ../<repo>-<name> -b <name>` from the repository, open a new terminal there, start `claude`, and paste the brief. Show the person these commands; let them run them.
  40. 40 - **Inside one session only:** if neither of the above is available, run each workstream as a subagent with its own worktree, and open the pull requests yourself when they return.
  41. 416. **Coordinate.** While they run: answer questions a session sends, forward the person's decisions word for word, and watch for two sessions drifting toward the same files. Never poll; wait to be told a session finished a turn.
  42. 427. **Merge in order.** Each session merges its own pull request when CI passes. Shared files decide the order: the workstream that changes a shared convention (log format, config layout) merges last, after rebasing on everything else.
  43. 438. **Integrate.** When all pieces are on the main branch, the lead runs the checks that need everything together and reports what each session produced (its pull request, what is not done).
  44. 44
  45. 45## Brief template
  46. 46
  47. 47```text
  48. 48Task: <one paragraph: what to build and why>
  49. 49Area: <files, folders, and docs to read first>
  50. 50Decisions already made: <answers from step 3 that apply here>
  51. 51Rules: <the project's rules that matter: style, tests, security, no new dependencies without asking>
  52. 52Out of scope: <what other sessions are doing, so it stays in its lane>
  53. 53Shared files: <logs or configs others also touch, and how to resolve conflicts in them>
  54. 54Done means: <tests added, checks green, docs updated, one pull request merged on green CI, no release>
  55. 55Ask the person before: <anything outward facing or hard to undo>
  56. 56```
  57. 57
  58. 58## Conflict rules
  59. 59
  60. 60- **One writer per set of files.** Two sessions never edit the same files. If they must, run them in sequence.
  61. 61- **Shared append-only logs** (a progress log, a changelog) conflict on every parallel pull request. Tell each session to keep both entries in date order when it rebases, or better, switch to one file per session.
  62. 62- **Database migrations:** only one workstream adds migrations at a time, or each takes the next number only after rebasing, so two branches never claim the same number.
  63. 63- **Overlapping features** (two workstreams touching the same subsystem, for example two sign-in methods): name the overlap in both briefs and say which one builds the shared part; the other rebases onto it.
  64. 64- **Rebase, do not merge,** the main branch into a workstream before its final CI run.
  65. 65
  66. 66## Rules
  67. 67
  68. 68- Every workstream ends in a pull request that merges only after CI passes. Merging is not releasing; releases stay with the person.
  69. 69- A session's report is a claim, not proof. Check the pull request or diff before telling the person something is done.
  70. 70- Never invent or predict a session's result.
  71. 71- Never publish, send, buy, or delete anything outward facing from a workstream without the person's yes.
  72. 72- Keep secrets out of briefs. Point to where a secret lives, never paste its value.
Sign in to comment on a line

Cookie settings

Cookies that keep you signed in and remember these choices are always on. Everything else is off until you turn it on.