Metadata-Version: 2.4
Name: ccsessions-tui
Version: 0.1.0
Summary: Terminal UI for browsing, previewing, resuming and managing Claude Code sessions
Project-URL: Homepage, https://github.com/miskiewiczm/ccsessions
Project-URL: Issues, https://github.com/miskiewiczm/ccsessions/issues
Author: Marek Miśkiewicz
License: MIT
License-File: LICENSE
Keywords: claude,claude-code,sessions,terminal,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: textual>=0.80
Description-Content-Type: text/markdown

# ccsessions

A fast terminal UI for browsing, previewing, resuming and managing
[Claude Code](https://claude.com/claude-code) terminal sessions.

![ccsessions in a fullscreen terminal — wide layout with a full-height conversation pane](assets/ccsessions_fullscreen.png)

## 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:

  <img src="assets/ccsessions_halfscreen.png" alt="ccsessions in a half-screen terminal — stacked layout with a full-width conversation pane" width="70%">
- **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](https://claude.com/claude-code) installed (`claude` on PATH —
  needed only for resuming)
- macOS or Linux (Windows untested)

## Installation

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

Both install the `ccsessions` command.

Or from a clone:

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

## Usage

```bash
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) |
| `/` | Filter the focused list (projects or sessions) |
| `Ctrl+R` | Rescan `~/.claude` |
| `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()`).
- `~/.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

```bash
pip install -e . --group dev
pytest
```

## License

[MIT](LICENSE)
