session management

session-management

A long Claude Code session starts things everywhere — background agents, other panes and workspaces, PRs, tickets, temp files, a promise to reply to someone. Halfway through you lose track of what is still running and what is waiting on you; at the end you close the window and something falls through the cracks.

Three slash commands cover the life of a session: a recap in the middle, a resume check after the Mac slept or the network/account changed, and a close-out before you stop that closes the session when you say close.

Setup

/plugin marketplace add roypadina/padina-claude-code-plugins
/plugin install session-management@padina

Requires nothing. Used when present:

• jq — the close finds its own pane with it.
• agentctl — the close marks the session done.
• cmux — the close closes the pane the session runs in.

What you get

Command	When	What it does
/session-recap [focus]	Mid-session	Where are we, what is in flight and where, and what you owe
/resume-all [what happened]	After sleep, a network change (Wi-Fi ⇄ LAN, VPN) or an account switch	Finds what the disruption stopped and restarts it exactly as it was — no plan changes — then carries on
/finish-session [cleanup] [close] [force] [notes]	Before you stop	Every open, un-done, un-cleaned or owed item, with a proposed action each — then close closes the session

Plain slash commands plus a few scripts, and one hook: a UserPromptSubmit hook that, when your whole reply is a close (close, close it, 1,3 then close — not close the PR), hands Claude the close steps again, so close works even after /compact. For every other prompt it prints nothing. The full name works too: /session-management:session-recap.

Both are read-only until you approve an action, and every rule in your own CLAUDE.md and memory still applies. They check real state (git, gh, the task list, harness notifications) instead of trusting the conversation's memory of it, and they only look at what this session started or touched — never other sessions' work.

/session-recap

A mid-session orientation. It gathers, reports and stops — nothing is stopped, cleaned, pushed, posted or messaged, and it does not resume work in the same turn, so you can redirect. It never pings another agent or session for status; those pings would interrupt them.

Its Running group includes every process the session started that is still alive (scripts/session-procs.sh) — port-forwards, servers, background jobs — not just the ones the conversation remembers.

It opens with three lines, then six groups (empty groups are left out, at most five lines each):

Done: <1–3 lines>
Now: <the step in progress, or "idle — waiting on you">
Then: <what comes after>

Running (n):    started by this session, not yet handled — and how/where it runs
Open (n):       agreed or asked for, not running, not done
Missing:        needed for the goal, but nobody has asked yet
Not planned:    descoped, deferred or rejected — things you might assume are happening
Waiting on:     blocked on something outside both of you, and since when
You:            only what you alone can do, verb first

→ Next: <one concrete action>

Each item lands in exactly one group. A blocker that is you goes under You, not Waiting on.

Running lines say how each thing runs, in a fixed vocabulary: bg agent, bg bash, Monitor, cron / wakeup / loop, workflow, a cmux workspace:N or pane surface:N (with its report-back file, if it has one), or another session. State is one of running, finished — result not handled, blocked: <why>, unknown.

An optional focus argument narrows the middle groups; the header always appears.

/finish-session

The close-out before you stop. It reviews the whole session, checks the real state of everything it touched — task list, git (status, unpushed commits, stashes, branches and worktrees it created), PRs, issue-tracker tickets, background shells and agents, monitors and crons, temp files, lessons not yet saved to memory — and reports on one screen:

Done:
- ...
Open:
1. <item> → <proposed action>
Run which? (all / 1,3 / none) — or "close" to close the session

It acts only on the items you pick, then reports each as done / skipped / failed. Message text (chat, email, comments) is drafted only for the items you pick, and sent only after you approve it.

Closing: say close

Reply close (or 1,3 then close) right after the report and it closes the session. close the PR is an ordinary request, and a bare close anywhere else gets a yes/no question first:

1. Re-checks every item from the report with a real check, not memory. Items you didn't pick count as skipped — you saw the list. It asks only about items marked ! in the report — what the close would kill or orphan: something still running (background shell or agent, port-forward, server, monitor, loop), a lesson not yet saved, an unsent draft, uncommitted work in a worktree the session created. Unpushed commits stay on disk, so they don't block.
2. agentctl done — skipped if agentctl is not installed.
3. Closes this cmux pane (or the workspace, if this pane is its only one) — the last thing it does, since it ends the session. Outside cmux it tells you to close the window yourself.

/finish-session cleanup deletes this session's own leftovers without asking — temp files, test resources, merged local branches it created; never anything under ~/ClaudWork, never what you'd need to resume the session. /finish-session close (alone or with cleanup) closes right after the report, but only if nothing else is open — otherwise it shows the report and waits. /finish-session force (or -f) skips the report and every check.

It never closes someone else's pane. It finds its own pane by $CMUX_SURFACE_ID and then confirms it: that pane's tty must sit on the session's own process chain, so an environment variable leaked from another pane can't aim it elsewhere. It never trusts $CMUX_WORKSPACE_ID (stale once a pane is moved), closes a workspace only when this pane is provably its single surface, and when anything is uncertain it closes nothing and says so. A pinned workspace is never unpinned or closed: if the session is its only pane, a fresh shell takes its place. Just before closing, it tells you exactly what it will close (surface:N in workspace:M "<title>").

Uninstalling

/plugin uninstall session-management@padina

Nothing to clean up — the commands keep no state of their own.