ccsessions-tui 0.1.0__tar.gz

ccsessions_tui-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+      - name: Test
+        run: pytest -v

ccsessions_tui-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ccsessions_tui-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Environments
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+
+# OS
+.DS_Store
+
+# Claude Code local settings
+.claude/

ccsessions_tui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marek Miśkiewicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ccsessions_tui-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+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)

ccsessions_tui-0.1.0/README.md

@@ -0,0 +1,130 @@
+# 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)

ccsessions_tui-0.1.0/ccsessions/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ccsessions_tui-0.1.0/ccsessions/__main__.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import sys
+
+from .core.resume import ResumeError, ResumeRequest, execute_resume
+from .ui.app import CCSessionsApp
+
+
+def main() -> int:
+    app = CCSessionsApp()
+    result = app.run()
+    if isinstance(result, ResumeRequest):
+        try:
+            execute_resume(result)  # replaces process; does not return on success
+        except ResumeError as e:
+            print(f"Resume failed: {e}", file=sys.stderr)
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ccsessions_tui-0.1.0/ccsessions/core/aliases.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .models import Project
+
+DEFAULT_ALIASES_PATH = Path.home() / ".config" / "ccsessions" / "aliases.json"
+
+
+class ProjectAliases:
+    """Cosmetic display names for projects, keyed by project path.
+
+    Purely a ccsessions-side overlay — nothing under ~/.claude is touched,
+    so the default (path-derived) name is always recoverable by removing
+    the alias.
+    """
+
+    def __init__(self, path: Path = DEFAULT_ALIASES_PATH) -> None:
+        self.path = path
+        self._data: dict[str, str] = {}
+        self._load()
+
+    def _load(self) -> None:
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return
+        if isinstance(data, dict):
+            self._data = {
+                k: v for k, v in data.items() if isinstance(k, str) and isinstance(v, str)
+            }
+
+    def get(self, project_path: str) -> str:
+        return self._data.get(project_path, "")
+
+    def set(self, project_path: str, alias: str) -> None:
+        self._data[project_path] = alias
+
+    def remove(self, project_path: str) -> None:
+        self._data.pop(project_path, None)
+
+    def save(self) -> None:
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self.path.with_suffix(".tmp")
+            tmp.write_text(
+                json.dumps(self._data, indent=2, ensure_ascii=False), encoding="utf-8"
+            )
+            tmp.replace(self.path)
+        except OSError:
+            pass
+
+    def apply(self, projects: list[Project]) -> None:
+        for p in projects:
+            p.alias = self.get(p.project_path)

ccsessions_tui-0.1.0/ccsessions/core/cache.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .models import TokenStats
+
+DEFAULT_CACHE_PATH = Path.home() / ".cache" / "ccsessions" / "token-stats.json"
+
+
+class TokenCache:
+    """Per-JSONL-file token stats cache.
+
+    An entry stays valid as long as the file's (st_mtime_ns, st_size) are
+    unchanged — large finished sessions are read from disk only once.
+    """
+
+    def __init__(self, path: Path = DEFAULT_CACHE_PATH) -> None:
+        self.path = path
+        self._entries: dict[str, dict] = {}
+        self._dirty = False
+        self._load()
+
+    def _load(self) -> None:
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return
+        if isinstance(data, dict):
+            self._entries = {
+                k: v for k, v in data.items() if isinstance(v, dict)
+            }
+
+    def get(self, jsonl: Path, stat: os.stat_result | None = None) -> TokenStats | None:
+        entry = self._entries.get(str(jsonl))
+        if not entry:
+            return None
+        if stat is None:
+            try:
+                stat = jsonl.stat()
+            except OSError:
+                return None
+        if entry.get("mtime_ns") != stat.st_mtime_ns or entry.get("size") != stat.st_size:
+            return None
+        try:
+            return TokenStats(
+                input=int(entry["input"]),
+                output=int(entry["output"]),
+                cache_read=int(entry["cache_read"]),
+                cache_write=int(entry["cache_write"]),
+                messages=int(entry["messages"]),
+            )
+        except (KeyError, TypeError, ValueError):
+            return None
+
+    def put(self, jsonl: Path, stats: TokenStats, stat: os.stat_result) -> None:
+        self._entries[str(jsonl)] = {
+            "mtime_ns": stat.st_mtime_ns,
+            "size": stat.st_size,
+            "input": stats.input,
+            "output": stats.output,
+            "cache_read": stats.cache_read,
+            "cache_write": stats.cache_write,
+            "messages": stats.messages,
+        }
+        self._dirty = True
+
+    def prune(self, existing: set[str]) -> None:
+        """Drop entries for files that no longer exist on disk."""
+        stale = [k for k in self._entries if k not in existing]
+        for k in stale:
+            del self._entries[k]
+            self._dirty = True
+
+    def save(self) -> None:
+        if not self._dirty:
+            return
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self.path.with_suffix(".tmp")
+            tmp.write_text(json.dumps(self._entries), encoding="utf-8")
+            tmp.replace(self.path)
+            self._dirty = False
+        except OSError:
+            pass