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

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()).
• ~/.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