How It Works

Catty connects your local terminal to Claude Code running in isolated cloud machines. Here's how all the pieces fit together.

Architecture

The catty CLI on your machine communicates with the Catty API to provision isolated session machines in the cloud. Each session machine runs Claude Code in a PTY. Your terminal connects directly to Claude Code via WebSocket, streaming input and output in real-time. File changes sync back to your local directory, and workspaces are periodically saved to cloud storage for persistence.

Components

Data Flow

Session Creation

1. catty new calls the API
2. API provisions a cloud machine
3. Machine starts and reports ready
4. CLI zips your workspace (respecting .gitignore)
5. Workspace uploads to session machine
6. WebSocket connection established
7. Claude Code spawns in a PTY
8. Terminal I/O streams bidirectionally

File Sync-Back

1. Claude modifies a file in /workspace
2. File watcher detects the change
3. Change sent over WebSocket as JSON message
4. CLI validates path (security check)
5. File written to your local directory

Cloud Persistence

1. Session saves workspace every 30 seconds
2. Tarball uploaded to cloud storage
3. When you run catty download:
   • API generates presigned URL
   • CLI downloads directly from cloud storage
   • Extracts to your local directory

Security