Skip to main content
A session is an isolated cloud machine running Claude Code. Each session has a memorable label like “brave-tiger-1234” for easy reference.

​
Creating Sessions

Start a new session with: 
catty new
This will:
  1. Create a new cloud machine
  2. Upload your current directory (see Workspace Sync)
  3. Start Claude Code
  4. Connect your terminal

​
Options

FlagDescription
--no-uploadSkip uploading current directory
--no-sync-backDisable real-time file sync back to local
--api <url>Override API URL (for development)
--agent codexUse Codex instead of Claude Code (experimental)

​
Examples

# Standard session with workspace upload
catty new

# Session without uploading files
catty new --no-upload

# Session without sync-back
catty new --no-sync-back

​
Session Labels

Each session gets a memorable label like:
  • brave-tiger-1234
  • swift-falcon-5678
  • clever-dolphin-9012
Labels are easier to remember than UUIDs and are used for all session operations.

​
Listing Sessions

View all your sessions: 
catty list
Output shows:
  • Session label
  • Status (running, stopped)
  • Creation time

​
Reconnecting

Sessions persist until explicitly stopped. Reconnect to an existing session: 
catty connect brave-tiger-1234
Use Tab completion with the session label for convenience.

​
Reconnect Options

FlagDescription
--no-sync-backDisable sync-back for this connection
# Reconnect without sync-back
catty connect brave-tiger-1234 --no-sync-back

​
Stopping Sessions

Stop a running session: 
catty stop brave-tiger-1234
Stopping a session destroys the cloud machine. Any files not synced back will be lost.