dob323/session-kit: session Kit is a local picker for Claude Code and Codex

Many AI coding sessions. One place to see which one needs you.

Session Kit is a local picker for Claude Code and Codex. Type kit and every session you are running is in one list, each with a stable number, a name, and a state word that says whether it is waiting on you or still working. The sessions run on the host, so closing the terminal or dropping SSH does not end them.

One limit, stated up front rather than in a table further down: Claude Code reports a blocking prompt the moment it opens one, so question is exact. Codex does not expose that yet, so a Codex session reads needs you when its turn ends rather than the instant it asks you something.

What is on the screen is not what gets trusted. The number, the name, the directory, the timestamps: all of that is display. Identity is the provider's conversation UUID together with the exact process generation, and every action that changes anything re-proves that against the live system in the moment before it runs, then refuses outright on evidence that is missing, stale, partial or contradictory. This is the part worth caring about: a picker one second out of date still cannot act on the wrong session, because the picker was never the evidence.

Every session names itself. It takes a short title from its own first piece of work, keeps a number that does not move, and gets a colour of its own. All three follow the session into its own window. The tab title carries the name and number, and the session is tinted its colour in Claude Code and Codex themselves. So the window you are typing in tells you which session it is, and the picker and the session never disagree about it. Colours are kept distinct from the other live sessions: eight for Claude Code, six for Codex, chosen so no Claude session can ever share a colour with a Codex one.

Every session can use a different subscription. Enrol several accounts for the same provider and hand each session whichever one you want: three Claude Code subscriptions running in three sessions side by side on one machine, at the same time. The account belongs to the session, not to the machine or to the terminal you launched from, which is the usual arrangement elsewhere.

Install · The picker · Safety model · Accounts · Delegated work · How it works · Documentation

Public beta, v0.4.2. Linux with systemd, or macOS 14 and newer.

Settled: the picker, session identity and the guards around every action, install, update and rollback, and the Claude Code and Codex integrations. Around 2,700 tests run on both platforms for every change.

Not settled: the beta moves quickly, thirteen releases in its first three weeks, so expect to update. Codex does not report a blocking prompt yet.

What is promised: this is a tool its author uses daily and publishes; it is not a supported product. Replies are best-effort, security fixes go into the current release with no dated windows and no back-ports, and nothing here is a security boundary against another process already running as your Unix user. Start on a single trusted Unix account where provider conversations can be recovered.

What you get

Is this for you?

It fits best if you run several AI coding sessions at once, work on a remote host over SSH, and want to know at a glance which session is blocked on you rather than opening each one to find out.

Here is what it does not do:

• No diff review. It will not show you what a session changed. That stays in git and your editor.
• No cost or spend accounting. It can read the provider's own quota percentages and tell you when one runs out, but it does not price or count tokens.
• Not a multiplexer. It runs on shpool and does not replace tmux, or try to.
• Not a security boundary. It protects you from acting on the wrong session, not from a hostile process running as you.

If what you actually need is reviewing the diff each agent produced, a different tool will serve you better.

Why not tmux, or one of the other session managers?

tmux is already on your machine and keeps processes alive, which is most of the way there. What it does not do is tell you which of eleven panes is waiting on an answer, and it has no notion of which conversation a pane holds, so nothing stops you acting on the pane next to the one you meant. If you are running two sessions, tmux is enough and this is overkill.

The other AI session managers solve the listing problem, and several are pleasant. The difference is what they do with the list: they act on it. Here the list is treated as a cache that can be a second out of date, and identity is re-proved against the live system before anything is changed. That distinction only matters when you have enough sessions that the list can be wrong, which is also the point where you start needing this.

What it costs you: this runs on shpool rather than tmux, so there is one more thing to install before you see anything. That was a deliberate trade: shpool gives a clean session per shell without fighting multiplexer semantics, which is what makes a session's identity provable at all. It is a real cost, and it is paid before you get to the payoff.

Install

Session Kit installs per user, on the Linux or macOS machine where the work runs.

