cs creates persistent workspaces for Claude Code, with session notes, conversation resume, and local git history.

Install

Requires macOS or Linux, Bash 3.2+, git, jq, perl, Claude Code, and a UTF-8 locale. Remote control needs Claude Code 2.1.299+. Non-UTF-8 locales such as ja_JP.eucJP, ko_KR.eucKR, and zh_CN.eucCN cause syntax errors in cs and two of its hooks.

curl -fsSL https://github.com/hex/claude-sessions/releases/latest/download/install.sh | bash

From a checkout:

git clone https://github.com/hex/claude-sessions.git
cd claude-sessions
./install.sh

Review install.sh before running it. The piped command always installs the release, even inside a checkout. The installer puts the commands in ~/.local/bin/, registers hooks, and installs skills, mods, and Bash and Zsh completions. Updates and prebuilt picker downloads require ssh-keygen with -Y verify support to check the signed release manifest.

Usage

cs debug-api

One command, from any terminal: cs <name> creates the session the first time and resumes it every time after. It needs no project or git repository first.

First run in 60 seconds

1. Run cs debug-api. cs creates a workspace and opens Claude Code.
2. Describe your task. cs records the first substantive prompt in the session's Objective section and keeps notes under .cs/.
3. Exit Claude Code. Run cs debug-api again and accept the prompt to resume the recorded conversation.

When you forget a name, a bare cs opens a picker of your sessions, and cs . reopens the one whose root you are in.

The statusline guide covers the quiet default layout, the band and the capsules, colors, thresholds, font setup, and agent rows.

Features

Feature	What it does	Details
Session records	Keeps objectives, per-actor narratives, memory, plans, checkpoints, and a timeline in .cs/.	Session layout
Crash recovery	Saves edits to shadow git refs without adding normal branch commits.	Autosave hook
Conversation rotation	Hands work to a fresh conversation through /rotate and /clear.	Rotation and queue hooks
Existing projects	cs -adopt <name> registers your project without moving it.	Adoption
Parallel worktrees	cs <base>@<feature> gives each feature its own checkout and session records.	Worktrees
Remote control	cs <name> --remote serves a session for the Claude app or web.	Remote control
Task queue	Runs confirmed tasks at turn boundaries, with failure, context, and quota breakers.	Queue behavior
Cross-session mail	Delivers local messages and wakes idle sessions for unread arrivals.	Mail wakes
Secrets	Uses the macOS keychain or encrypted files, with signed age exports for sync.	Secrets guide
Encrypted sessions	Keeps notes, transcripts, plans, and private state in a vault on macOS.	Encrypted sessions
Statusline	Shows session, git, model, context, queue, mail, and rate limits.	Statusline guide
Prompt grounding	Adds matching files, recent commits, changes, and clarification guidance to code-work prompts.	Scope hook
Prompt rewriting	Ctrl+G rewrites a draft in the composer for you to review before sending.	Prompt rewriter
Writing skills	Judges prose or drafts from a writing profile.	Skills
Session wrap	/wrap saves memory, summarizes the narrative, and archives completed tasks without committing.	Memory checks
Inline Mermaid	Draws supported flowcharts in replies, and a show-me skill answers "show me" with one.	Mermaid mod
Chat feed	Folds each turn's tool calls into one line beside your messages and Claude's replies, off until you turn it on per session with the band's ctrl+x 3 or /feed on.	Feed mod
Release notes	Shows pending release notes in-session through /cs-update.	Update mod
Other front ends	Session hooks also work in desktop and IDE conversations opened in a .cs/ workspace.	Session resolution

Uninstall

cs -uninstall

Documentation

Guide	Contents
Commands	Command reference, adoption, worktrees, queues, remote control, and completion.
Configuration	Every environment variable cs reads and the values it exports.
Session layout	Shared and local records, encryption, and merge policy.
Hooks	Hook behavior, prompt rewriting, and Claude Code mods.
Secrets	Storage backends, backups, and signed sync files.
Statusline	Segments, the quiet, band and capsule layouts, colors, thresholds, and agent rows.

License

MIT. Contributions can start with an issue or pull request.