A local status and safety layer for shpool sessions running Claude Code, Codex, or shells over SSH.
The image is rendered from the real picker with demo-only session data by
tools/render-readme-dashboard; it is not a mock of a different interface.
Session Kit gives each managed terminal a stable number, useful name, color, reply state, and exact provider identity. It keeps the terminal alive when a provider exits and refuses actions when live identity cannot be proved.
Warning
Session Kit is a public beta for Linux with systemd and macOS 14 or newer. Start on a single-user account where Claude Code and Codex conversations can be recovered. Session Kit is not a boundary against another process running as the same Unix user.
- One on-demand picker for Claude Code, Codex, and shell sessions.
- First-install discovery of project folders already known to Claude Code and Codex, with no filesystem-wide scan.
needs your reply, working, idle, quiet, provider-exited, and subagent state.- Exact open, move, close, reopen, fork, repair, and recovery checks.
- Manual names plus guarded 2–5 word agent self-names.
- Per-provider colors, so two live sessions do not share one until the palette runs out, and a Claude session and a Codex session never share one at all.
- A visible
title pendingstate when a Codex bar still needs a safe refresh. - Immutable local releases with atomic update and rollback.
- Optional terminal journals, off by default.
- No account, hosted service, analytics, update beacon, or telemetry.
Normal rows hide shpool IDs and provider UUIDs. Use sp detail, JSON output, or
an explicit search when diagnosis requires exact identity.
Download the archive, checksum, and provenance files attached to the
v0.2.0 release.
Beta releases are published as GitHub prereleases, so releases/latest does not
resolve to them; browse all releases
or name the tag explicitly, as below. Release assets are named by commit, not by
version. With the GitHub CLI:
mkdir session-kit-download
cd session-kit-download
gh release download v0.2.0 --repo dob323/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 enableThe preflight is read-only. Installation copies an immutable release and
systemd or launchd definitions, but it does not start, stop, restart, or enable
a service. Review the definitions before services enable. The guided
installer can add the shell integration; journals remain off unless you
explicitly enable them. On a new interactive installation, it also shows the
existing project folders recorded by Claude Code and Codex and offers to import
them as local Session Kit shortcuts.
For requirements, manual asset download, and activation checks, read
Install Session Kit. Use main only for development after
reviewing and testing its exact commit.
SSH opens a normal shell. Type kit when you want the session picker.
kit
sp list
sp new [claude|codex|shell] [project-alias]
session-kit projects discover
session-kit projects import
session-kit projects candidates
session-kit projects import --select 1,3-4
session-kit projects add <alias> <claude|codex|shell> /absolute/path
session-kit projects here
session-kit projects ignore /absolute/path
sp go <terminal-number|shpool-id>
sp takeover <terminal-number|shpool-id>
sp name <terminal-number|shpool-id> <title>
sp name reset <terminal-number|shpool-id>
sp close <terminal-number|shpool-id>
sp repair <terminal-number|shpool-id>
sp detail <terminal-number|shpool-id>
sp find <text>
sp history <terminal-number|shpool-id>
sp health
sp recover
sp prune
The picker accepts one visible number to open a session. k accepts visible
numbers, comma-separated lists, and small ranges. Every action uses a frozen
private proof and rechecks live identity immediately before changing anything.
A cached or stale dashboard is read-only.
If a new Codex process started before its thread acquired a name, the row shows
title pending. A detached, proven-idle provider can refresh automatically on
open. An attached provider is never restarted automatically; its action menu
offers an explicit refresh only when the exact provider is idle and has no
subagents.
Session Kit runs on top of shpool and
does not vendor or replace it. shpool-patch/ carries local patches against
released shpool versions, each with the evidence that justified it and the
conditions under which it should not be applied. One of them, 0004, fixes a
detach deadlock in shpool 0.11.0 that can freeze every managed session at once;
read the patch notes before deciding what to run.
Rebuilding or reinstalling shpool replaces the binary you patched. session-kit doctor records the shpool binary it validated at install time and warns when it
changes, so a silent downgrade is caught by a health check rather than by a
frozen terminal.
Session Kit treats a provider UUID and exact process generation as identity. Titles, numbers, directories, timestamps, and terminal output are display context only. Missing, duplicated, changed, or partial evidence fails closed.
The default local footprint is privacy-minimal:
- journals and notifications are off;
- provider transcripts remain in provider-owned storage;
- the picker action log stores only fixed action and outcome labels;
- private state is owner-only and never uploaded by Session Kit.
Optional journals can contain prompts, credentials, source code, and command output. Read Security and local data before enabling them.
The watchdog raises no alert anywhere until you configure a notifier. It detects and logs either way, but with nothing wired up the only record is the owner-only watchdog log. See Watchdog alerts.
- Install
- Configure
- Use Session Kit
- Claude Code and Codex integration
- Security and local data
- Troubleshoot
- Update and roll back
- Uninstall
- Architecture
- Maintainer release process
Bug reports, feature requests, documentation fixes, and pull requests are welcome. Reports about provider compatibility, lifecycle safety, privacy, and clean installation are the most useful, especially from operating systems and hardware the maintainer cannot test.
Session Kit is maintained by one person alongside other work. Replies are best-effort rather than guaranteed, and a pull request may be declined when it would weaken the identity and safety model even if the code is sound. Read Contributing before opening a pull request.
Report vulnerabilities through the Security policy, never through a public issue.
Session Kit is released under the MIT License. The optional shpool patches modify Apache-2.0 software; see Third-party notices and the included Apache License 2.0.