hex/claude-sessions

cs - Claude Code Session Manager

A session manager for Claude Code that creates isolated workspaces with automatic documentation.

Why cs?

Claude Code doesn't require a project. You can spin up an instance to debug an API, troubleshoot home automation, research a hardware problem, or explore any idea that comes to mind.

But conversations get lost. You discover key insights, create useful scripts, figure out a tricky configuration - then the session ends and it's gone.

cs gives every task a home:

cs debug-api          # Investigate that flaky endpoint
cs homeassistant      # Fix your smart home setup
cs router-config      # Document your network settings
cs research-llms      # Explore a topic, keep your notes

Each session is a persistent workspace - documentation and secrets that survive across conversations.

No git repo required. No project structure needed. Just a name for what you're working on.

Features

• Isolated session workspaces - Each session has its own directory with structured documentation
• Secure secrets handling - Store sensitive data in the OS keychain (value read from stdin, never written to a file); exportable as age-encrypted files for backup
• Documentation templates - Pre-configured markdown files for the session narrative and outcome
• Automatic git version control - Every session gets a local git repo; in-session edits are autosaved to a shadow ref for crash recovery
• Session locking - PID-based lock prevents the same session from being opened in two terminals simultaneously; use --force to override. cs also treats a session as live when its statusline heartbeat is fresh — in the TUI (■ live · unlocked), cs -live, and the cs -usage marker — so a conversation opened outside cs still registers as live. The destructive guards (cs -rm/-archive/-spawn) stay on the strict PID lock, so a session whose process is gone is still removable without --force
• Deterministic Claude-session resume - Each session pre-allocates a conversation UUID in the gitignored .cs/local/state, so cs <name resumes the exact conversation via claude --resume <uuid, not the most-recent one --continue might pick from a sibling. A ps-based guard refuses to launch a second claude for the same conversation (--force overrides), and every launch passes --name plus a per-session /color so parallel sessions stay visually distinct.

• Per-session memory path redirect - cs points Claude Code's built-in auto-memory writer at <session/.cs/memory/ (via CLAUDECOWORKMEMORYPATHOVERRIDE) so durable facts land in the session instead of the global project store. The harness owns how memory files are written (naming, frontmatter, MEMORY.md index); cs owns only the storage path.
• Cross-session search - cs -search <query greps across all sessions' narrative, memory, and README
• Prose hygiene enforcement - cs -lint <file flags AI-slop tells (em-dashes, a curated banned-phrase list) outside code fences; the prose-lint Stop hook blocks turn-end when prose written this session carries them. /summary and /wrap add a subagent judge that applies the full prose-hygiene taxonomy a regex can't catch. See docs/hooks.md
• Auto-grounded scope - On each code-work prompt, the scope-prompt hook injects a bounded context block — matching tracked files, recent commits, and a working-tree diff — grounding Claude in the current codebase before it acts. Capped at 8000 bytes; opt out per-session with CSSCOPEDISABLE=1. See docs/hooks.md
• Status line - cs-statusline renders Claude Code's status bar as one line of squared pills: a Claude logo badge (pulsing until your next prompt), the session name in its /color, a queued-task count, an unread cross-session mail count, git branch with ahead/behind and dirty counts, model + effort, context %, and 5-hour/weekly rate limits (each gaining a reset countdown as it fills) — all from the status-line JSON plus one bounded git call, with no transcript parsing, network, or writes. Session cost is available as an opt-in segment. Enable or remove it any time with cs -statusline enable|disable; choose and order segments with CSSTATUSLINESEGMENTS. cs auto-detects the terminal's light/dark theme (override with CSTERMTHEME; cs -detect-theme shows the result). A companion cs-subagent-statusline styles the agent-panel rows so each running subagent shows the model driving it, its own context %, and elapsed time; cs -statusline enable registers both (Claude Code reads the registration at startup, so restart it to see them). See docs/statusline.md

• Health checks - cs -doctor reports status of Keychain backend, hook registration, shadow-ref freshness, auto-memory writability, status line registration, Claude Code settings audit (hooks/MCPs/permissions/env vars counts), and cumulative token usage for the current project
• Usage attribution - cs -usage shows which sessions are consuming the 5-hour and weekly rate-limit windows: per-session input/output token sums (deduplicated by API request, cache-read excluded), anchored at the true reset boundaries when the cs status line is active. cs -usage <name breaks one session down per conversation with a lifetime column.
• Session tags - cs -tag add api tags the current session in its README frontmatter (tags: [api] — the same field Obsidian indexes); cs -list --tag api filters the listing, and the picker filters live with #api in the search query (combining with fuzzy name search). Tags show in the preview card.
• Session archive - cs -archive <name drops a tracked .cs/archived marker that hides a finished session from the picker, cs -list, and cs -search (the marker syncs with the session, so archiving on one machine archives everywhere). cs -list --archived lists only archived sessions, cs -search <q --include-archived searches them, and the picker toggles visibility with A (archived rows render dimmed). Opening an archived session unarchives it.
• Walk-away supervision - a draining queue is watched by circuit breakers: too many tool failures in one task (default 5, CSQUEUEMAXFAILURES), context past 85% (CSQUEUEMAXCTX), or the 5-hour rate-limit window past 85% (CSQUEUEMAX5H) parks the queue with a debrief instead of feeding the next task — nothing is lost, cs -queue start re-arms. Everything that happened while you were away (tasks done, breaker trips) lands in a per-machine journal: a one-line digest surfaces once on your return, and cs -queue log shows the full history.
• Cross-session mail - cs -msg <session "note" drops a message in another session's machine-local mailbox (--kind notify|task|text|result; task also lands in its walk-away queue). The recipient sees the unread bodies inlined into its context on every prompt until it reads them with cs -msg (bounded to 5, truncated; task kind shows a count-only label since it is already queued). Same-machine only; attribution is unauthenticated by design.

• tmux spawner - cs -spawn <name opens a session in a cs-owned tmux session (tmux attach -t cs); --task "..." seeds and arms its walk-away queue so it starts working unattended, and the spawner hears back over cross-session mail when the queue drains. Same-machine only.
• Conversation rotation - a heavy conversation can hand off to a fresh one without losing context: the rotate skill (self-invoked, or nudged once per conversation past 80% context) writes a lineage-stamped handoff to .cs/handoffs/ and arms it, then /clear continues from it without leaving Claude Code. Exiting and answering r at the next cs <name launch does the same; d discards the handoff. cs -conversations shows the resulting chain.
• Voice drafting - /voice drafts messages, replies, PR text, or docs in your own writing voice. On first use it distills your typed messages from Claude Code transcripts into an editable profile at ~/.claude-sessions/.voice/profile.md; drafting loads the profile and writes as you.
• iTerm2 awareness - inside iTerm2 the session color tints the tab (native escapes, reset on exit), and with iTerm2 shell integration installed a finished turn bounces the dock until your next prompt. CSNOITERM2=1 disables; cs -doctor reports the integration surface.
• Bash command audit trail - Every Bash command Claude runs is logged to .cs/local/session.log (machine-local, never git-synced) with timestamps
• Update notifications - Checks for updates and notifies when new versions are available. When an update is pending, cs shows the release notes for every version above the installed one: a compact summary card in the launch banner, and the full notes under cs -update --check.

• Verified updates - Updates are downloaded from GitHub Releases and verified with SHA-256 checksums; additionally verified with minisign signatures when available

Installation

Bash (macOS/Linux)

bash -c "$(curl -fsSL https://raw.githubusercontent.com/hex/claude-sessions/main/install.sh)"