Session Kit

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

Session Kit is a local picker for Claude Code, Codex, and shell sessions. Type kit and every session you are running is in one list, 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.

Public beta. v0.4.2 supports Linux with systemd and macOS 14 or newer. Start on a single trusted Unix account where provider conversations can be recovered. Session Kit is not a security boundary against another process already running as the same Unix user.

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

Install

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

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

gh release download --repo dob323/session-kit --pattern 'session-kit-*'

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
• 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+.

For supported shpool paths, provider setup, manual asset download, project import, and activation, read Install Session Kit.

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
sp new shell

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.

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.

Safety model

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