Skip to content

One live console to monitor Claude Code and Codex agents across machines, track context and spend, and unblock sessions that need you.

Update README

yuz207eaa7dad788a0
diff --git a/README.md b/README.md
index 2881815..96f064d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,33 @@
-# SITREP
+<p align="center">
+ <picture>
+ <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg">
+ <img src="docs/logo-light.svg" alt="" width="96" height="96">
+ </picture>
+</p>
-**Every Claude Code and Codex session, on every machine, in one live view.**
+<h1 align="center">SITREP</h1>
+
+<p align="center"><b>Every Claude Code and Codex session, on every machine, in one live view.</b></p>
+
+<p align="center">
+ <a href="#try-it-in-two-minutes">Try it</a> ·
+ <a href="#install">Install</a> ·
+ <a href="docs/TUTORIAL.md">Tour</a> ·
+ <a href="docs/HOW-IT-WORKS.md">How it works</a> ·
+ <a href="docs/OPERATIONS.md">Operations</a>
+</p>
+
+<p align="center">
+ <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue"></a>
+ <img alt="Node 24" src="https://img.shields.io/badge/node-24-339933?logo=nodedotjs&logoColor=white">
+ <img alt="macOS and Linux" src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey">
+</p>
+
+> *“Who will guard the guards themselves?”*
+>
+> — Juvenal, *Satires*
+
+![The Fleet](docs/tutorial/01-fleet-cards.png)
You run coding agents on a laptop, a workstation and a server. SITREP shows all of them at once: which are working,
which are waiting on you, which are stuck or have failed. Answer the ones that are waiting from the dashboard, without
@@ -10,13 +37,9 @@ hunting for their terminal.
|---|---|---|
| Every session on every machine as cards, a list or a graph, each with its plan and current step, its agents, model and effort, context fill, git state, cost, and what failed. | Every permission, question and plan that is waiting sits at the top, longest wait first; answer it there or in the terminal, and the first answer wins. | It sends a session only your own answers, messages and commands, never controls a terminal, never starts, stops or restarts a session, stores no transcripts, and runs on a machine you own. |
-![The Fleet: every live session as a card, grouped by machine, under the usage panel's estimated spend by model and its charts](docs/tutorial/01-fleet-cards.png)
-
-*A simulated fleet, drawn by the real interface: no project, path or session in the pictures on this page is real.*
-
## Try it in two minutes
-No agents needed: a simulator fills the dashboard with a fleet. You need git and Node 24.
+You need git and Node 24. A simulator stands in for the agents.
```sh
git clone https://github.com/IluvatarLabs/sitrep ~/sitrep && cd ~/sitrep
@@ -33,9 +56,10 @@ npx tsx scripts/sim.ts --sessions 8 --codex 0.4 --machines 3 --chaos
## Install
-**Before you put it on a network:** SITREP is built for one person on a trusted LAN. It speaks plain HTTP, by default
-anyone who can reach port 7487 can read every session, and answering needs a sign-in with the admin secret.
-[Operations: Security](docs/OPERATIONS.md#security-one-owner-one-secret) says what that means and how to narrow it.
+> [!WARNING]
+> SITREP is built for one person on a trusted LAN. It speaks plain HTTP: anyone who can reach port 7487 can read every
+> session, and answering needs a sign-in with the admin secret.
+> [Security](docs/OPERATIONS.md#security-one-owner-one-secret) says how to narrow that.
### The server
@@ -48,14 +72,14 @@ npx tsx scripts/install.ts --server --bind 0.0.0.0 # dry run: prints
npx tsx scripts/install.ts --server --bind 0.0.0.0 --apply
```
-It starts as a user service and writes an admin secret to `~/.sitrep/server.env`. Open `http://<server IP>:7487`, by
-the machine's IP address: the server refuses a host name until it is listed in `SITREP_ALLOWED_HOSTS`
-([Operations: Deploy the server](docs/OPERATIONS.md#deploy-the-server), step 6).
+It runs as a user service and writes an admin secret to `~/.sitrep/server.env`. Open `http://<server IP>:7487`. Use the
+IP address: a host name has to be listed in `SITREP_ALLOWED_HOSTS` first
+([Deploy the server](docs/OPERATIONS.md#deploy-the-server), step 6).
### Add a machine
-On each machine that runs sessions. In the dashboard, Machines → Add a machine gives these commands for that machine's
-OS and harness, each with Copy:
+On each machine that runs sessions. Machines → Add a machine in the dashboard gives these commands with your server's
+address filled in:
```sh
git clone https://github.com/IluvatarLabs/sitrep ~/sitrep && cd ~/sitrep && npm ci
@@ -63,24 +87,19 @@ npm run build -w codex-reporter # only where Codex
npx tsx scripts/install.ts --claude --codex --url http://<server IP>:7487 --token-stdin --apply
```
-The installer takes the admin secret on its standard input: paste it, then Ctrl-D. Leave out `--claude` or `--codex` on
-a machine without that tool. [Operations: Add a machine](docs/OPERATIONS.md#add-a-machine) has the form that pipes the
-secret from the server instead. On Node 22, `npm ci` warns that the repository asks for Node 24; that is the server's
-requirement, and the install goes on.
+Paste the admin secret, then Ctrl-D. Leave out `--claude` or `--codex` where that tool is not installed.
+[Add a machine](docs/OPERATIONS.md#add-a-machine) has the form that pipes the secret from the server.
`npx tsx scripts/doctor.ts` checks a machine and prints the fix for anything wrong.
-`npx tsx scripts/uninstall.ts --claude --codex --server` lists what it would remove: the plugins, the services and the
-settings the installer set. `--apply` removes them, and `--purge` also deletes the config and data it otherwise keeps
-([Operations: Uninstall](docs/OPERATIONS.md#uninstall)). Your own hooks are never touched.
+`npx tsx scripts/uninstall.ts --claude --codex --server` lists what it would remove, and `--apply` removes it
+([Uninstall](docs/OPERATIONS.md#uninstall)). Your own hooks are never touched.
## What it looks like
-The same simulated fleet, in four more views.
-
| | |
|---|---|
-| ![Sessions and their agents as a graph](docs/tutorial/03-fleet-graph.png) | ![One session: its plan, agents and timeline](docs/tutorial/07-session.png) |
-| ![Every plan step on a board](docs/tutorial/04-plans.png) | ![The Fleet in the light theme](docs/tutorial/05-fleet-light.png) |
+| ![Graph](docs/tutorial/03-fleet-graph.png) | ![A session](docs/tutorial/07-session.png) |
+| ![Plans](docs/tutorial/04-plans.png) | ![The light theme](docs/tutorial/05-fleet-light.png) |
## What it does
@@ -96,16 +115,16 @@ The same simulated fleet, in four more views.
[Settings and History](docs/TUTORIAL.md#settings-and-history)
- **A wall view** for a screen left on, and browser notifications when a session needs you, is stuck or fails, or a plan
window reaches 90 %. [Filter and keys](docs/TUTORIAL.md#filter-and-keys)
-- **Claude Code, Codex and Hermes** today; Hermes sessions are shown, not answered. A value a harness does not report
- shows as "—", never as a guess, and every cost is marked "est.". [The pieces](docs/HOW-IT-WORKS.md#the-pieces)
+- **Claude Code, Codex and Hermes.** Hermes sessions are shown, not answered. A value a harness does not report shows as
+ "—", never as a guess, and every cost is marked "est.". [The pieces](docs/HOW-IT-WORKS.md#the-pieces)
## What you need
- macOS or Linux, with git. It has not been run on Windows.
-- Node 24 on the server; Node 22.15 or later on every other machine, where the installer and codex-reporter run on it.
+- Node 24 on the server; Node 22.15 or later on every other machine (`npm ci` warns there that the repository asks for
+ 24, and installs anyway).
- Claude Code 2.1.287 or later.
-- Codex 0.162 or later, the oldest version it has been run with. Answering Codex sessions also needs Codex's managed
- daemon on that machine.
+- Codex 0.162 or later. Answering Codex sessions also needs Codex's managed daemon on that machine.
- Docker, for Hermes: its reporter is a sidecar container.
## Docs
@@ -115,17 +134,7 @@ The same simulated fleet, in four more views.
- [Operations](docs/OPERATIONS.md): deploying, settings, security, backup, upgrades, troubleshooting.
- [Hermes](hermes-reporter/README.md): the sidecar.
-| Path | What |
-|---|---|
-| `server/` | The server: the reporters' API, the SQLite store, and the dashboard it serves |
-| `frontend/` | The dashboard (React, Vite) |
-| `mod/claude-reporter/` | The Claude Code plugin `sitrep-reporter` |
-| `codex-reporter/` | The Codex plugin `sitrep-codex` and the `codex-reporter` service |
-| `hermes-reporter/` | A read-only sidecar for Hermes |
-| `scripts/` | Install, uninstall, doctor, and the fleet simulator |
-| `docs/` | The guides above, their screenshots, and sample reports (`fixtures/`) |
-
## License
-MIT: see [LICENSE](LICENSE). Third-party material keeps its own license: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md),
-and [frontend/THIRD_PARTY_NOTICES.md](frontend/THIRD_PARTY_NOTICES.md) for the logos.
+[MIT](LICENSE). Third-party material keeps its own license: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), and
+[frontend/THIRD_PARTY_NOTICES.md](frontend/THIRD_PARTY_NOTICES.md) for the logos.
diff --git a/docs/logo-dark.svg b/docs/logo-dark.svg
new file mode 100644
index 0000000..6c6da5b
--- /dev/null
+++ b/docs/logo-dark.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="96" height="96">
+ <!-- SITREP's mark for dark pages: an S drawn as one line between two stations, the far one working. -->
+ <path d="M17.2 4.8H10.4a3.6 3.6 0 0 0 0 7.2h3.2a3.6 3.6 0 0 1 0 7.2H6.8" fill="none" stroke="#d0d0d0" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+ <circle cx="17.6" cy="4.8" r="3" fill="#22c55e"/>
+ <circle cx="6.4" cy="19.2" r="3" fill="#f5f5f5"/>
+</svg>
diff --git a/docs/logo-light.svg b/docs/logo-light.svg
new file mode 100644
index 0000000..56a5c90
--- /dev/null
+++ b/docs/logo-light.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="96" height="96">
+ <!-- SITREP's mark for light pages: an S drawn as one line between two stations, the far one working. -->
+ <path d="M17.2 4.8H10.4a3.6 3.6 0 0 0 0 7.2h3.2a3.6 3.6 0 0 1 0 7.2H6.8" fill="none" stroke="#383838" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+ <circle cx="17.6" cy="4.8" r="3" fill="#009741"/>
+ <circle cx="6.4" cy="19.2" r="3" fill="#111111"/>
+</svg>