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

• Live document — w keeps _session_<id>.md in the project directory in sync with a running session, so an external renderer (quarto preview, VS Code, Marked, Obsidian) can display the conversation with LaTeX rendered while you work in the terminal. Only appended bytes are read, so following a 300 MB transcript costs nothing

• 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.

Live documents

w toggles a live Markdown document for the selected session, written to _session_<session-id>.md in that session's project directory and updated every couple of seconds while ccsessions runs. Point any live-reloading Markdown renderer at it — quarto preview _session_<id>.md renders LaTeX with KaTeX, which is the point: formulas Claude writes in the terminal become readable.

If the project is itself a Quarto project, quarto preview serves the project's output directory and cannot reach a document sitting next to it (you get a 404 and a /../ in the URL). Set CCSESSIONS_LIVE_DIR to a plain directory — e.g. export CCSESSIONS_LIVE_DIR=~/live — and live documents are written there instead.

The eye column shows the state: ◉ green — following a running session, ◉ yellow — following, but the session is not running, ◌ grey — the file exists but nothing is updating it (from an earlier run or another machine). With a Nerd Font in your terminal, set CCSESSIONS_NERD_FONT=1 for a proper eye glyph (or set CCSESSIONS_EYE / CCSESSIONS_EYE_OFF to any characters you like). Quitting ccsessions stops all updates and leaves the files in place; there are no background processes to track down. Add _session_*.md to .gitignore in git repositories.

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_LIVE_DIR — where live documents (w) are written; defaults to the session's own project directory. Point it at a plain directory when your projects are Quarto projects.
• 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