cc-session-control 0.4.0

TUI manager for Claude Code sessions and Remote Control

cc-session-control

TUI manager for Claude Code sessions and Remote Control.

CLI command: csctl

Features

• Sessions Tab — View, resume, terminate, and delete Claude Code sessions across all projects
• Remote Control Tab — Start/stop RC servers per project, toggle auto-start, show running/stopped/dead states
• Cleanup Tab — Prune empty/short sessions, sweep orphan artifact directories

Built with urwid.

UI language: Simplified Chinese (notifications and status text). CLI output is in English.

Requirements

• Python 3.12+
• Claude Code CLI installed and authenticated
• tmux (for Remote Control management)
• Linux / WSL (macOS support is partial — /proc-based liveness detection is Linux-only)

Installation

Coming soon to PyPI. The package is not published yet. Until the first release lands, install from GitHub (see Latest master build below). Once published, the commands below will work.

Install the latest published release:

uv tool install cc-session-control
# or
pipx install cc-session-control

Upgrade later with uv tool upgrade cc-session-control (or pipx upgrade cc-session-control).

Latest master build

Until the package is on PyPI — or to try the newest master before it is released — install from GitHub:

uv tool install --reinstall git+https://github.com/dzshzx/cc-session-control.git

csctl manages the Claude Code state on the machine where it is installed: the local ~/.claude, local tmux, and local workspace. Install it separately on each machine whose sessions you want to manage. For working on the code instead of using it, see CONTRIBUTING.md.

Usage

# Open TUI
csctl

# Remote Control management (no TUI)
csctl rc status          # Show all projects and RC status
csctl rc add .           # Add current project to RC list and start
csctl rc add myproject   # Add by name
csctl rc rm myproject    # Remove and stop
csctl rc up              # Start all listed projects
csctl rc stop all        # Stop all RC servers
csctl rc list            # Show auto-start list

# Session cleanup
csctl prune                          # Dry run: show stats
csctl prune --max-prompts 1 --apply  # Delete sessions with ≤1 prompt

# Options
csctl --workspace ~/projects   # Override workspace root
csctl --version

Configuration

Environment Variable	Default	Description
CSCTL_WORKSPACE	~/workspace	Workspace root directory
CSCTL_RC_SESSION	rc	tmux session name for RC servers
CSCTL_RC_STAGGER	2	Seconds between starting RC servers
XDG_CONFIG_HOME	~/.config	Config directory base

RC auto-start list is stored at $XDG_CONFIG_HOME/csctl/rc-enabled.

License

MIT