feat(tui-py): migrate TUI to Python/Textual; add tests + polish

Replace the Ink/React TUI under tui/ with a Python/Textual implementation
under tui-py/. New entry point: python3 tui-py/main.py (also wired into
the cctrace --tui CLI and dev:tui npm script).

Architecture
- Shared HighlightListView base class owns the highlight CSS, the
  background-tint:transparent focus override, and the ensure_highlight()
  cursor-init helper. SessionPicker, MessageList, and DetailView's items
  list all extend it — one source of truth for selection styling and
  initial cursor behaviour.
- MessageList.populate is async and awaits clear()/append()/remove().
  An exclusive worker group ("populate_msglist") serialises back-to-back
  populates so rapid SSE updates / load-session resets no longer race
  with their own deferred clear() calls and produce duplicated rows.
- _load_session keeps the picker visible (LoadingIndicator overlay)
  until the MessageList is fully populated, then flips the view —
  avoiding the few-second window where j/k pressed against an empty
  list pane.
- App.BINDINGS hosts j/k/Enter so they appear in the Footer on every
  page; thin delegation actions forward to the focused widget's
  cursor_up/cursor_down/select_cursor.

DetailView
- Bordered container; #msg-content gets a divider underneath.
- Two section headings: "RESPONSE" (top) and "STEP (N)" (between body
  and items list). Headings hide when no message or no items.
- Async _rebuild eagerly clears stale state and toggles loading on the
  pane while it rebuilds.

Other changes
- .gitignore: add Python entries (__pycache__, *.pyc, .venv).
- .github/dependabot.yml: add pip ecosystem for /tui-py.
- .claude/hooks/pre-commit.sh: run ruff format/lint when tui-py files
  are staged.
- bin/cctrace.mjs + package.json dev:tui: launch the Python TUI.
- README: add Python and Textual badges.

Tests
- pytest + pytest-asyncio in requirements.txt; pytest.ini with
  asyncio_mode = auto.
- tui-py/tests/ covers HighlightListView (ensure_highlight policy,
  shared highlight color), MessageList (populate race-safety,
  incremental diff, index preservation), DetailView (border, RESPONSE
  and STEP headings with item count + hide rules). 15 tests, all pass.

Drops the old tui/ TypeScript/Ink implementation entirely.

Author: delexw

.claude/hooks/pre-commit.sh

@@ -18,12 +18,12 @@ fi
 
 ERRORS=""
 
-# --- Format check ---
+# --- JS/TS Format check ---
 FMT_OUTPUT=$(npm run fmt:check 2>&1) || {
   ERRORS="Format issues found. Run: npm run fmt, do not ask user for options, ⚠️  STAGE THE FIXED FILES in a SEPARATE Bash tool call: git add <files>\nThen retry the commit in another Bash tool call.\n\n$FMT_OUTPUT"
 }
 
-# --- Lint check ---
+# --- JS/TS Lint check ---
 LINT_OUTPUT=$(npm run lint 2>&1)
 LINT_EXIT=$?
 if [ $LINT_EXIT -ne 0 ] || echo "$LINT_OUTPUT" | grep -qE "[1-9][0-9]* warnings? "; then
@@ -34,6 +34,24 @@ if [ $LINT_EXIT -ne 0 ] || echo "$LINT_OUTPUT" | grep -qE "[1-9][0-9]* warnings?
   fi
 fi
 
+# --- Python format + lint check (only when tui-py files are staged) ---
+PY_STAGED=$(printf '%s\n' "$STAGED" | grep '^tui-py/.*\.py$' || true)
+if [ -n "$PY_STAGED" ]; then
+  PY_FMT_OUTPUT=$(ruff format --check tui-py/ 2>&1)
+  PY_FMT_EXIT=$?
+  if [ $PY_FMT_EXIT -ne 0 ]; then
+    PY_FMT_MSG="Python format issues found. Run: cd tui-py && ruff format . — ⚠️  STAGE THE FIXED FILES in a SEPARATE Bash tool call, then retry.\n\n$PY_FMT_OUTPUT"
+    ERRORS="${ERRORS:+$ERRORS\n\n}$PY_FMT_MSG"
+  fi
+
+  PY_LINT_OUTPUT=$(ruff check tui-py/ 2>&1)
+  PY_LINT_EXIT=$?
+  if [ $PY_LINT_EXIT -ne 0 ]; then
+    PY_LINT_MSG="Python lint issues found. Fix at the root cause — do NOT add noqa comments unless genuinely necessary. ⚠️  STAGE THE FIXED FILES in a SEPARATE Bash tool call, then retry.\n\n$PY_LINT_OUTPUT"
+    ERRORS="${ERRORS:+$ERRORS\n\n}$PY_LINT_MSG"
+  fi
+fi
+
 if [ -n "$ERRORS" ]; then
   printf '{"decision": "block", "reason": %s}' "$(printf '%s' "$ERRORS" | jq -Rs .)"
   exit 0

.github/dependabot.yml

@@ -14,3 +14,8 @@ updates:
     directory: /src-tauri
     schedule:
       interval: weekly
+
+  - package-ecosystem: pip
+    directory: /tui-py
+    schedule:
+      interval: weekly

.gitignore

@@ -1,6 +1,13 @@
 # Dependencies
 node_modules/
 
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+
 # Build output
 dist/
 src-tauri/target/

.oxlintrc.json

@@ -57,23 +57,6 @@
       "rules": {
         "no-restricted-imports": "off"
       }
-    },
-    {
-      "files": ["tui/**/*.ts", "tui/**/*.tsx"],
-      "rules": {
-        "no-restricted-imports": [
-          "error",
-          {
-            "paths": [
-              {
-                "name": "react",
-                "importNames": ["default"],
-                "message": "Not needed with react-jsx transform. Use named imports."
-              }
-            ]
-          }
-        ]
-      }
     }
   ]
 }

