serenity
One calm map for your Claude Code sessions.
Every session is a node on a mind map around one master agent.
Working agents stay quiet. Waiting agents call you. The master keeps the overview.
Website · Install · How it works · Keys · Configuration · Usage and cost · Docs
Why serenity
It starts with one Claude session. Then there are six, spread across tmux windows, worktrees and PRs, and you spend your day tabbing between them to find the one that is waiting on you.
serenity puts them all on one keyboard-driven map in your terminal:
- Harmony instead of clutter. Every Claude Code session is a node, grouped into topics the master picks for you.
- Focus instead of distraction. Working agents stay grey and quiet. An agent that needs an answer turns yellow and moves to the top.
- Clarity instead of noise. The master agent summarises every session, suggests the next step, and acts on it when you press
y.
serenity runs on your existing Claude Code login and subscription (what it uses).
[!NOTE]
serenity is in beta. Expect rough edges and changes between releases.
Features
| |
|---|
| Mind map of sessions | Three zoom levels: the map (master in the centre, topics around it), topics (every session as a card with its summary and PR), and session (the real Claude Code pane, untouched). |
| Live status | Sessions report through Claude Code hooks: ◐ waiting, ● working, ✓ finished. Only waiting sessions ask for attention. |
| The master | Haiku writes one-line summaries and groups sessions into topics, Sonnet suggests replies, approvals and cleanups you accept with y / e / n, and an Opus chat (i on the master) can see and steer everything, start new sessions from a brief, and relay to any session you tag with @name, condensing its answer when you asked a question. |
| Pull requests | Each card shows its PR and checks via gh. o opens it, ready PRs get a review request from CODEOWNERS, and a merged PR finishes the session. |
| Safe cleanup | Removing a session checks for uncommitted changes, unpushed commits and PR state before it touches a worktree. |
| Worktrees | New sessions get their own git worktree beside the repo, or reuse an existing branch. |
| Import | Claude sessions you already run in tmux join the map with I and stay in their windows. |
| Pinned sessions | p pins a session you reuse: it is never marked finished or cleaned up, and resumes with claude --resume when you attach after it ended. |
| Slack (optional) | Mentions and DMs that need you to act, at most three, join NEEDS YOU. The master proposes a follow-up from your sessions and PRs: a reply, a message to the session it is about, or a new session. y runs it, Enter marks it seen and opens it, x dismisses it. Messages you have written after on Slack drop out. |
Install
Requirements: macOS or Linux, Claude Code logged in with a Claude subscription (Pro or Max, or a Team or Enterprise seat) or an Anthropic Console account, tmux 3.2+, git, and gh logged in (gh auth login). The install script installs tmux, git, gh and Claude Code if they are missing; logging in is up to you.
curl -fsSL https://raw.githubusercontent.com/mukkund1996/serenity/main/scripts/install.sh | sh
Or with Homebrew (tmux, git and gh come as dependencies):
brew install mukkund1996/tap/serenity
[!TIP]
If you don't have Claude Code yet, install it first with brew install --cask claude-code. Skip this if you already installed it with npm or Anthropic's installer, or you end up with two copies.
The install script reads these environment variables:
| Variable | Default | Effect |
|---|
SERENITY_VERSION | latest release | Install a specific version |
SERENITY_INSTALL_DIR | ~/.local/bin | Where the binary goes |
SERENITY_NO_DEPS | unset | Set to 1 to skip installing dependencies |
Install the skill
New to running several sessions? The free parallel-sessions skill gives Claude a worktree per task, safety checks before cleanup and short handover notes, with or without serenity:
/plugin marketplace add mukkund1996/serenity
/plugin install parallel-sessions@serenity
For claude.ai, build the upload zip with bun run package:skill (details).
Quick start
gh auth login # optional: PR status on cards (without it, cards say why)
cd ~/your/repo
serenity # opens the map for this repo
serenity doctor checks your setup. Press N to start a session, ? for the full keymap.
| Command | What it does |
|---|
serenity | Open the map for the git repo you are in |
serenity doctor | Check tmux, claude, git and gh |
serenity slack login | Sign in to Slack for the master (once) |
serenity restart | Restart the background daemon (sessions keep running) |
serenity stop | Stop the background daemon |
serenity version | Print the version |
How it works
┌────────────── serenity TUI (Ink) ──────────────┐
you ── keys ─▶│ map › topics › session │
└───────────────────────┬────────────────────────┘
│ JSON-RPC over a socket
┌───────────────────────▼────────────────────────┐
│ daemon SQLite state · master (Haiku/Sonnet/ │
│ Opus via Claude Code) · gh · Slack │
└───────┬───────────────────────────────┬────────┘
│ tmux panes │ hooks
┌───────▼───────┐ ┌───────────────┐ │
│ claude (wt 1) │ │ claude (wt 2) │ ◀──┘ status
└───────────────┘ └───────────────┘
- Each session is a real
claude process in its own tmux pane, usually in its own git worktree. Attaching shows you that pane as it is.
- A background daemon owns the state (SQLite), receives status from Claude Code hooks, polls PRs through
gh, and runs the master.
- The master proposes actions through MCP; nothing runs until you approve it.
- One map per repo: serenity is scoped to the repo you launch it in.
The reasoning behind each of these choices is in the architecture decision records.
Keys
serenity is keyboard-only. The footer shows the moves; ? opens the full list.
| Key | Action |
|---|
← ↑ ↓ → / WASD | Move between nodes |
Enter | Attach to a session, or go into the master; on a NEEDS YOU item, mark it seen (a Slack item is also opened; a session waiting on you is attached instead) |
i | Send the focused session a quick message; on the master, open its chat input (@ tags a session, Shift+Enter or Ctrl+J starts a new line, Esc closes it) |
Ctrl+q | Back to the map from inside a session |
z / Z / Esc | Zoom out to the map / zoom in / one level up |
Ctrl+w | Focus the master from anywhere |
PgUp PgDn | On the master, scroll its conversation back and on (Shift+↑ Shift+↓ too) |
← → Home End | In a text field, move the cursor; Option+← → by a word. Ctrl+a e u k and Option+Backspace edit as in a shell |
Tab | Jump to the next session that needs you |
y e n | Approve, edit or decline the master's suggestion |
[ ] | Previous / next topic |
N I | New session · import from tmux |
o f p | Open the PR · watch · pin |
r K x | Rename · kill the agent · clean up; on a Slack item, x dismisses it |
/ c H | Search sessions · centre on the master · archived sessions |
Configuration
Config lives in ~/.config/serenity/config.json. Every field is optional.
{
"models": { "chat": "opus", "summarizer": "haiku", "suggester": "sonnet" },
"reviewers": ["teammate-login"],
"maxTopics": 10,
"slack": { "repos": ["~/projects/serenity"] },
"crashReports": { "enabled": true }
}
| Field | Default | Meaning |
|---|
models | Opus / Haiku / Sonnet | Models for the master's chat, summaries and suggestions |
reviewers | none | Who to suggest for review when CODEOWNERS names nobody |
maxTopics | 10 | How many topics the master groups sessions into |
slack.repos | none | Repos whose maps show Slack mentions and DMs that need you (ADR 0023, 0024, 0031, 0034, 0050); run serenity slack login once |
crashReports.enabled | false | File daemon crashes as GitHub issues through your gh, scrubbed of paths, tokens and emails, one issue per crash signature (ADR 0045). Reports are always kept in crash-reports/ in the state directory |
crashReports.repo | mukkund1996/serenity | Where crash issues go |
Model names are anything claude --model accepts (an alias like sonnet or a full model id). Config is read when the daemon starts, so run serenity restart after changing it.
A supervisor restarts the daemon if it crashes, and it picks up where it left off (ADR 0045). State (SQLite, socket, daemon log, crash reports) lives in ~/.local/state/serenity. Set SERENITY_HOME to use another directory.
Usage and cost
serenity has no API key or model access of its own. Every model call goes through Claude Code with your login, so it counts against your Claude plan's usage limits, or is billed to your Anthropic Console account if that is how Claude Code is logged in. The sessions on the map are ordinary Claude Code sessions and use what they would use anyway; the master's calls come on top:
Role (models.…) | Default | Runs when |
|---|
summarizer | Haiku | A session replies. One short call per reply (a burst of hook events within 1.5 seconds counts once) writes its summary and picks its topic. |
suggester | Sonnet | A session starts waiting on you or finishes, its question changes, or its PR merges. One call proposes the next step for y / e / n. |
chat | Opus | The master's chat gets a message: one you send with i, or serenity's note that a session you asked it to watch has finished. It does nothing between messages. |
Slack (off by default) adds calls only while the map of a repo in slack.repos is open: the summarizer model reads your mentions and DMs once a minute and when you open the map, the suggester model proposes a follow-up for each new item (and again when a session you told about it answers), and the summarizer model posts a reply or shares a file you approved.
Status, PRs, cleanup and the map itself use no model. To use smaller models, set them in ~/.config/serenity/config.json and run serenity restart; fields you leave out keep their defaults:
{ "models": { "chat": "sonnet", "summarizer": "haiku", "suggester": "haiku" } }
Development
serenity is TypeScript on Bun with an Ink TUI, split into packages/core, daemon, tui and cli.
bun install
bun dev # run from source with its own state and tmux server
bun run install:local # build and install to ~/.local/bin for daily use
| Command | What it does |
|---|
bun run test | Unit and contract tests |
bun run test:e2e | End-to-end in a private tmux server with a fake claude |
bun run lint / bun run format | Biome |
bun run typecheck | TypeScript |
bun run build | Single binary at dist/serenity |
bun run install:local | Build, install to ~/.local/bin/serenity, restart the daemon |
bun dev … | The CLI from source, isolated state and tmux server |
A new build replaces a running daemon by itself.
Further reading: decision records · screen specs · dogfooding notes · website source · changelog
Releases: merging the release-please PR on main tags a version; the release workflow attaches the binaries and bumps the Homebrew tap (ADR 0025).
Contributing
See CONTRIBUTING.md for setup, checks, ADRs and pull requests. Ask questions and share ideas in Discussions. Report bugs as issues.
License
MIT. serenity is an independent open-source project, not affiliated with or endorsed by Anthropic, Slack or Microsoft.
