Documentation

Everything you need to install, configure, and use cc-term.

Installation

cc-term runs on macOS (Intel and Apple Silicon). The installer handles all dependencies via Homebrew.

curl -fsSL https://ttyd.ink/install | bash

Or clone and run manually:

git clone https://github.com/xbsura/cc-term.git
cd cc-terminal
./install.sh

What gets installed

• Homebrew packages: bash, tmux, vim, bat, btop, duf, tig, lazygit, qrencode, python@3
• iTerm2 (via Homebrew Cask)
• Tmux Plugin Manager (TPM) with tmux-resurrect and tmux-continuum
• Everything installs under ~/.cc-term — your existing shell/tmux/vim configs are untouched.

Quick Start

# Launch default session
cc-term

# Launch a named session
cc-term myproject

# Enable remote access (inside a session window)
cc-term -r

# List all sessions
cc-term -ls

Requirements

Sessions

Sessions are persistent tmux sessions managed by cc-term. Each session opens in a new iTerm2 tab.

# Open default "main" session
cc-term

# Open named session
cc-term myproject

# Open multiple sessions at once
cc-term api,frontend,worker

# List sessions
cc-term -ls

# Delete a session
cc-term -delete myproject

Remote Access

Share any session over the web. Access from your phone, tablet, or another computer.

Enable remote for the current session

Inside a cc-term tmux window, run:

cc-term -r

This registers the current session with the proxy server and gives you a URL + QR code.

Enable remote from outside tmux

# Register a specific session
cc-term myproject -r

# Register all sessions
cc-term -r

# Register with password protection
cc-term myproject -r -u admin -p secret

# Register as private (hidden from aggregate page)
cc-term myproject -r -s

Status indicator

When a session is registered for remote access, the tmux status bar shows a green R on the far right. If the tunnel connection drops, it turns red.

Stop remote access

cc-term -server -stop

Keyboard Shortcuts

The tmux prefix key is Ctrl+A (not the default Ctrl+B).

Web UI shortcuts

Windows & Panes

Each session can have multiple windows (tabs in the tmux status bar) and each window can have multiple panes (splits).

# Inside tmux (after Ctrl+A prefix):
# c     - create new window
# n     - next window
# p     - previous window
# ,     - rename window
# &     - kill window

# Splitting:
# F5    - horizontal split
# F6    - vertical split

AI Providers

cc-term can manage AI provider API keys for Claude Code and other tools.

# List providers
cc-term -p -ls

# Add a new provider
cc-term -p -new -api https://api.example.com -key sk-xxx

# Edit a provider
cc-term -p -edit <id> -key sk-newkey

# Delete a provider
cc-term -p -delete <id>

Self-Hosting

By default, cc-term tunnels through ttyd.ink. You can run your own proxy server instead.

# Start local proxy server
cc-term -server --port 9999

# Register sessions against your local server
cc-term -r --local

# Or specify a custom host via environment variables
export CC_PROXY_HOST=my-server.example.com
export CC_PROXY_PORT=443
export CC_PROXY_PROTOCOL=https
cc-term -r

Server CLI

CLI Reference

File Structure

~/.cc-term/
├── bin/                  # Executables
│   ├── cc-term           # Main CLI
│   ├── _cc-term-core     # Core logic
│   ├── cc-proxy-server.py
│   ├── cc-tunnel-client.py
│   └── ...
├── config/
│   ├── bash_profile      # Isolated bash config
│   ├── tmux.conf          # Tmux config
│   ├── vimrc              # Vim config
│   ├── remote/            # Remote server HTML
│   └── ttyd/              # Web terminal UI
├── providers/             # Provider scripts
├── providers.json         # AI provider config
├── run/                   # PID files, runtime state
├── state/                 # Session state
├── tmux/plugins/          # TPM plugins
└── venv/                  # Isolated Python venv

Uninstall

cc-term is fully self-contained. To remove it:

# Stop any running processes
cc-term -server -stop

# Remove the installation directory
rm -rf ~/.cc-term

# Remove the symlink
rm -f $(brew --prefix)/bin/cc-term