Artifacts are named by the exact commit they were built from, so there is no fixed download URL. This asks the release API which files belong to the current release, checks what arrived, and only then unpacks it. It needs nothing but Python 3 and tar, both of which the install needs anyway.

mkdir session-kit-download
cd session-kit-download

python3 - <<'PY'
import json, urllib.request
url = "https://api.github.com/repos/dob323/session-kit/releases/latest"
with urllib.request.urlopen(url) as response:
    release = json.load(response)
for asset in release["assets"]:
    urllib.request.urlretrieve(asset["browser_download_url"], asset["name"])
    print("downloaded", asset["name"])
PY

if command -v sha256sum >/dev/null; then
  sha256sum --check session-kit-*.sha256
else
  shasum -a 256 --check session-kit-*.sha256
fi

tar -xzf session-kit-*.tar.gz
cd session-kit-*/

./install.sh --check
./install.sh

session-kit doctor
session-kit services enable
session-kit doctor

./install.sh --check is read-only. Do not work around a refusal. Session Kit prints the reason and the remedy it expects.

Requirements

• shpool 0.11.0, the stock build. The optional patches in shpool-patch/ are not needed to install or to start using this; that decision can wait until something makes you want them
• Claude Code, Codex, or both
• one trusted Unix account, with per-user service access

Linux additionally needs a readable /proc, a systemd user manager, Bash 4+, and Python 3.10+. macOS additionally needs macOS 14+, an active desktop login for the per-user launchd GUI domain, Homebrew Bash 4+, and Python 3.11+.

Prefer the GitHub CLI, installing without a network path to the API, or checking the provenance file by hand? Install Session Kit has every route, plus supported shpool paths, provider setup, project import, and activation.

Installing with an AI assistant

If Claude Code, Codex, or another terminal agent is doing the installation, give it this:

Install Session Kit from https://github.com/dob323/session-kit. Use the latest release artifact, not a clone of main. Download the release archive with its .sha256 and .provenance.json files, verify the checksum, extract it, and run ./install.sh --check first. Fix only the remedies that preflight explicitly names. Then run ./install.sh, session-kit doctor, session-kit services enable, and session-kit doctor again. Never bypass a refused step. Show me the final doctor output and finish by telling me to type kit.

First run

kit

New session defaults to Claude Code. A session can also be started directly:

sp new claude
sp new codex

Project aliases, provider choice, account selection, and configured models make those launches more specific. See Projects and Use Session Kit.

The picker

Ready sessions come first. Sessions already attached to another window appear under Open elsewhere. Within a group, attention state determines the first part of the order, followed by provider and activity.

The state words are deliberately small and literal:

Pressing a narrows the list to just those sessions, with how long each has waited.

The home screen keeps the common actions one key away:

A session that is open elsewhere defaults to Move it here after a fresh identity check. The earlier window returns to its picker, and the provider conversation is not duplicated.

Press ? for the full key reference: filtering, ranges, grouping, forking, renaming, and g to jump to the next session that needs you are all there. See Picker navigation for the cursor-driven picker, mouse behavior, action panels, machine sessions, and closed-session restore.

Safety model

Session Kit deliberately separates what you see from what it trusts.

1. Provider UUID plus exact process generation is identity.
2. Session number, title, directory, timestamps, and terminal output are display context.
3. Every mutation rechecks live identity immediately before it runs.
4. Missing, stale, partial, duplicated, or conflicting evidence fails closed.
5. A refusal changes nothing.

Before a proof-bound action, Session Kit can bind and recheck the session manager, terminal generation, managed shell, provider process and ancestry, exact provider conversation UUID, and frozen snapshot generation. The proof is owner-only and short-lived.

This protects against stale or ambiguous picker state selecting a different session than the one you intended. It does not isolate mutually hostile processes running with your own Unix-user privileges.

Read Security and local data and Architecture for the complete trust model.

Accounts and subscriptions

One machine, several logins for the same provider, one per session. Enrol each account once and it becomes a choice at launch:

