clack-tui 0.1.1__tar.gz

clack_tui-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Build package
+        run: uv build
+
+      - name: Validate package metadata
+        run: uvx twine check dist/*
+
+      - name: Smoke test installed CLI
+        run: |
+          uv venv .smoke-test
+          . .smoke-test/bin/activate
+          uv pip install dist/*.whl
+          python -c "import shutil; import clack; import clack.__main__; assert shutil.which('clack'); assert shutil.which('clack-tui')"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

clack_tui-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.envrc
+.venv/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/

clack_tui-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janine
+
+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.

clack_tui-0.1.1/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: clack-tui
+Version: 0.1.1
+Summary: TUI for browsing, searching, and resuming Claude Code sessions
+Project-URL: Homepage, https://github.com/jcc-ne/clack
+Project-URL: Repository, https://github.com/jcc-ne/clack
+Project-URL: Issues, https://github.com/jcc-ne/clack/issues
+Author: Janine
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,claude-code,terminal,textual,tui
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=1.1.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: libtmux>=0.40.0
+Requires-Dist: textual>=1.0.0
+Description-Content-Type: text/markdown
+
+# clack
+
+[![PyPI](https://img.shields.io/pypi/v/clack-tui)](https://pypi.org/project/clack-tui/)
+[![Python](https://img.shields.io/pypi/pyversions/clack-tui)](https://pypi.org/project/clack-tui/)
+[![License](https://img.shields.io/github/license/jcc-ne/clack)](LICENSE)
+
+A terminal UI for browsing, searching, and resuming [Claude Code](https://claude.ai/code) sessions.
+
+Browse your full session history, read past conversations, jump into stats, and resume any session — all without leaving the terminal.
+
+---
+
+## Install
+
+```bash
+# pipx
+pipx install clack-tui
+
+# uvx (run without installing)
+uvx clack-tui
+```
+
+The package name is `clack-tui` because `clack` is already taken on PyPI. The package installs both `clack` and `clack-tui` executables.
+
+Requires Python 3.11+ and [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) installed.
+
+---
+
+## Quick start
+
+```bash
+clack
+```
+
+clack reads your Claude Code session files directly from `~/.claude/projects/` — no configuration needed.
+
+---
+
+## Features
+
+| Tab | Key | What it does |
+|-----|-----|--------------|
+| Dashboard | `1` | Browse all sessions, search with full-text search (DuckDB FTS / BM25) |
+| Stats | `2` | Token usage and model breakdown, daily sparklines |
+| Dialog | `3` | Read any conversation turn-by-turn, export to HTML |
+| Query | `4` | Write SQL directly against your session data (DuckDB) |
+
+### Dashboard key bindings
+
+| Key | Action |
+|-----|--------|
+| `/` | Focus search |
+| `Esc` | Clear search |
+| `Enter` | Resume session (opens `claude --resume`) |
+| `v` | View full conversation |
+| `r` | Refresh session list |
+| `q` | Quit |
+
+**tmux:** If clack is running inside a tmux session, resuming opens the session in a new tmux window. Otherwise it suspends the TUI, runs `claude --resume`, and returns when you exit.
+
+If the DuckDB FTS extension is unavailable, dashboard search falls back to simple substring matching.
+
+### Query console
+
+The Query console exposes your session data as DuckDB SQL views:
+
+| View | Contents |
+|------|----------|
+| `v_sessions` | One row per session — date, project, summary, model, turn count |
+| `v_assistant_turns` | Individual assistant turns with token counts |
+| `v_stats` | Aggregated usage by model |
+| `v_sessions_by_day` | Daily session and token totals |
+| `raw_records` | Raw JSONL records |
+
+Example queries:
+
+```sql
+-- Sessions from the last week
+SELECT title, cwd, turn_count FROM v_sessions
+WHERE last_active > now() - INTERVAL '7 days';
+
+-- Most token-heavy sessions
+SELECT sessionId, SUM(output_tokens) AS total
+FROM v_assistant_turns GROUP BY 1 ORDER BY 2 DESC LIMIT 10;
+```
+
+---
+
+## Dev setup
+
+```bash
+git clone https://github.com/jcc-ne/clack
+cd clack
+uv sync
+uv run clack
+```
+
+Release notes for TestPyPI and Trusted Publishing live in [docs/releasing.md](docs/releasing.md).
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) (session files at `~/.claude/projects/`)
+- tmux (optional — enables opening resumed sessions in a new window)

clack_tui-0.1.1/README.md

@@ -0,0 +1,106 @@
+# clack
+
+[![PyPI](https://img.shields.io/pypi/v/clack-tui)](https://pypi.org/project/clack-tui/)
+[![Python](https://img.shields.io/pypi/pyversions/clack-tui)](https://pypi.org/project/clack-tui/)
+[![License](https://img.shields.io/github/license/jcc-ne/clack)](LICENSE)
+
+A terminal UI for browsing, searching, and resuming [Claude Code](https://claude.ai/code) sessions.
+
+Browse your full session history, read past conversations, jump into stats, and resume any session — all without leaving the terminal.
+
+---
+
+## Install
+
+```bash
+# pipx
+pipx install clack-tui
+
+# uvx (run without installing)
+uvx clack-tui
+```
+
+The package name is `clack-tui` because `clack` is already taken on PyPI. The package installs both `clack` and `clack-tui` executables.
+
+Requires Python 3.11+ and [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) installed.
+
+---
+
+## Quick start
+
+```bash
+clack
+```
+
+clack reads your Claude Code session files directly from `~/.claude/projects/` — no configuration needed.
+
+---
+
+## Features
+
+| Tab | Key | What it does |
+|-----|-----|--------------|
+| Dashboard | `1` | Browse all sessions, search with full-text search (DuckDB FTS / BM25) |
+| Stats | `2` | Token usage and model breakdown, daily sparklines |
+| Dialog | `3` | Read any conversation turn-by-turn, export to HTML |
+| Query | `4` | Write SQL directly against your session data (DuckDB) |
+
+### Dashboard key bindings
+
+| Key | Action |
+|-----|--------|
+| `/` | Focus search |
+| `Esc` | Clear search |
+| `Enter` | Resume session (opens `claude --resume`) |
+| `v` | View full conversation |
+| `r` | Refresh session list |
+| `q` | Quit |
+
+**tmux:** If clack is running inside a tmux session, resuming opens the session in a new tmux window. Otherwise it suspends the TUI, runs `claude --resume`, and returns when you exit.
+
+If the DuckDB FTS extension is unavailable, dashboard search falls back to simple substring matching.
+
+### Query console
+
+The Query console exposes your session data as DuckDB SQL views:
+
+| View | Contents |
+|------|----------|
+| `v_sessions` | One row per session — date, project, summary, model, turn count |
+| `v_assistant_turns` | Individual assistant turns with token counts |
+| `v_stats` | Aggregated usage by model |
+| `v_sessions_by_day` | Daily session and token totals |
+| `raw_records` | Raw JSONL records |
+
+Example queries:
+
+```sql
+-- Sessions from the last week
+SELECT title, cwd, turn_count FROM v_sessions
+WHERE last_active > now() - INTERVAL '7 days';
+
+-- Most token-heavy sessions
+SELECT sessionId, SUM(output_tokens) AS total
+FROM v_assistant_turns GROUP BY 1 ORDER BY 2 DESC LIMIT 10;
+```
+
+---
+
+## Dev setup
+
+```bash
+git clone https://github.com/jcc-ne/clack
+cd clack
+uv sync
+uv run clack
+```
+
+Release notes for TestPyPI and Trusted Publishing live in [docs/releasing.md](docs/releasing.md).
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) (session files at `~/.claude/projects/`)
+- tmux (optional — enables opening resumed sessions in a new window)

clack_tui-0.1.1/docs/releasing.md

@@ -0,0 +1,71 @@
+# Releasing clack-tui
+
+## Manual dry run with TestPyPI
+
+Create a TestPyPI account, enable 2FA, and create a TestPyPI API token.
+
+Store the token in `~/.pypirc`:
+
+```ini
+[distutils]
+index-servers =
+    pypi
+    testpypi
+
+[pypi]
+username = __token__
+password = pypi-REPLACE_ME
+
+[testpypi]
+repository = https://test.pypi.org/legacy/
+username = __token__
+password = pypi-REPLACE_ME
+```
+
+Lock the file down:
+
+```bash
+chmod 600 ~/.pypirc
+```
+
+Build and upload:
+
+```bash
+uv build
+uvx twine check dist/*
+uvx twine upload -r testpypi dist/*
+```
+
+Smoke-test install from TestPyPI:
+
+```bash
+python3 -m venv /tmp/clack-test
+source /tmp/clack-test/bin/activate
+python -m pip install --upgrade pip
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple clack-tui
+clack
+```
+
+If `0.1.0` has already been uploaded to TestPyPI, bump `version` in `pyproject.toml` before uploading again.
+
+## Trusted Publishing to PyPI
+
+The repo includes a GitHub Actions workflow at `.github/workflows/publish.yml` that publishes on GitHub Release publication.
+
+Configure PyPI Trusted Publishing for the project:
+
+1. Create the `clack-tui` project on PyPI if it does not exist yet, either by an initial manual upload or by creating the project through PyPI's publisher flow.
+2. In PyPI, open the project, then go to `Manage` -> `Publishing`.
+3. Add a GitHub publisher with:
+   - Owner: `jcc-ne`
+   - Repository: `clack`
+   - Workflow filename: `publish.yml`
+   - Environment name: `pypi`
+4. In GitHub, create an environment named `pypi` for the repository. Add approval rules if you want a manual gate.
+5. Publish a GitHub Release. The workflow will build with `uv build` and publish to PyPI via OIDC.
+
+Notes:
+
+- Trusted Publishing does not require a PyPI API token in GitHub secrets.
+- The workflow requests `id-token: write`, which PyPI uses to mint a short-lived upload token.
+- You can keep using the manual TestPyPI flow locally even after enabling Trusted Publishing for production releases.

clack_tui-0.1.1/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "clack-tui"
+version = "0.1.1"
+description = "TUI for browsing, searching, and resuming Claude Code sessions"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Janine" }]
+requires-python = ">=3.11"
+keywords = ["claude", "tui", "terminal", "ai", "textual", "claude-code"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Terminals",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "textual>=1.0.0",
+    "duckdb>=1.1.0",
+    "libtmux>=0.40.0",
+    "jinja2>=3.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jcc-ne/clack"
+Repository = "https://github.com/jcc-ne/clack"
+Issues = "https://github.com/jcc-ne/clack/issues"
+
+[project.scripts]
+clack = "clack.__main__:main"
+clack-tui = "clack.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clack"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.claude",
+    "/.envrc",
+    "/uv.lock",
+]
+
+[tool.ruff]
+target-version = "py311"
+src = ["src"]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ty.environment]
+root = "src"

clack_tui-0.1.1/src/clack/__init__.py

@@ -0,0 +1 @@
+"""clack — TUI for Claude Code session management."""

clack_tui-0.1.1/src/clack/__main__.py

@@ -0,0 +1,12 @@
+"""Entry point for `python -m clack` and the `clack` CLI command."""
+
+from clack.app import ClackApp
+
+
+def main():
+    app = ClackApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

clack_tui-0.1.1/src/clack/app.py

@@ -0,0 +1,142 @@
+"""Main Textual application for clack."""
+
+from __future__ import annotations
+
+import duckdb
+from textual import work
+from textual.actions import SkipAction
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.events import Key
+from textual.widgets import Footer, Header, Input, LoadingIndicator, TabbedContent, TabPane, Tree
+from textual.worker import Worker, WorkerState
+
+from clack.widgets.dashboard import DashboardTab
+from clack.widgets.dialog_viewer import DialogViewer
+from clack.widgets.query_console import QueryConsole
+from clack.widgets.stats import StatsTab
+
+
+class ClackApp(App):
+    CSS_PATH = "css/app.tcss"
+    TITLE = "clack"
+    BINDINGS = [
+        Binding("1", "show_tab('dashboard')", "Dashboard", show=True),
+        Binding("2", "show_tab('stats')", "Stats", show=True),
+        Binding("3", "show_tab('dialog')", "Dialog", show=True),
+        Binding("4", "show_tab('query')", "Query", show=True),
+        Binding("q", "quit", "Quit", show=True),
+        Binding("t", "switch_theme", "Theme", show=True),
+        Binding("G", "nav_end", show=False),
+        Binding("ctrl+f", "nav_page_down", show=False),
+        Binding("ctrl+b", "nav_page_up", show=False),
+    ]
+
+    THEMES = ("solarized-dark", "solarized-light")
+
+    db: duckdb.DuckDBPyConnection | None = None
+    _dashboard: DashboardTab | None = None
+    _g_pending: bool = False
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield LoadingIndicator(id="loading-indicator")
+        with TabbedContent(id="tabs"):
+            with TabPane("Dashboard", id="dashboard"):
+                yield DashboardTab()
+            with TabPane("Stats", id="stats"):
+                yield StatsTab()
+            with TabPane("Dialog", id="dialog"):
+                yield DialogViewer()
+            with TabPane("Query", id="query"):
+                yield QueryConsole()
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.theme = "solarized-dark"
+        self.query_one("#tabs").display = False
+        self._load_data()
+        self.set_interval(60, self._auto_refresh_dashboard)
+
+    @work(thread=True, group="db_init")
+    def _load_data(self) -> duckdb.DuckDBPyConnection:
+        from clack.db import get_connection
+
+        return get_connection()
+
+    def on_worker_state_changed(self, event: Worker.StateChanged) -> None:
+        if event.worker.group == "db_init" and event.state == WorkerState.SUCCESS:
+            self.db = event.worker.result
+            self.query_one("#loading-indicator").display = False
+            self.query_one("#tabs").display = True
+            assert self.db is not None
+            self._dashboard = self.query_one(DashboardTab)
+            self._dashboard.load_data(self.db)
+            self.query_one(StatsTab).load_data(self.db)
+            self.query_one(QueryConsole).set_db(self.db)
+
+    def _auto_refresh_dashboard(self) -> None:
+        """Periodic refresh for the dashboard tab."""
+        if self.db is not None and self._dashboard is not None:
+            try:
+                self._dashboard._refresh_data()
+            except Exception:
+                pass
+
+    def on_key(self, event: Key) -> None:
+        # Skip vim nav when an Input widget has focus
+        if isinstance(self.focused, Input):
+            self._g_pending = False
+            return
+        if event.key == "g":
+            if self._g_pending:
+                # gg -> go to top
+                self._g_pending = False
+                event.prevent_default()
+                self.action_nav_home()
+            else:
+                self._g_pending = True
+                event.prevent_default()
+            return
+        self._g_pending = False
+
+    def _nav_action(self, *actions: str) -> None:
+        """Try navigation actions on the focused widget, using the first one found."""
+        widget = self.focused
+        if widget is None:
+            return
+        for action in actions:
+            method = getattr(widget, f"action_{action}", None)
+            if method is not None:
+                try:
+                    method()
+                except SkipAction:
+                    continue
+                return
+
+    def action_nav_home(self) -> None:
+        self._nav_action("scroll_top", "scroll_home")
+
+    def action_nav_end(self) -> None:
+        self._nav_action("scroll_bottom", "scroll_end")
+
+    def action_nav_page_down(self) -> None:
+        self._nav_action("page_down")
+
+    def action_nav_page_up(self) -> None:
+        self._nav_action("page_up")
+
+    def action_switch_theme(self) -> None:
+        current = self.THEMES.index(self.theme) if self.theme in self.THEMES else -1
+        self.theme = self.THEMES[(current + 1) % len(self.THEMES)]
+
+    def action_show_tab(self, tab_id: str) -> None:
+        self.query_one(TabbedContent).active = tab_id
+
+    def show_dialog(self, session_id: str, title: str) -> None:
+        """Switch to dialog tab and load a session."""
+        self.query_one(TabbedContent).active = "dialog"
+        assert self.db is not None
+        viewer = self.query_one(DialogViewer)
+        viewer.load_session(self.db, session_id, title)
+        viewer.query_one("#dialog-tree", Tree).focus()

clack_tui-0.1.1/src/clack/css/app.tcss

@@ -0,0 +1,104 @@
+Screen {
+    background: $surface;
+}
+
+#loading-indicator {
+    width: 100%;
+    height: 100%;
+    content-align: center middle;
+}
+
+/* Dashboard */
+DashboardTab {
+    height: 1fr;
+}
+
+DashboardTab DataTable {
+    height: 1fr;
+}
+
+DashboardTab #detail-bar {
+    height: 3;
+    padding: 0 1;
+    background: $surface-darken-1;
+    color: $text-muted;
+}
+
+DashboardTab #search-input {
+    dock: top;
+    width: 100%;
+    margin: 0;
+}
+
+/* Stats */
+StatsTab {
+    height: 1fr;
+    layout: grid;
+    grid-size: 2;
+    grid-gutter: 1;
+}
+
+StatsTab #model-table {
+    height: 1fr;
+}
+
+StatsTab #stats-summary {
+    height: 1fr;
+    padding: 1;
+}
+
+/* Dialog Viewer */
+DialogViewer {
+    height: 1fr;
+}
+
+DialogViewer #dialog-header {
+    height: 2;
+    padding: 0 1;
+    background: $primary-darken-2;
+    color: $text;
+}
+
+DialogViewer #dialog-search {
+    dock: top;
+    width: 100%;
+    margin: 0;
+}
+
+DialogViewer #dialog-tree {
+    height: 1fr;
+}
+
+DialogViewer #dialog-footer {
+    height: 1;
+    padding: 0 1;
+    background: $surface-darken-1;
+    color: $text-muted;
+}
+
+/* Query Console */
+QueryConsole {
+    height: 1fr;
+}
+
+QueryConsole #query-results {
+    height: 1fr;
+}
+
+QueryConsole #query-input {
+    height: 5;
+    border: tall $primary;
+}
+
+QueryConsole #query-status {
+    height: 1;
+    padding: 0 1;
+    background: $surface-darken-1;
+    color: $text-muted;
+}
+
+QueryConsole #views-help {
+    height: 1;
+    padding: 0 1;
+    color: $text-muted;
+}