ccs — Claude Code session manager

A fast terminal UI to browse, resume, fork, rename, and delete your Claude Code CLI sessions — organized by project, with a live preview of each conversation.

Claude Code stores every session on disk, but claude --resume only gives you a flat, unsorted picker with no way to group by project, preview, rename, or delete. ccs fixes that.

Features

• Grouped by project — pick a project, then a session.
• Live preview pane — see the most recent messages of the highlighted session.
• Scrollable, lazy-loaded list — instant startup even with hundreds of large sessions; metadata loads only for what's on screen.
• Resume with launch options — start a session in plan mode, with --dangerously-skip-permissions, a specific model, extra --add-dirs, etc.
• Fork a session into a new id (--fork-session) to experiment without touching the original.
• Rename (writes a new ai-title, exactly like Claude does) and delete (removes the .jsonl plus all satellite files).
• Works as an interactive TUI or via scriptable subcommands.

Install

# from npm (scoped)
npm install -g @raoufsenou/claude-session-manager

# or with pnpm
pnpm add -g @raoufsenou/claude-session-manager

This installs the ccs command. Requires Node ≥ 20 and the claude CLI on your PATH (for resume/fork).

From source

git clone https://github.com/raoufsenou/claude-session-manager.git
cd claude-session-manager
pnpm install
pnpm build
pnpm link --global   # optional: makes `ccs` available everywhere

Usage

Run with no arguments for the interactive browser:

ccs

Keys (interactive browser)

| Key | Action | |-----|--------| | ↑ / ↓ | Move (the preview follows the selection) | | ⏎ | Resume the session | | o | Resume options (permission mode, fork, safe/bare/ide, extra flags) | | f | Fork & resume (new session id, original untouched) | | r | Rename | | i | Details | | d | Delete (with confirmation) | | q | Back to project list | | esc | Quit |

Subcommands

ccs                          # interactive browser
ccs list [--project <s>]     # list projects and sessions
ccs info <id>                # details for a session (id or unique prefix)
ccs preview <id>             # last messages of a session
ccs rename <id> <title>      # set a session's title
ccs resume <id> [-- ...]     # resume; flags after -- forwarded to claude
ccs fork <id> [-- ...]       # resume into a new session id (--fork-session)
ccs delete <id> [--yes]      # delete a session and its files

Anything after -- is forwarded verbatim to claude:

ccs resume 03fc9146 -- --permission-mode plan --add-dir ../shared

Resume options & defaults

The o popup lets you shape how a session boots — the launch-time choices you can't easily make once Claude is running:

• Permission: default · plan · acceptEdits · dontAsk · bypassPermissions · skip-all (skip-all → --dangerously-skip-permissions, the rest → --permission-mode)
• Fork → new id, Safe mode (--safe-mode), Bare mode (--bare), Connect IDE (--ide)
• Extra flags: free-text list for anything else (--model, --add-dir, …)

Default options are read from ccs.config.json (shipped with the package, no files are written to your home directory). Edit it to set your preferred defaults — for example, always resume in plan mode:

{ "permission": "plan", "fork": false, "safeMode": false, "bare": false, "ide": false, "extra": [] }

Per-launch tweaks in the o popup override these defaults for that launch only.

Flags that conflict with resuming (-r, -c, --session-id, --from-pr, -p) are stripped automatically with a warning.

How it works

Claude Code stores sessions as newline-delimited JSON at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl, with satellite data under session-env/, tasks/, and file-history/. ccs reads these directly — discovery uses only stat (instant), and titles/previews read just the head/tail of each file, never the whole thing. Deleting a session removes the .jsonl and all of its satellite files.

License

MIT © raoufsenou