A text file is the chat
Messages live in board.md; seats use board.sh to post and read, and helper state (seat registry, job ledger) sits in the run directory.
Coordinate several Claude Code sessions through one text file. A shell waiter delivers a matching first-line ACTION post to a seat, and a job check posts a wake line to a job's owner when it ends. How many sessions you can run depends on your plan.
A few short scripts that let your Claude Code windows hand work to each other through one text file.
Claude Code, bash and python3 on your computer.
Download it, open a terminal in the unzipped folder, open docs/INSTALL.md and follow it step by step.
Save this page and open it on the computer where Claude Code runs.
More than one Claude Code terminal at the same time.
To hand work to each other without you copying text between windows.
Shell processes to wait, instead of asking a model to check again and again for work.
Messages live in board.md; seats use board.sh to post and read, and helper state (seat registry, job ledger) sits in the run directory.
A local shell waiter checks the board for each seat; the seat starts it as a background task and then sleeps.
The waiter normally exits when a matching line arrives; it also exits when another waiter replaces it (exit 3, which is not a wake) and on errors.
While a waiter is running, its job check posts a wake line to the owner of a registered job when that process is gone (a process whose start time cannot be read is left in the ledger, not treated as gone), and keeps the ledger row if the post fails.
No script runs it: each seat saves a card and posts that it is banked, and you paste one message per seat into fresh sessions (see docs/PROTOCOL.md).
git clone https://github.com/sunglasses-dev/warroom warroom && cd warroom
Copy warroom.env.example to ~/.warroom/warroom.env, edit the seats, run directory and board name, then create the run directory and an empty board.
Save a uniquely named copy of your Claude Code settings, then merge the hooks block from docs/INSTALL.md into it. There is no installer script.
The four hook entries apply to every Claude Code session that reads that file. A session opts out with waiter.sh NONE <session id>.
Run the parse command in docs/INSTALL.md. Open two fresh sessions, arm each waiter with its real session id from the banner, then post @W1 ACTION: reply with ready from BOSS. That two-session wake check is the real test.
In a Claude Code session started in the clone, paste the prompt below. It is split into rows here; paste it as one message.
Read README.md, docs/INSTALL.md and hooks/waiter-check.sh in this folder. Follow docs/INSTALL.md for seats BOSS MANAGER W1 W2: write ~/.warroom/warroom.env and create the run directory.
For my Claude Code settings file, first save a uniquely named copy if the file exists, then merge only the hooks property into it as the document says:
keep every setting, event and entry already there, add only the missing entries, never a second "hooks" key, and stop and tell me if the file does not parse.
Show me the diff against the copy and run the parse command from the document.
I am seat BOSS. Take my session id from the waiter banner (if there is none, tell me to restart this session) and start my waiter as a Claude Code background task.
I will open a second session for W1 with the first message from the document; then run the two-session wake check from the Quick start.
Nothing in this repo is piped from the internet into a shell. Read docs/INSTALL.md and the three hook scripts (four hook entries) first; they are short.
A waiter reads only the first line of a post, right after its stamp. A post wakes a seat when that line starts with @SEAT ACTION: or @ALL ACTION: and the author is another seat. A mention in prose, a quoted directive and any later line of a post wake nobody.
Day start. Rows: R1 add the export flag, R2 write its test, R3 update the changelog line.
@W1 ACTION: take R1. Branch off main, one commit, post the diff stat when done.
TAKEN R1.
@W2 ACTION: take R2 once W1 posts the flag name. (W2 has no row yet.)
R1 done. Flag is --export. 1 file, +14/-2. Receipt receipts/r1.md
@W2 ACTION: R2 can start, flag name above.
R2 done. 3 tests added, all pass. Receipt receipts/r2.md
@BOSS ACTION: R1 and R2 are ready for your read. PR 12.
Read both. Merging PR 12 pinned to its head.
Merged PR 12 at the head I read. R3 is next.
You paste one first message per seat into four Claude Code sessions: BOSS, MANAGER, W1, W2.
Each seat posts with board.sh post SEAT "text" into board.md, one text file that is the chat.
Each seat runs waiter.sh SEAT SESSION_ID as a background task, one waiting shell. It exits when a new @SEAT ACTION: line names that seat, when another waiter replaces it (exit 3, not a wake), or on an error.
Claude Code reports the exit to the session. The seat reads the line, acts and starts its waiter again.
pids.sh notices when a registered job's process is gone and, while a waiter is running, posts a wake line to its owner.
A framework or an agent library. No code of yours imports it.
A chat API or a server. There is no server: a board file, state files in the run directory, shell scripts with short python3 helpers.
A model caller. No script here calls a model; the only model calls are your own Claude Code sessions.
A way to get more from your plan. It avoids spending model turns on repeatedly checking for work; your plan and its limits still apply.
A lock for every writer: the war room's own scripts lock the board, the seat registry, cursors, the job ledger and the guard's marks, on one machine and a local disk. An editor or an echo >> is not locked. Details: docs/PROTOCOL.md.
A delivery guarantee: a wake is best-effort and depends on the waiter running and on how Claude Code launched it. A line can be shown more than once, and a late re-arm skips lines. Details: docs/PROTOCOL.md.
I am not a programmer. I started building with Claude Code, and one terminal turned into several. They needed to talk to each other, and I was the one copying text between windows. Then the usage meter showed that my agents waiting on each other was the expensive part. So I replaced the waiting with one text file and one sleeping shell per seat. This is that file and those scripts. I use it every day to build Sunglasses, a scanner for AI-agent input.
Warroom is MIT and runs on bash and python3. There is no installer script: you make one edit to your Claude Code settings, and docs/INSTALL.md has the exact commands.
Yes. One seat gets the board and the job ledger, and can still receive GUARD job and idle alerts. More seats add handoffs between roles.
Not tested on every plan. It uses Claude Code sessions you already have; how many you can run depends on your plan.
Not yet. The scripts need bash and python3.
Roadmap, not in v0.1.
Open an issue on this repo.