Susan

Susan keeps a board of every Claude Code session you have open, so the work in the window you cannot see is not work you have forgotten.

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. Susan sits between them: she knows who is working where, tells your agent when two sessions are about to edit the same file, and keeps a list of work that outlives any single conversation.

Two promises hold the whole design together:

She never writes to a file in your projects. Not from a hook, not ever. Exporting to markdown is a command you run by hand.

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.

Related MCP server: session-coord-mcp

What she does

The card, at five sessions

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

The conflict sits above every session row, because it is the only line that changes what you do next. The card is capped at ten lines no matter how many sessions are running.

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 todo add "thing"       record work that outlives this session
/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
susan watch              # the board, live — ctrl-c to close
susan serve              # the board in a browser, with tickable todos
susan serve --lan        # ...also reachable from your phone on the same wifi
susan statusline         # one line, for a status bar

susan todo               # open todos for this project
susan todo add "thing"   # record work that outlives this session
susan todo export        # write them under a marker in TODO.md
susan todo import        # read hand-edits back out of it

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 todos and queue
susan doctor             # diagnose

The MCP tools

Registered as susan when you run susan init.

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

susan_todo_add deliberately says "only for work that outlives this conversation" in its own description. Without that line an agent uses it and the built-in TodoWrite interchangeably, and the board fills with this-turn noise.

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, plus the thing a terminal cannot do: todos have checkboxes. Tick one off, add one, finish or drop a queued task. 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.

• It cannot claim queued work. Claiming decides which session does a job, and that belongs to the session whose agent will actually do it — not to a browser tab with no context. Tick it done, or drop it; do not assign it.

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

What she touches

~/.claude/susan/susan.db        the board — sessions, todos, queue, messages
~/.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

MIT.