claude-code-terminal 0.2.0

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.

What's New Since v0.1.0

• Codex and Shell session support
• Auto Pilot and WAITING auto-focus queue
• Home page, session panel toggle, and session deletion flow polish
• Interactive raw-stdin path with Shift+Enter / Alt+Enter compatibility
• Interactive cursor overlay in snapshot preview
• Major multi-session performance work: preview caching, bounded 1000-line preview window, truncation hint, prioritized polling, and in-place SessionList updates
• New read-only diagnostics for cursor stability and live-session latency profiling

Languages

• English
• 简体中文
• Français

Features

• In-dashboard permission handling
• Vim-style modal operation
• Working / Idle / Waiting / Stopped / Auto / Shell state display
• Snapshot preview with ANSI rendering
• Interactive cursor overlay in snapshot preview
• Preview truncation hint when pane history exceeds the current 1000-line preview window
• WAITING auto-focus with FIFO queue processing
• Per-session Auto Pilot
• macOS notifications
• Built-in Claude Code / Codex / Shell support

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

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.

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.

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.
• Recent performance work reduced preview-path overhead, session-list remount churn, and all-session polling load.

Roadmap

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

License

MIT