README.md

@@ -9,11 +9,13 @@
 [![Rust](https://img.shields.io/badge/rust-1.77.2%2B-orange?logo=rust)](https://www.rust-lang.org/)
 [![React](https://img.shields.io/badge/react-19-61DAFB?logo=react&logoColor=white)](https://react.dev/)
 [![Tauri](https://img.shields.io/badge/tauri-v2-24C8D8?logo=tauri&logoColor=white)](https://v2.tauri.app/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Textual](https://img.shields.io/badge/textual-0.80%2B-5A4FCF?logo=textualize&logoColor=white)](https://textual.textualize.io/)
 [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)](https://github.com/delexw/claude-code-trace/releases)
 
 **Claude Code Trace** is a **Claude Code session log viewer** for local JSONL files stored in `~/.claude/projects/`.
 
-Browse, tail, and inspect Claude Code conversations in real time. Claude Code Trace renders Claude Code JSONL session files as readable conversations with expandable tool calls, token counts, timestamps, MCP tool call detection, and live log tailing. It also helps you find sessions by user message. It runs as a **native desktop app** for macOS, Linux, and Windows, or a **web app**.
+Browse, tail, and inspect Claude Code conversations in real time. Claude Code Trace renders Claude Code JSONL session files as readable conversations with expandable tool calls, token counts, timestamps, MCP tool call detection, and live log tailing. It also helps you find sessions by user message. It runs as a **GUI app** for macOS, Linux, and Windows, a **Web app** or a **TUI**.
 
 Use Claude Code Trace when you want to:
 

bin/cctrace.mjs

@@ -154,17 +154,19 @@ switch (mode) {
       });
     }
 
-    // Build TUI if needed, wait for backend, then start TUI
-    execSync("npm run build", { stdio: "inherit", cwd: resolve(root, "tui") });
-    // wait-for-backend.mjs lives in bin/, not tui/
+    // Install Python dependencies, wait for backend, then start TUI
+    execSync("pip install -r requirements.txt --quiet", {
+      stdio: "inherit",
+      cwd: resolve(root, "tui-py"),
+    });
     execSync("node wait-for-backend.mjs", {
       stdio: "inherit",
       cwd: resolve(root, "bin"),
     });
 
-    const tui = spawn("node", ["dist/tui/src/cli.js"], {
+    const tui = spawn("python3", ["main.py"], {
       stdio: "inherit",
-      cwd: resolve(root, "tui"),
+      cwd: resolve(root, "tui-py"),
     });
 
     tui.on("exit", (code) => {

package.json

@@ -12,7 +12,7 @@
     "preview": "vite preview",
     "tauri": "tauri",
     "dev:web": "tauri dev -- -- --web",
-    "dev:tui": "tauri dev -- -- --headless & cd tui && npm run build && node wait-for-backend.mjs && node dist/tui/src/cli.js",
+    "dev:tui": "tauri dev -- -- --headless & pip install -r tui-py/requirements.txt -q && node bin/wait-for-backend.mjs && python3 tui-py/main.py",
     "lint": "oxlint && cargo clippy --manifest-path src-tauri/Cargo.toml",
     "fmt": "oxfmt && cargo fmt --manifest-path src-tauri/Cargo.toml",
     "fmt:check": "oxfmt --check && cargo fmt --manifest-path src-tauri/Cargo.toml --check",

specs/00-overview.md

@@ -22,7 +22,7 @@ graph TB
     subgraph Frontends
         TAURI["Tauri Desktop\n(WebView + IPC)"]
         WEB["Browser\n(Vite / HTTP)"]
-        TUI["Terminal UI\n(Ink / React)"]
+        TUI["Terminal UI\n(Python / Textual)"]
     end
 
     JSONL -->|"FS events"| RUST
@@ -44,7 +44,7 @@ graph TB
 | HTTP API           | `src-tauri/src/http_api.rs` | REST + SSE for browser and TUI                   |
 | Frontend Converter | `src-tauri/src/convert.rs`  | Internal → JSON-serialisable display types       |
 | Web Frontend       | `src/`                      | React components, hooks, keyboard navigation     |
-| TUI                | `tui/`                      | Ink/React terminal rendering                     |
+| TUI                | `tui-py/`                   | Python / Textual terminal rendering              |
 | Shared             | `shared/`                   | Types, project tree builder, format helpers      |
 | CLI Launcher       | `bin/cctrace.mjs`           | Mode selector (desktop / web / tui / headless)   |
 
@@ -91,7 +91,7 @@ flowchart LR
 | 03  | [03-state-management.md](03-state-management.md)   | AppState, session cache, SSE broadcast                              |
 | 04  | [04-http-api.md](04-http-api.md)                   | REST endpoints, SSE contract, Tauri IPC mirror                      |
 | 05  | [05-frontend-web.md](05-frontend-web.md)           | React hooks and components (web/desktop)                            |
-| 06  | [06-tui.md](06-tui.md)                             | Terminal UI (Ink/React), keyboard routing, windowing                |
+| 06  | [06-tui.md](06-tui.md)                             | Terminal UI (Python / Textual), shared list base, async populate    |
 | 07  | [07-data-types.md](07-data-types.md)               | Shared TypeScript types, Rust serialisation                         |
 | 08  | [08-session-lifecycle.md](08-session-lifecycle.md) | End-to-end session loading, live update, truncation                 |
 | 09  | [09-subagent-linking.md](09-subagent-linking.md)   | Four-phase subagent linking algorithm                               |