Susan

Susan shows you what every Claude Code session on your machine is working through — its own todo list, live, from outside the window.

You run four sessions across four projects. One is waiting on a test, one is half way through a refactor, one you started an hour ago and cannot remember why.

Claude Code already keeps a todo list inside each session — the steps it is working through. Susan reads those lists and puts them all on one board, so you can see what every window is doing without opening it. She also tells your agent when two sessions are about to edit the same file, and lets one hand work to another.

There is nothing to maintain. Susan writes no todo list of her own; she reads the one your sessions are already keeping.

Two promises hold the whole design together:

She never writes to a file in your projects, or to a transcript. Plans are read, never edited — they belong to the session that wrote them.

She never blocks a tool call. When two sessions touch the same file, both edits proceed. The agents are told; nothing is denied.

---

Install

npm i -g @arkone_ai/susan   # installs two binaries. Touches nothing else.
susan init                  # shows the exact diff, asks once, backs up your settings

Now open two Claude Code sessions in any two projects. The second one's opening card will show the first. That is the whole proof it works.

susan doctor       # check everything is wired
susan uninstall    # undo it — your settings backup is kept

Needs Node 22.5+ (for the built-in node:sqlite, so there is no native module to compile). macOS and Linux. On Windows, run it inside WSL.

---

What she does

Surface	What you get
Session start card	Who else is running, what they are working on, anything queued or unread. Prints nothing at all when you are alone and nothing is pending.
Conflict notice	Edit a file another live session touched in the last 30 minutes and your agent is told to re-read it first. Once per file. Never blocks.
Status line	arkone-ai/1 ●4 sessions ⚠1 conflict ▣3 — the one region of the screen that never scrolls.
susan watch	A live board, redrawing every two seconds. Park it on a second monitor. When nothing is running it shows what you were last doing.
susan serve	The same board in a browser at localhost:4747. --lan makes it reachable from your phone.
susan plans	Every live session's todo list, and full-text search across every plan ever written on this machine.
MCP tools	Your agent can read the board, see what other sessions are working through, search plan history, hand work to another project, and leave notes.

The card, at five sessions

─ susan ── 5 sessions ─────────────────────────────────────────────────────
  ⚠ conflict  hosts.js — arkone-ai/1 · goclaw/1
  ● pharmadesk/1      refactoring the approval route    12m  3/7
  ● goclaw/1          wire the mcp stdio transport      31m  1/4
  ● fzst-claw/1       lead scoring backfill              8m  2/2
  ● arkone-ai/1       fix the content planner filter     4m  0/5
  ▣ 2 queued                                            `susan queue`
───────────────────────────────────────────────────────────────────────────

The conflict sits above every session row, because it is the only line that changes what you do next. 3/7 is how far that session has got through its own plan. The card is capped at ten lines no matter how many sessions are running.

The plans

Claude Code keeps a todo list inside each session — the steps it is working through. Susan reads that list out of the session's transcript and shows it on the board:

  ●  arkone-ai/2         fix the content planner filter        4m
                         src/app/.../ui.js
                         2/6 done
                         ✓ read how the date filter is built
                         ✓ reproduce the timezone bug
                         ▸ correct the boundary comparison
                         · add a test for the DST case
                         +2 more

She never writes to that list. It belongs to the session, and the session's agent is the only thing that changes it — so what you see is what it actually thinks it is doing.

susan plans                    every live session's list
susan plans razorpay webhook   search every plan ever written
susan plans --all              recent plans, including closed sessions

Search covers your whole history. Nine hundred megabytes of transcripts index in about a second and a half, and only newly appended bytes are read after that.

How a session gets its name

Nobody types it. Susan takes the first eight words of the first thing you typed, verbatim. A session that has not been given anything yet reads just started, and once it edits something it reads by filename. There is no (unclaimed).

---

From inside a session

/susan                       the board, without leaving your session
/susan plans                 what every session is working through
/susan plans <words>         search every plan ever written
/susan queue                 what is waiting for this project

susan init installs it at ~/.claude/commands/susan.md. If you already have a susan.md of your own there, she leaves it alone and says so.

---

Commands

susan board              # the board, once — sessions, their plans, conflicts
susan watch              # the board, live — ctrl-c to close
susan serve              # the board in a browser
susan serve --lan        # ...also reachable from your phone on the same wifi
susan statusline         # one line, for a status bar

