Metadata-Version: 2.4
Name: claude-code-terminal
Version: 0.2.7
Summary: TUI dashboard for managing Claude Code, Codex, and shell sessions via tmux
Project-URL: Homepage, https://github.com/phinease/claude-code-terminal
Project-URL: Repository, https://github.com/phinease/claude-code-terminal
Project-URL: Issues, https://github.com/phinease/claude-code-terminal/issues
Author: Phinease
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: libtmux>=0.37.0
Requires-Dist: textual<=8.1.1,>=0.85.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: textual-dev>=1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Claude Code Terminal (CCT)

[![Version](https://img.shields.io/badge/version-v0.2.5-0A7B83)](https://pypi.org/project/claude-code-terminal/)
[![PyPI](https://img.shields.io/pypi/v/claude-code-terminal)](https://pypi.org/project/claude-code-terminal/)
[![Python](https://img.shields.io/pypi/pyversions/claude-code-terminal)](https://pypi.org/project/claude-code-terminal/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![README EN](https://img.shields.io/badge/README-English-blue)](README.md)
[![README ZH](https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87-red)](README.zh-CN.md)
[![README FR](https://img.shields.io/badge/README-Fran%C3%A7ais-green)](README.fr.md)

> TUI dashboard for managing Claude Code, Codex, and shell sessions via tmux.

image

## Languages

- [English](./README.md)
- [简体中文](./README.zh-CN.md)
- [Français](./README.fr.md)

## ✨ Features

- Built-in Claude Code / Codex / Shell session support
- In-dashboard permission handling
- Vim-style modal operation
- Working / Idle / Waiting / Stopped / Auto / Shell state display
- High-performance line-level rendered preview (TerminalView) with Strip caching
- Interactive cursor overlay in snapshot preview
- Raw-stdin interactive input path with `Shift+Enter` / `Alt+Enter` newline compatibility
- Preview cache and single-flight refresh to reduce repeated preview work
- Typing-aware smart refresh: suppresses preview updates during rapid input
- Preview truncation hint when pane history exceeds the current 1000-line preview window
- WAITING auto-focus with FIFO queue processing
- Per-session Auto Pilot
- Home page, session panel toggle, and smoother session deletion flow
- Read-only diagnostics for cursor stability and live-session latency profiling
- macOS notifications

## 🚀 Installation

### Quick Install (recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/phinease/claude-code-terminal/main/install.sh | sh
```

### Via pipx

```bash
pipx install claude-code-terminal
```

### Via pip

```bash
pip install claude-code-terminal
```

### Upgrade

```bash
pipx upgrade claude-code-terminal
```

or:

```bash
pip install -U claude-code-terminal
```

### Prerequisites

- Python >= 3.11
- tmux (`brew install tmux` / `apt install tmux`)

## ▶️ Usage

```bash
cct
```

## ⌨️ Keybindings

### Normal Mode

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate sessions |
| `n` | New session |
| `r` | Rename session |
| `i` | Enter Interactive mode |
| `a` / `d` | Approve / Deny permission request |
| `1`-`9` | Select numbered permission option |
| `p` | Toggle Auto Pilot |
| `c` | Select mode (text copy) |
| `Ctrl+\` | Toggle session panel |
| `Ctrl+x` | Delete session |
| `q` | Quit |

### Interactive Mode

All keystrokes pass through directly to the selected agent session.

| Key | Action |
|-----|--------|
| `Ctrl-]` | Exit to Normal mode |
| `Ctrl+\` | Toggle session panel |
| `Shift+Enter` | Newline (kitty protocol terminals) |
| `Alt+Enter` | Newline (legacy terminals) |
| Mouse click on session list | Switch session |

## 🪟 Preview Behavior

- Normal and interactive preview both keep a bounded 1000-line window.
- When older content is omitted from the preview window, CCT shows a truncation banner below the preview.
- Waiting detection and Auto Pilot still use plain `capture-pane`, independent of preview truncation.

Environment variables:

- `CCT_PREVIEW_HISTORY_LINES`
  Current implementation clamps this to at least `1000`.
- `CCT_INTERACTIVE_PREVIEW_HISTORY_LINES`
  Current implementation also clamps this to at least `1000`.
- `CCT_USE_LEGACY_INTERACTIVE_VIEW=1`
  Disables the interactive cursor overlay path and falls back to the legacy interactive preview behavior.
- `CCT_OUTPUT_DEBOUNCE_MS`
  Drain output debounce interval in ms (default `16`, ≈60fps).
- `CCT_TYPING_SUPPRESS_MS`
  During interactive mode, defer preview refreshes while the user is typing faster than this threshold (default `0`, disabled).
  The historical default `80` was calibrated to a pre-optimisation ~80 ms capture cost; since the one-shot capture path (~6 ms) there is nothing to coalesce.
  Set to `80` to restore the legacy behaviour if needed.

## 🧪 Diagnostics

- `python tests/e2e_cursor_scope.py`
  Verifies cursor position and mixed ASCII / Chinese input stability.
- `python tests/e2e_latency_scope_existing_sessions.py`
  Reuses current live tmux sessions in read-only mode to profile preview, list, and polling costs.
- `python tests/e2e_interactive_latency.py`
  Measures interactive mode latency: drain debounce, capture, parse, render, and end-to-end refresh cycle.

## 🖥️ Interface

```
+----------------------------------------------------------------+
| Vibe · Agent Dashboard                                         |
+----------------------------------------------------------------+
| Sessions           | Preview: frontend-refactor (claude)        |
|--------------------|---------------------------------------------|
| * frontend-refactor| > Analyzing src/components/Header.tsx...    |
|   proj/frontend    |                                             |
| * api-fix          |   I'll update the Header component to       |
|   proj/backend     |   use the new theme variables.              |
| ! test-fix         |---------------------------------------------|
|   proj/tests       | ! Permission: execute `npm test`            |
| o data-migration   |   [a:Allow] [d:Deny]                        |
|   proj/migration   |                                             |
+--------------------+---------------------------------------------+
| NORMAL — i:Interactive  n:New  a/d:Allow/Deny  p:Pilot         |
+----------------------------------------------------------------+

Status icons: * Working  ! Waiting  o Idle  x Stopped
```

## 📝 Notes

- The current interactive preview is still tmux snapshot based, not a full terminal-buffer renderer.
- v0.2.2 replaced RichLog with a line-level TerminalView (ScrollView + render_line), reducing preview render cost by ~61%. Combined with drain debounce reduction and typing-aware smart refresh, end-to-end interactive latency dropped from ~145ms to ~65ms.
- v0.2.5 fixed interactive cursor off-by-one offset caused by trailing newline in tmux capture-pane output. Session names now truncate with ellipsis instead of disappearing when the panel is narrow.

## 🛣️ Roadmap

| Version | Goal |
|---------|------|
| v0.2 (current) | Claude Code / Codex / Shell sessions, Auto Pilot, bounded preview, TerminalView performance, cursor fix, diagnostics |
| v0.3 | More tools (Aider/Open Claw), session groups, fuzzy search |
| v0.4 | Web version (textual-web), diff view, Docker isolation |

## 📄 License

[MIT](LICENSE)
