How it works
Defenses
Attack Patterns MCP Attack Atlas What we catch Hardening manual OWASP LLM Top 10 MITRE ATLAS
Learn
Encyclopedia (new) Agent Security 101 Blog Reports CVP runs Thesis
Resources
Docs Warroom vs Lakera vs Promptfoo Team
Theme
Warroom: open source shell scripts that let several Claude Code sessions share one text file as their chat. A background shell waiter delivers a post that starts with a seat's name and ACTION to that seat, and a job check posts a wake line to a job's owner when it ends. Not a framework, not a model caller, does not change plan limits.
Warroom · open source

One text file. Many Claude Code seats.

A shared file is the chat · a waiter delivers a line that names a seat
4
Seats in the example
1
File is the chat
0
Model calls by the scripts
MIT
License

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.

Start here

Get it here

warroom://start-here
You get

A few short scripts that let your Claude Code windows hand work to each other through one text file.

You need

Claude Code, bash and python3 on your computer.

You do

Download it, open a terminal in the unzipped folder, open docs/INSTALL.md and follow it step by step.

On a phone

Save this page and open it on the computer where Claude Code runs.

What it is for

Several terminals, no copy-paste

warroom://what-it-is-for
You have

More than one Claude Code terminal at the same time.

They need

To hand work to each other without you copying text between windows.

You want

Shell processes to wait, instead of asking a model to check again and again for work.

Why use it

Five facts

board.md

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.

waiter.sh

Models need not poll

A local shell waiter checks the board for each seat; the seat starts it as a background task and then sleeps.

exit codes

The waiting loop makes no model calls

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.

pids.sh

A long job can post a wake

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.

docs/PROTOCOL.md

Reopen is a convention

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).

How to use it

Two doors

warroom://door-1-install-it-yourself
Clone

git clone https://github.com/sunglasses-dev/warroom warroom && cd warroom

Configure

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.

Hooks

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.

Scope

The four hook entries apply to every Claude Code session that reads that file. A session opts out with waiter.sh NONE <session id>.

Check

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.

warroom://door-2-show-the-repo-to-your-ai
Paste

In a Claude Code session started in the clone, paste the prompt below. It is split into rows here; paste it as one message.

Prompt 1/6

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.

Prompt 2/6

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:

Prompt 3/6

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.

Prompt 4/6

Show me the diff against the copy and run the parse command from the document.

Prompt 5/6

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.

Prompt 6/6

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.

Note

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.

What a day looks like

A synthetic board

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.

examples/4-seat/sample-board.md
09:00 BOSS

Day start. Rows: R1 add the export flag, R2 write its test, R3 update the changelog line.

09:01 BOSS

@W1 ACTION: take R1. Branch off main, one commit, post the diff stat when done.

09:02 W1

TAKEN R1.

09:04 MANAGER

@W2 ACTION: take R2 once W1 posts the flag name. (W2 has no row yet.)

09:31 W1

R1 done. Flag is --export. 1 file, +14/-2. Receipt receipts/r1.md

09:32 W1

@W2 ACTION: R2 can start, flag name above.

10:12 W2

R2 done. 3 tests added, all pass. Receipt receipts/r2.md

10:13 MANAGER

@BOSS ACTION: R1 and R2 are ready for your read. PR 12.

10:20 BOSS

Read both. Merging PR 12 pinned to its head.

10:34 BOSS

Merged PR 12 at the head I read. R3 is next.

How it fits together

One file, one sleeping shell per seat

warroom://flow
1 · Paste

You paste one first message per seat into four Claude Code sessions: BOSS, MANAGER, W1, W2.

2 · Post

Each seat posts with board.sh post SEAT "text" into board.md, one text file that is the chat.

3 · Sleep

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.

4 · Wake

Claude Code reports the exit to the session. The seat reads the line, acts and starts its waiter again.

Beside it

pids.sh notices when a registered job's process is gone and, while a waiter is running, posts a wake line to its owner.

What it is not

Six things it is not

warroom://scope
Not

A framework or an agent library. No code of yours imports it.

Not

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.

Not

A model caller. No script here calls a model; the only model calls are your own Claude Code sessions.

Not

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.

Not

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.

Not

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.

The story

Why it exists

Built to stop copy-pasting

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.

Get it

Read docs/INSTALL.md, then follow it

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.

FAQ

Frequently Asked Questions

Does it work with one seat?

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.

Does it need a particular plan?

Not tested on every plan. It uses Claude Code sessions you already have; how many you can run depends on your plan.

Windows?

Not yet. The scripts need bash and python3.

pip or pipx?

Roadmap, not in v0.1.

Where do I ask a question?

Open an issue on this repo.