CCS - Coding CLI Session Manager

A terminal UI and CLI for browsing, managing, and resuming sessions across multiple coding assistants: Claude Code, Codex, and opencode -- locally and on remote servers.

Original idea and first version created by: Varun Wahi

CCS provides a unified interface for all your coding CLI sessions with session previews, tmux integration, profiles, themes, bulk operations, and remote server management over a secure WebSocket protocol.

Sessions List

Session View with Launch Modal

Launch Mode

Themes

Supported CLIs

CLI	Sessions	Resume	New	Badge
Claude Code	~/.claude/projects/*.jsonl	Yes	Yes	[C]
Codex	~/.codex/state_*.sqlite	Yes	Yes	[X]
opencode	~/.local/share/opencode/opencode.db	Yes	Yes	[O]

CCS auto-detects installed CLIs and their sessions. Each session shows a badge indicating which CLI it belongs to.

Requirements

• Python 3.9+
• uv (Python package manager)
• At least one supported CLI installed: Claude Code, Codex, or opencode
• Optional: tmux (for background session management)
• Optional: git (for repository info in session details)

Install

git clone https://github.com/mike-plivo/ccs.git
cd ccs
./install.sh

The install script uses uv tool install to create an isolated virtualenv with all dependencies (including remote server support). The ccs command is added to your PATH automatically.

# Minimal install (no remote server dependencies)
./install.sh --minimal

# Upgrade after git pull
git pull && ./install.sh

# Uninstall
uv tool uninstall ccs

Manual install

uv tool install .[remote]     # Full install with remote support
uv tool install .             # Minimal (no remote server deps)

Usage

ccs                  # Launch interactive TUI
ccs list             # List all sessions (all CLIs)
ccs resume <id|tag>  # Resume a session
ccs providers        # Show detected CLIs and status
ccs help             # Show all commands

CLI Commands

ccs list                               List all sessions (all CLIs)
ccs scan [-n|--dry-run]                Rescan all sessions
ccs resume <id|tag> [-p <profile>]     Resume session
ccs resume <id|tag> --claude <opts>    Resume with raw CLI options
ccs new <name>                         New named session
ccs new -e [name]                      Ephemeral session (auto-deleted on exit)
ccs pin/unpin <id|tag>                 Pin/unpin a session
ccs tag <id|tag> <tag>                 Set tag on session
ccs tag rename <oldtag> <newtag>       Rename a tag
ccs untag <id|tag>                     Remove tag
ccs delete <id|tag>                    Delete a session
ccs delete --empty                     Delete all empty sessions
ccs info <id|tag>                      Show session details
ccs search <query>                     Search sessions
ccs export <id|tag>                    Export session as markdown
ccs profile list|info|set|new|delete   Manage profiles
ccs providers                          List CLI providers and status
ccs theme list|set                     Manage themes
ccs tmux list                          List running tmux sessions
ccs tmux attach <name>                 Attach to tmux session
ccs tmux kill <name>                   Kill a tmux session
ccs tmux kill --all                    Kill all ccs tmux sessions
ccs remote add <name> <host:port> --pair <code>   Pair with remote server
ccs remote list                        List configured remotes
ccs remote remove <name>               Remove a remote
ccs remote test <name>                 Test remote connectivity
ccs remote enable/disable <name>       Toggle remote on/off
ccs remote repin <name>                Re-pin TLS fingerprint
ccs serve [--port N] [--bind addr]     Start remote server
ccs serve pair                         Generate new pairing code
ccs serve clients                      List paired clients
ccs serve revoke <id|--all>            Revoke client(s)

TUI Keyboard Shortcuts

Sessions List

Key	Action
Up/Down	Navigate sessions
g / G	Jump to first / last
PgUp/PgDn	Page up / down
Right	Open Session View
Enter	Resume session
n	New named session (prompts CLI choice)
e	New ephemeral session (prompts CLI choice)
p	Toggle pin
t / T	Set / remove tag
d	Delete session
D	Delete all empty sessions
C	Toggle continuation sessions
A	Toggle subagent sessions
k / K	Kill tmux session / all
Space	Mark / unmark session
u	Unmark all
s	Cycle sort mode
F	Cycle CLI filter
/	Search / filter (@host to filter by remote)
S	Rescan all sessions
r	Refresh
R	Remote server manager
P	Profile manager
H	Change theme
m	Open menu
?	Help

Session View

Key	Action
Tab	Switch Info / Preview pane
Up/Down	Scroll focused pane
Enter	Resume session
i	Send text to tmux
k	Kill tmux session
p	Toggle pin
t / T	Set / remove tag
d	Delete session
Left / Esc	Back to sessions list

Continuation Sessions

When Claude Code runs out of context, it creates a new continuation session with a summary of the previous conversation. CCS detects these automatically and hides them by default to keep the session list clean.

• Hidden by default -- only root/parent sessions are shown with a +N badge indicating how many continuations exist
• Toggle with C -- press C to show/hide continuation sessions; when visible, they appear grouped under their parent with a ↳ prefix and dimmed text
• Search includes all -- searching always includes continuation sessions regardless of the toggle
• Orphan promotion -- if a continuation's parent was deleted, it's promoted to a standalone session
• Bulk archive -- use the menu (m) to delete all continuation sessions at once

Subagent Sessions

Claude Code spawns subagent sessions for background tasks (suggestions, summaries, parallel work). These can accumulate into hundreds of entries. CCS detects them automatically (session ID starts with agent-) and hides them by default.

• Hidden by default -- the header shows (+N subagent hidden, A to show)
• Toggle with A -- press A to show/hide subagent sessions
• Search includes all -- searching always includes subagent sessions regardless of the toggle
• Server-side filtering -- remote servers skip subagent sessions during scan for faster transfer

Tmux Expert Mode

Tmux Expert allows launching a session with ephemeral environment variables (e.g. AWS credentials, API keys). The variables are set inline on the CLI command and are never stored anywhere.

• Available in the Launch modal and the menu (m) as Tmux Expert
• Enter one KEY=VALUE per line (Ctrl+D to confirm, Esc to cancel)
• Variables are passed directly to the claude process and inherited by all its subcommands
• On detach (Ctrl+B, D), the tmux session is automatically killed to avoid preserving sensitive env vars

Profiles

Profiles store launch configurations and are CLI-aware -- each profile targets a specific CLI (Claude, Codex, or opencode) and only shows relevant options for that CLI. When launching a session with a CLI that doesn't match the active profile, CCS prompts you to select an appropriate profile.

Create and manage profiles from the TUI (P) or CLI:

ccs profile list           # List all profiles
ccs profile info <name>    # Show profile details
ccs profile set <name>     # Set active profile
ccs profile new <name>     # Create new profile
ccs profile delete <name>  # Delete a profile

Remote Server Management

CCS can connect to remote servers running ccs serve to list, manage, and attach to coding CLI sessions over a secure WebSocket protocol. No SSH dependency required.

How it works

1. Start the server on the remote machine:

   ccs serve --port 7433

   On first run, it generates a TLS certificate and displays a one-time pairing code.

2. Pair from your local machine:

   ccs remote add dev1 192.168.1.50:7433 --pair ABCD1234

3. Use CCS normally -- remote sessions appear grouped by host in the TUI, separated by ── dev1 ── lines. All operations work: browse, attach, create new sessions, kill, tag, pin, and search with @dev1 filter.

Security

• TLS encryption with self-signed certificates and fingerprint pinning (trust-on-first-use)
• JWT access tokens (1-hour expiry) with automatic refresh
• Refresh tokens (90-day expiry) hashed with bcrypt server-side
• One-time pairing codes (5-minute expiry, single use)
• Client management -- list and revoke paired clients at any time

Managing remotes

Press R in the TUI to open the Remotes modal, or use CLI commands:

ccs remote list              # List all configured remotes
ccs remote test dev1         # Test connectivity
ccs remote enable/disable dev1   # Toggle without removing
ccs remote remove dev1       # Remove a remote
ccs remote repin dev1        # Re-pin TLS fingerprint after cert change

Server administration

ccs serve pair               # Generate a new pairing code
ccs serve clients            # List all paired clients
ccs serve revoke <id>        # Revoke a specific client
ccs serve revoke --all       # Revoke all clients

Configuration

All CCS data is stored in ~/.config/ccs/:

File	Purpose
sessions.json	Session metadata (tags, pins, ephemeral flags)
session_cache.json	Scan cache for faster startup
ccs_profiles.json	Profile configurations
ccs_active_profile.txt	Currently active profile
ccs_theme.txt	Selected theme
remotes.json	Remote server configurations (tokens, fingerprints)
clients.json	Paired clients (server-side only)
serve_secret	JWT signing secret (server-side only)
tls/server.crt, tls/server.key	TLS certificate and key (server-side only)

CCS reads session data from each CLI's storage location (see Supported CLIs above). CCS metadata (tags, pins, profiles) is stored separately and does not affect any CLI's configuration.

Important: Deleting a session in CCS permanently deletes the underlying session data. This action cannot be undone. As a safeguard, all delete operations require typing DELETE in uppercase to confirm.

License

MIT