parallel-streams.

#What it is

A working method plus three small scripts per platform (runner, launcher, takeover) that split a project too big for one agent session into independent work streams and build them in parallel headless claude -p loops, one terminal per stream. The part that makes it worth a repo: each runner is limit-tolerant. When the subscription window runs out mid-build, the runner detects it, sleeps 15 minutes, and picks the stream back up until the stream writes its done marker or hits a hard deadline.

#The itch

Overnight headless builds die at the usage limit. The window empties at 2am, the process exits, and nothing happens until you wake up, even though the window refills on its own a while later. The fix in one line from the README: you go to sleep; the streams do not.

#How it works

Each stream is a loop around claude -p. The first iteration sends the stream's brief, a markdown file you write; the following iterations resume the session by id with context intact. An exit code other than zero, or a session shorter than 120 seconds, counts as a limit hit: the runner sleeps 15 minutes and then starts fresh by default, letting the stream re-read its brief and its own progress file instead of dragging a monotonically grown context along. The repo calls that context rotation. After the pause the prompt cache is cold anyway, so resuming saves nothing, and long contexts make the model worse. The loop ends when the stream writes its done marker, at the deadline hour (default 9:00), or after 60 iterations.

Around the loop: a PID lock so two runners never share a stream, state files plus a heartbeat file that lets an external watchdog spot a frozen runner, and per-stream tool allow and deny lists for guardrail runs. Two intervention paths are designed to never break the auto-resume loop: steer, an async note the runner appends to the next iteration's prompt, and takeover, which pauses the runner cleanly and opens the same session interactively so you can type along.

#In real use

The Windows runner (PowerShell) is battle-tested: real overnight builds with limit pauses, resumes, steering, and takeovers. The overnight run that packaged the repo itself ran on it. The POSIX port is the opposite, and the repo says so: a careful line-by-line port that has never executed on a real Mac or Linux box. CI runs dash -n, bash --posix -n, and shellcheck over it on every push, and the README calls that the honest maximum for code that has never run on its target platforms.

The stated limits: at most 3 streams in parallel, because more pushed a mid-range machine into paging in real runs. N streams drain the subscription window roughly N times faster. Headless means no browser, so interactive logins and visual QA stay with you. And in real runs, done markers repeatedly appeared at least one iteration before the work actually met its definition of done, so verifying a stream's output stays a human job.

#Install

$ git clone --depth=1 https://github.com/belschak/parallel-streams.git \
  ~/.claude/skills/parallel-streams

The runners ship inside the repo. Per project you copy them into a .streams/ folder and write one brief per stream; the README has the full quickstart for Windows and for the untested POSIX path.

#Links

---