Metadata-Version: 2.4
Name: clack-tui
Version: 0.2.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 / cmux:** If clack is running inside a tmux session, resuming opens the session in a new tmux window (or jumps to the existing pane if that session is already live). The same behavior works inside [cmux](https://github.com/manaflow-ai/cmux) — clack opens a new cmux workspace via `cmux new-workspace --cwd ... --command ...`, or focuses the existing pane with `cmux focus-pane`. Outside any multiplexer, clack 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 or [cmux](https://github.com/manaflow-ai/cmux) (optional — enables jumping to live sessions and opening resumed sessions in a new window/workspace)