susan plans              # what every live session is working through
susan plans <words>      # search every plan ever written
susan plans --index      # re-read every transcript from scratch

susan queue push goclaw "regenerate types"    # hand work to another project
susan queue claim 3                           # take it
susan message send pharmadesk "taking hosts.js"

susan reset              # clear stale sessions; keeps plans and queue
susan doctor             # diagnose

---

The MCP tools

Registered as susan when you run susan init.

Tool	Reads/writes	For
susan_board	read	What every other session is doing right now
susan_plans	read	The todo list each other session is working through
susan_plans_search	read	Search every plan ever written — "what was I doing about X"
susan_queue_push	write	Hand a task to a session in another project
susan_queue_list / _claim	read / write	See and take queued work
susan_message_send	write	Leave a short note for another session

Every write is local, additive and reversible. Nothing here needs a confirmation gate.

Your agent keeps using TodoWrite exactly as before. Susan reads that list; she does not ask an agent to keep a second one. There is no susan_todo_add, on purpose — a tool that manages Claude Code should not also be a reminder app.

---

The browser board

susan serve          # http://localhost:4747, this machine only
susan serve --lan    # also on your phone, over the same wifi

Everything susan watch shows — every session's plan, struck through as it completes, in a window you can leave open on a second screen. It updates the instant anything changes, in any session.

Two deliberate limits:

• Loopback by default. A page that can edit your board does not go on the network unless you pass --lan, and when you do, it says plainly that anyone on that network can edit it.
• Plans are read-only here. They belong to the session that wrote them; a browser tab has no business ticking off another session's steps.
• It cannot claim queued work. Claiming decides which session does a job, and that belongs to the session whose agent will actually do it. Finish it, or drop it; do not assign it.

Dropping work is undoable. drop sits apart from done, in its own colour, and offers an Undo for seven seconds after — a confirmation dialog taxes every correct tap, an undo only costs the rare wrong one.

The page loads nothing from the internet — no fonts, no scripts, no analytics — and the server sends a Content-Security-Policy that forbids it from trying.

---

Delegation, not possession

susan_queue_push hands work to another project. The receiving session does not start it on its own — queued work appears on that project's next session card and in the status line count, and the agent picks it up when you ask.

A session that quietly began work you never requested, in a window you were not watching, is exactly the failure this tool exists to prevent.

---

How she stays out of your way

Concern	What actually happens
Nothing else can reach it	The board refuses any request that did not come from its own page — wrong content type, foreign origin, or a rebound hostname all get a 403. A page you visit in another tab cannot touch your board.
Token cost	The conflict check is a shell hook: zero tokens when there is no conflict. The card is at most ten lines, and nothing at all when you are working alone.
Latency	The pre-edit hook's database work measures ~0.3ms. A 50ms circuit breaker guards it: if the board is ever slow, the hook goes quiet rather than making a file write feel sluggish.
Crashed sessions	A session that dies without warning is swept after four hours of no activity. Nothing is ever locked, so a stale row costs you nothing. susan reset clears them now.
Broken hooks	Every hook exits 0 unconditionally, wrapped at the outermost level. A bug in Susan must never break the session she runs inside.
Your settings	susan init backs up settings.json with a timestamp and marks every key it adds. susan uninstall removes exactly those and nothing you wrote yourself.

---

What she touches

~/.claude/susan/susan.db        the board — sessions, plans, queue, messages
~/.claude/projects/**.jsonl     READ ONLY — where the plans come from
~/.claude/settings.json         four hooks, a status line, one MCP server
~/.claude/settings.json.backup-<timestamp>

Nothing is written anywhere else. No daemon, no port, no network.

To see the change before agreeing to it:

susan init --dry-run

---

Development

git clone https://github.com/arkone-ai/susan.git && cd susan
npm install
npm test        # 34 tests, no network, isolated databases
npm link        # put susan + susan-mcp on your PATH from the checkout

Point her at a scratch database while developing, so your real board is never touched:

SUSAN_HOME=/tmp/susan-dev susan board

Variable	Does
SUSAN_HOME	Where the database lives (default ~/.claude/susan)
SUSAN_CLAUDE_DIR	Where settings.json lives (default ~/.claude)
SUSAN_DEBUG	Print hook errors and over-budget warnings instead of failing silently
SUSAN_NO_BELL	Suppress the terminal bell on a conflict

MIT.