Skip to main content
Catty provides bidirectional file synchronization between your local directory and the remote session.

​
Upload (Local to Remote)

When you run catty new, your current directory is automatically zipped and uploaded to the remote session.

​
What Gets Uploaded

Your entire current directory, except:
  • Files matching patterns in .gitignore
  • Default exclusions (see below)

​
Default Exclusions

These patterns are always excluded, regardless of .gitignore: 
.git/
.git/**
node_modules/
node_modules/**
__pycache__/
*.pyc
.venv/
venv/
.env
.DS_Store
*.log
Add patterns to your .gitignore to exclude additional files from upload.

​
Upload Limits

LimitValue
Maximum size100 MB
Uploads per session1
If your workspace exceeds 100 MB, reduce its size by adding exclusions to .gitignore or use --no-upload and manually copy files.

​
Skipping Upload

Start a session without uploading: 
catty new --no-upload
Useful when:
  • Your workspace is too large
  • You want an empty session
  • You’ll clone a repo in the session instead

​
Sync-Back (Remote to Local)

Changes made by Claude in the remote /workspace directory are automatically synced back to your local directory in real-time.

​
How It Works

​
Supported Operations

OperationDescription
CreateNew files appear locally
ModifyChanged files are updated
DeleteDeleted files are removed locally

​
Security

Sync-back includes safety measures:

Path Validation

Rejects absolute paths and directory traversal (../) attempts.

Workspace Scoped

Only changes under /workspace are synced.

Local Boundary

Writes are confined to your current working directory.

Real-time

Changes appear immediately as Claude makes them.

​
Disabling Sync-Back

Disable for new sessions: 
catty new --no-sync-back
Disable when reconnecting: 
catty connect brave-tiger-1234 --no-sync-back
Disabling sync-back means you’ll need to manually retrieve any files Claude creates or modifies.

​
Protocol Details

Sync-back uses WebSocket text frames with JSON messages:

​
File Change Message (Server to Client)

{
  "type": "file_change",
  "path": "src/main.go",
  "action": "write",
  "content": "cGFja2FnZSBtYWluLi4u"
}
FieldDescription
typeAlways "file_change"
pathRelative path from workspace root
action"write" or "delete"
contentBase64-encoded file content (for writes)

​
Enable Sync-Back Message (Client to Server)

{
  "type": "sync_back",
  "enabled": true
}

​
Acknowledgment (Server to Client)

{
  "type": "sync_back_ack"
}

​
Best Practices

Use .gitignore to exclude large files, build artifacts, and dependencies. These can be regenerated in the remote session.
The default behavior ensures your local copy stays in sync with Claude’s changes. Only disable if you have a specific reason.
Make sure your .gitignore excludes sensitive files like .env with secrets. These are excluded by default, but verify your specific setup.
Since files sync in real-time, use Git to track changes and revert if needed. Commit your work before starting a session.