claude-code-terminal 0.2.1

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
• Snapshot preview with ANSI rendering
• 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
• 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.

🧪 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