Catty

Run Claude Code sessions remotely.

Catty spins up isolated Claude Code environments on-demand, syncs your local workspace in both directions, and gives you a seamless terminal experience - as if Claude Code was running locally.

Quick Start

# Install (macOS and Linux)
npm install -g @diggerhq/catty

# Log in (required once)
catty login

# Start a session in your project directory
cd your-project
catty new

That's it. Your files sync to the remote environment, and any changes Claude makes sync back to your local directory in real-time.

Why Catty?

• No local setup - Claude Code runs in an isolated cloud environment
• Two-way sync - Your workspace uploads automatically, and changes sync back to your local directory in real-time
• Native terminal feel - Full PTY streaming means colors, vim, interactive prompts all work perfectly
• Isolated sessions - Each session runs in its own environment, fully isolated

Commands

catty login                  # Authenticate (required before first use)
catty logout                 # Remove stored credentials
catty new                    # Start Claude Code session (uploads current directory)
catty new --no-upload        # Start without uploading workspace
catty new --no-sync-back     # Disable syncing remote file changes back to local
catty connect <label>        # Reconnect to an existing session
catty list                   # List your sessions (shows labels)
catty stop <label>           # Stop a session by label
catty version                # Print version number

Requirements

• macOS (Intel or Apple Silicon) or Linux (x64 or ARM64)
• Node.js 16+

What Gets Synced

When you run catty new, your current directory is zipped and uploaded. The following are automatically excluded:

• .git/ directory
• node_modules/
• Python virtual environments (.venv, venv)
• .env files
• Anything in your .gitignore

Maximum upload size: 100MB

Changes made remotely sync back to your local directory automatically. Use --no-sync-back to disable this.

How It Works

1. catty login authenticates you via browser (one-time)
2. catty new creates an isolated environment
3. Your current directory is zipped (respecting .gitignore) and uploaded
4. Claude Code starts with your workspace
5. Terminal I/O streams over WebSocket - you interact as if it's local
6. File changes sync back to your local directory automatically
7. When done, catty stop or Ctrl+C terminates the session

Troubleshooting

"Not logged in" error: Run catty login first.

Session won't start: Check your internet connection and try again. If the problem persists, try catty logout then catty login.

Files not appearing: Check that your workspace is under 100MB and files aren't gitignored.

Roadmap

• Progress indicators - Progress bars for uploads and other long operations
• Documentation site - Comprehensive docs at docs.catty.dev
• Multi-key support - Pool of API keys for handling load spikes

Development

See AGENTS.md for architecture details, deployment instructions, and contribution guidelines.

License

MIT