sp account enroll claude work you@example.com
sp account list claude

Each enrolled account keeps its own provider configuration directory, so a session started on it authenticates as that account and no other. Three Claude Code subscriptions can be running in three sessions at the same moment, and the picker shows which account each session belongs to, the personal and work column in the screenshot above.

This is the part most session tools do not do. A terminal multiplexer inherits whichever login the shell that started it happened to have, so every window shares one subscription. Here the account is a property of the session.

Provider authentication stays in provider-owned storage throughout. Each session launches the provider's own binary against its own configuration directory. Session Kit does not ask for, copy, print, or log provider tokens, and it does not put a subscription token into any harness of its own.

Carrying a conversation to another account

There is a mechanism that can move one idle conversation to another enrolled account when its weekly quota runs out. It is off, and it stays off until you turn it on. The watchdog runs in report mode by default and only says what it would do; automatic changes require setting SESSION_KIT_WATCHDOG_MODE=repair deliberately.

Leave it off unless you have a reason. Owning several subscriptions and using each for your own work is ordinary use. Moving work between accounts because a limit was reached is a different shape, and it is the shape providers look for when they enforce against limit evasion, and the consequence lands on your account, not on this tool. sp account-auto-switch <session> shows you what would happen without doing it.

Read Configure Session Kit for enrolment, verification, and the carry-over rules in full.

Delegated work

A session started as machine-origin is given its own git worktree, on a branch the kit cuts for it, so two workers on one repository never edit the same files. Any session can ask for one by branch:

sp new claude --worktree <branch>

Closing the session gives the copy back, and every close does it: sp close, the picker's k, bye or a clean provider exit, and the scheduled cleanup pass. The copy is kept instead, with the reason named out loud, whenever giving it back could lose work: uncommitted, staged or untracked files, ignored files that were created there, a commit not yet in the reference, somebody still working in the directory, or a check that could not run at all.

A directory that is not a git repository has nothing to isolate, and a person's own session is never moved out of the directory they chose. See Use Session Kit for the complete rules.

How it works

Install Session Kit where the work actually runs.

• On a local workstation, sessions survive closing the terminal window.
• On a remote host, they also survive the SSH client disconnecting.
• The laptop you connect from can sleep, disconnect, or shut down.
• The host must stay powered on and awake for the processes to keep running.
• A host reboot ends them. Recoverable Claude Code and Codex conversations remain available through Closed sessions.

There is no Session Kit server to deploy.

Claude Code and Codex

Session Kit does not replace either provider.

For Claude Code, it can supply the installed status line, session name and color integration, exact conversation identity, account profiles, guarded resume behavior, and optional attention evidence.

For Codex, it leaves the Codex status bar under Codex control, and supplies per-launch terminal-title items and the session theme without editing ~/.codex/config.toml.

Read Claude Code and Codex integration for the exact contracts.

Local data and privacy

No hosted service, no Session Kit account, no analytics, no update beacon, no telemetry.

By default:

• terminal journals are off;
• external notifications are off;
• provider transcripts stay in provider-owned storage;
• the picker action log stores fixed action and outcome labels, not terminal contents;
• private Session Kit state is owner-only and is never uploaded.

Optional history can contain prompts, source code, command output, credentials, and other sensitive terminal content. Read Security and local data before enabling it.

Running it

session-kit doctor      # what is installed, what is wrong, and what to do
sp help                 # every command, with exit codes and selectors

doctor is the first thing to run when anything looks wrong. Updates install an immutable local release and move current atomically; rollback selects a verified release already on the machine. Read Update and roll back before changing releases, Configure Session Kit for colour, terminal titles and every setting, and Troubleshooting when doctor names something you have not met.

Session Kit runs on shpool and neither vendors nor replaces it. The repository carries optional shpool patches with their scope and checks; doctor records the shpool binary validated at installation and reports when it later changes. Read shpool-patch/ before choosing a patched binary.

Documentation

Documentation index, every document grouped by what you are trying to do.

The ones people reach for first: