Session Kit: a numbered picker for Claude Code and Codex sessions

The problem Session Kit was written to solve

Keeping a long-running agent session alive across a closed terminal is a solved problem. shpool already does that, and Session Kit depends on it rather than replacing it. The unsolved part is recognition. Once you have six or seven sessions attached to a multiplexer, you no longer know which one asked a question ten minutes ago, which one finished, and which one has been sitting idle since you started it. The README states the author's own version of this: keeping sessions alive was the easy part, remembering which one was doing what was not.

The target user is narrow and specific. The README says plainly that if you usually keep one or two sessions going, you probably do not need this yet. The people who do need it run several Claude Code and Codex sessions at once, often on a remote host reached over SSH, and want a single screen that answers one question: which session needs me next. Session Kit is that screen. It is a per-user tool installed on the machine where the work actually runs, not on the laptop you type from.

What the picker shows and how a session is identified

Running kit opens a list. Each row carries a number, a name, a provider (Claude Code or Codex), an account, a model, a state, and a last-activity time. The README screenshot description groups rows under headings such as Ready and Open elsewhere. The states named in the README are question, needs you, working, and idle, which is the whole triage vocabulary. You read the list, find the row that says question, and type its number.

Two properties of that numbering matter. The number is stable, so it does not move under you between one look and the next. The name and colour also follow the session, so the window you land in is visually the same session you picked from the list. Sessions are grouped by provider in one menu rather than split across two tools.

The README is explicit that the picker is a view and nothing more. It is never treated as evidence of which live session an action should affect. That sentence is the design thesis, and the next section is where it becomes concrete.

The safety model: re-proving identity before touching a live session

Before Session Kit changes a live session, it re-proves that the session is still the exact provider conversation and the exact process it expects. If it cannot prove that, it refuses rather than guessing. The README calls this the whole design.

That is an unusually conservative posture for a session manager, and it is the right one given what these sessions are. A Claude Code or Codex session holds conversation state that is expensive to reconstruct and a process that may be mid-edit. Acting on the wrong one is worse than doing nothing. The practical consequence is that some actions will be declined even when the picker row looks correct to you. The README instructs you not to work around a refusal, and says Session Kit prints the reason and the remedy it expects.

What the material does not say is how the identity check is implemented, what it compares, or how it handles a session whose provider process was restarted underneath it. That is a gap worth knowing about before you rely on the refusal behaviour. You can observe it, but you cannot currently read the mechanism from the README.

Installing it: checksum, provenance, preflight, doctor

Session Kit installs per user, on the Linux or macOS machine where the work runs. There is no fixed download URL, because release artifacts are named by the exact commit they were built from. The README's own install route asks the GitHub releases API which assets belong to the latest release, downloads them, verifies the .sha256 file with sha256sum or shasum -a 256, unpacks the tarball, then runs the installer in two passes:

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

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

The --check pass is read-only. The README says not to bypass a refusal and that the remedy is printed for you. The doctor command is run twice, once before enabling services and once after, so you can see what changed. There is also a paste-ready prompt for handing the whole sequence to an already-open Claude Code or Codex session, which tells the agent to use the latest release artifact rather than a clone of main and to verify the checksum before extracting.

Requirements are worth reading before you start. You need shpool 0.11.0, the stock build. The patches under shpool-patch/ are explicitly not needed to install or start using it, and the README says that decision can wait. You need Claude Code, Codex, or both, and 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 needs 14 or newer, an active desktop login for the per-user launchd GUI domain, Homebrew Bash 4+, and Python 3.11+.

Accounts, delegated work, and what stays on the host

Two features go beyond the picker. The first is per-session accounts: the subscription belongs to the session, not to the terminal that launched it, so you can run different accounts side by side. The second is delegated work. A machine-origin session gets its own git worktree on its own branch, and hands that worktree back when the session closes. If you have ever had an agent commit onto the branch you were actively editing, the shape of that feature will make sense immediately.

The isolation claim is limited to the local host. Session Kit has no hosted account, no analytics, no telemetry, and no update beacon, according to the README. It talks to no server of the author's. That is a meaningful difference from session managers that sync state through a cloud service, and it also means there is no cross-machine view: if you work from two laptops, each sees only the host it connects to.

Where it is the wrong tool, and what to use instead

The clearest limitation is stated by the author rather than discovered by a reviewer: if you keep one or two sessions going, you do not need this. Installing a per-user service, a shpool dependency, and a Python 3.10+ or 3.11+ runtime to manage two sessions is not a good trade.

The second limitation is platform and privilege. Linux needs a readable /proc and a systemd user manager. macOS needs an active desktop login for the per-user launchd GUI domain, which rules out a headless Mac you only reach over SSH unless someone is logged in at the console. If you cannot run a per-user service on the host, Session Kit will not install usefully.

The third is maturity. This is a public beta at v0.4.3, with v0.4.1 labelled a superseded beta and v0.4.2 and v0.4.3 landing a day apart. The author says the beta moves quickly and to expect to update.

For a real alternative, consider tmux with a session-per-project naming convention and its own choose-tree picker. The difference in approach is fundamental. tmux gives you a stable, widely packaged multiplexer and nothing above it: you name sessions yourself, you decide which window matters, and there is no notion of a session state, no provider awareness, and no identity re-check before an action. Session Kit adds exactly that layer, the triage states and the refusal behaviour, at the cost of a Python application, a shpool dependency, and a beta that changes often. If your problem is purely persistence, tmux is the smaller answer. If your problem is knowing which of seven sessions to open, tmux does not address it.

Maintenance cost and licence terms

The upgrade path is a release-artifact download rather than a package manager, so each update repeats the same sequence: fetch the assets for the new release, check the .sha256, unpack, run the installer, then run session-kit doctor. Because artifacts are named by commit, any script you write around installation has to query the releases API rather than hardcode a URL. That is a small but real ongoing cost, and it is the price of the commit-named artifact scheme.

Session Kit is MIT licensed. In practical terms that permits use, modification, and redistribution provided the copyright notice and permission notice are preserved, and it comes with no warranty. This is not legal advice; read the LICENSE file in the repository if the terms matter to your organisation. Note that the MIT licence covers Session Kit itself, not shpool, Claude Code, or Codex, each of which carries its own terms.

On support: there is no company behind the project, no paid tier, and nothing to buy. The README describes it as a passion project maintained by someone who uses it daily. That is a reasonable predictor of attention and a poor predictor of response time when something breaks on your machine.

Editorial conclusion

Adopt Session Kit if you routinely run more than a handful of Claude Code or Codex sessions on one Linux or macOS host, especially over SSH, and you are comfortable installing a public beta that moves quickly. Do not adopt it if you keep one or two sessions going, if you need a stable pinned version with long support windows, or if you cannot grant a per-user systemd or launchd service. Before trusting it with live work, verify three things on your own machine: that shpool 0.11.0 is the stock build and resolves correctly, that session-kit doctor returns clean both before and after session-kit services enable, and that the release you downloaded carries a .sha256 and .provenance.json that match the artifact you unpacked.

Official sources

1. dob323/session-kit on GitHub
2. Issues
3. License: MIT
4. README
5. Releases