ccsessions-tui 0.2.1

Terminal UI for browsing, previewing, resuming and managing Claude Code sessions

ccsessions

A fast terminal UI for browsing, previewing, resuming and managing Claude Code terminal sessions.

Features

• Project & session browser — every Claude Code project on your machine, newest first, with live-session indicators (●), message counts and token usage (input / output / cache read / cache write)

• Conversation preview — the tail of any session rendered with roles, Markdown (for Claude's replies), tool calls (⚙) and slash commands (⌘), without opening Claude Code

• One-key resume — r replaces the TUI with claude --resume <id> in the session's working directory; c copies a ready cd <dir> && claude --resume <id> command to the clipboard (OSC 52)

• Archive & delete — move sessions out of claude --resume (reversibly) or delete them for good, per session or per project, with confirmation dialogs; sessions whose transcript lives on another synced machine are detected and marked (✕)

• Responsive layout — wide terminals get a side-by-side layout with a full-height conversation pane; narrow (half-screen) terminals get a stacked layout with a full-width conversation pane:

  

• Export — write a whole session to Markdown (YAML front matter with session metadata, then the conversation — ready for Quarto/Pandoc) or copy the raw JSONL transcript verbatim; existing files are never overwritten

• Fast — token stats are cached per transcript (invalidated by mtime + size), scanning runs off the UI thread, and conversation previews read only the tail of multi-megabyte files

Requirements

• Python ≥ 3.10
• Claude Code installed (claude on PATH — needed only for resuming)
• macOS or Linux (Windows untested)

Installation

pipx install ccsessions-tui        # or: uv tool install ccsessions-tui

Both install the ccsessions command.

Or from a clone:

git clone https://github.com/miskiewiczm/ccsessions
pip install -e ccsessions

Usage

ccsessions

Key	Action
j / k / arrows	Move within the focused pane
Tab / Shift+Tab	Switch panes
r	Resume the selected session (in place)
c	Copy the resume command to the clipboard
a	Archive ↔ restore session · archive ↔ restore project
d	Delete session / project (with confirmation)
n	Rename project (set a display alias)
e	Export the session (Markdown or raw JSONL)
/	Filter the focused list (projects or sessions)
Ctrl+R	Rescan ~/.claude now (a rescan also runs automatically)
q	Quit

a and d act on the session when the Sessions pane is focused and on the whole project when the Projects pane is focused.

Project names default to the last component of the project's working directory. n sets a purely cosmetic alias (stored in ~/.config/ccsessions/aliases.json — nothing under ~/.claude is touched); submitting an empty alias removes the entry and restores the default name.

Configuration

• Theme — switch at runtime with Ctrl+P → "Change theme"; the choice is remembered across runs (~/.config/ccsessions/settings.json). The CCSESSIONS_THEME env var overrides it. The default ansi-dark follows your terminal's palette and keeps terminal transparency; RGB themes (nord, gruvbox, tokyo-night, dracula, …) paint opaque backgrounds.
• Code blocks — fenced code follows the app theme with a matching pygments style. Set CCSESSIONS_CODE_THEME to pin a specific one (any name from pygments.styles.get_all_styles()).
• CCSESSIONS_REFRESH_SECONDS — auto-refresh interval (default 10, 0 disables it). Rescans keep your selection and never scroll the conversation pane; they pause while a dialog or the filter bar is open.
• ~/.config/ccsessions/aliases.json — project display aliases, managed with the n key.

How it works

ccsessions reads the data Claude Code already keeps on disk:

• ~/.claude/projects/<encoded-path>/*.jsonl — session transcripts
• ~/.claude/projects/<encoded-path>/sessions-index.json — session metadata (summaries, first prompts, message counts)
• ~/.claude/sessions/*.json — live-session records (PID liveness is checked with signal 0)

Archiving a session moves its transcript into an archived/ subdirectory of the project folder (invisible to claude --resume, fully restorable). Archiving a project moves the whole folder to ~/.claude/projects-archive/; archived projects stay listed (dimmed, ▪) after the active ones and can be restored with a. Deleting removes the transcript and its index entry. Token-stats caching lives in ~/.cache/ccsessions/.

Note: Claude Code automatically deletes transcripts older than its cleanupPeriodDays setting (30 days by default). If you rely on your session history, raise that value in ~/.claude/settings.json.

Privacy

Everything happens locally: ccsessions only reads files under ~/.claude/ and writes its cache under ~/.cache/ccsessions/. It makes no network requests and sends nothing anywhere.

Development

pip install -e . --group dev
pytest

License

MIT