claude-code-terminal 0.2.7

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

Claude Code Terminal (CCT)

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

Languages

• English
• 简体中文
• Français

✨ 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)

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

Via pipx

pipx install claude-code-terminal

Via pip

pip install claude-code-terminal

Upgrade

pipx upgrade claude-code-terminal

or:

pip install -U claude-code-terminal

Prerequisites

• Python >= 3.11
• tmux (brew install tmux / apt install tmux)

▶️ Usage

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