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.

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

She keeps the distillate, never the raw. Claude Code deletes your transcripts after about thirty days, so a pure view would go dark with them. Susan keeps the plans — measured at 0.002% of the transcripts she read, with a test that fails the build above 0.5%. Run susan doctor to see the live number on your own machine.

Nothing leaves your machine. The one exception is a daily ping — a random id, the version, and a count of live sessions — which is off unless you turn it on, and susan ping prints the exact payload before you decide.

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  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 connect            # a url + token, for chatgpt web and claude web
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 memory <words>     # what was decided, from sessions that no longer exist
susan memory --distill   # build it: shows the cost, waits for a keystroke
susan memory --status    # how many memories, and what is queued

susan agent create sales ~/plans/campaign-a ~/plans/campaign-b
susan agent list         # every domain agent, its folders and history
susan agent refresh sales
susan agent remove sales

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

Memory, after the transcript is gone

Claude Code keeps your session transcripts for about thirty days, then deletes them. Susan reads what a session decided before that happens and keeps the decision — a sentence, the quote it came from, and where to find it.

susan memory --distill          # ~$0.035 of plan quota per session, ~20s each
susan memory "retry wrapper"

No custom retry wrapper was added because the SDK already retries 429s. "The SDK already retries 429s with backoff internally" susan · ~/.claude/projects/-Users-d-projects-susan/a1b2.jsonl:284119

It uses the Claude Code subscription you already pay for. Not an API key, not a second bill — claude -p on your own plan. Susan never handles a credential.

It is asked, never volunteered. Nothing is injected into a session. A memory you have to ask for is a wrong answer you can check; a memory pushed into every session start is a wrong answer acted on everywhere, forever. Pull is what the numbers currently justify.

Scored before it shipped, on hand-labelled sessions: npm run eval reports precision and recall separately and refuses to pass below 0.95 precision. A memory layer that is 90% right is worse than none, because you stop being able to tell which 10% is wrong.

Domain agents — @sales, without the retyping

Every sales conversation used to start the same way: paste the campaign context, explain the offer, again. susan agent ends that. Name a domain, point at the folders that hold it, and Susan generates a Claude Code agent that opens already knowing them:

susan agent create sales ~/projects/acme/plans/dubai-campaign ~/projects/acme/plans/fly91-outreach

Type @sales in any new session and the agent reads the right entry document fresh (STATUS.md beats plan.md beats README.md), pulls every decision past sales sessions produced, and treats any "never"/"only" line in your documents as binding.

Three things keep it honest:

• The agent file is a router, never a copy. It points at your folders; it quotes nothing. Your documents stay the single source of truth and cannot go stale inside the agent.

• Its memory is scoped, not duplicated. Sessions that invoke @sales — or that edited files under its folders — are the domain's history, and their distilled decisions are what @sales remembers. One memories table, one budget, no second store.

• It leaves the way it came. susan agent remove and susan uninstall delete exactly the files Susan generated. An agent file you wrote or rewrote yourself is never touched.

Which tools she can read

There are two ways in, and which one a tool uses depends on one thing: does it run on this machine, or in a browser?

The web clients are not read; they ask. Neither writes anything to your disk, so there is nothing on disk to read — which is why the answer is a connection rather than a parser. She cannot see what you typed into ChatGPT. ChatGPT can see your board.

susan connect — for the tools with no filesystem

Claude Code, Cursor and Codex all run here and start Susan themselves; they need nothing from this section. ChatGPT on the web and Claude on the web cannot spawn a process, so for them she has to be a URL.

susan connect            # read-only, bound to this machine, token required
susan connect --write    # also allow queueing tasks and leaving notes
susan connect --port=5000
susan connect token      # print the token again

She prints a URL and a bearer token. Give both to the client as an MCP server.

A URL on your laptop is not reachable from the web. Both web clients call the URL from their servers, not from the browser tab, so 127.0.0.1 will never resolve for them however correct the config looks — the failure is silent, an empty tool list with no error. Put a tunnel in front of it and hand over the tunnel address:

cloudflared tunnel --url http://127.0.0.1:4949

What guards it, since this is the one place Susan opens a port:

She never exposes your files this way. The tools return the board, plans, search and memory — the same things any other MCP client sees, and nothing more.

The MCP tools

Registered as susan when you run susan init.

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

The same tools are what a remote client sees over susan connect, minus the three writes unless you passed --write.

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

susan init already started it, and it comes back after a restart — there is no terminal to leave open and nothing to remember. susan serve above is for running it in the foreground when you want to watch it start.

susan serve --install     # keep it up (init does this for you)
susan serve --uninstall   # stop it, and stop it starting on its own
susan doctor              # says whether the board is answering

Behind it is a launchd agent that starts at login and restarts the board if it stops. susan uninstall removes it along with everything else.

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.

Reading the board from somewhere else

GET /api/board is what the page itself reads, and anything else may read it too.

{
  "sessions": [
    {
      "id": "ba802d5a-…",
      "name": "arkone-ai/4",
      "project": "arkone-ai",
      "branch": "arkone_ai_dev",
      "subject": "where are the ICPs?",
      "files": 23,
      "recent_files": ["…/core/store.mjs", "…/bin/mimi.mjs"],
      "idle_ms": 24869,
      "idle": "24s",
      "last_activity": 1786169782995,
      "stale": false,
      "plan": {
        "done": 5,
        "total": 6,
        "items": [{ "content": "…", "status": "completed" }]
      }
    }
  ],
  "queue": []
}

Two names are worth stating plainly, because both have an obvious wrong guess:

subject is the session's opening prompt and does not change mid-session. A long session drifts far from what it was first asked; plan is what tracks the present. A board that looks stale in the header while the plan below it moves is Susan working correctly, not caching.

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, 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>
~/.claude/agents/<name>.md      only if you ran `susan agent create <name>`

Nothing is written anywhere else. No daemon, and no network of her own.

She opens a port only while you are standing in front of one: susan serve for the browser board, susan connect for a web client. Both stop when you close the terminal, and neither survives a reboot. There is nothing running when you have not asked for it.

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        # 176 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.