Metadata-Version: 2.4
Name: claude-code-terminal
Version: 0.2.0
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>=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)

[![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.

## 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](./README.md)
- [简体中文](./README.zh-CN.md)
- [Français](./README.fr.md)

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

```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
```

### 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.

## 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](LICENSE)
