Your workspace is the /workspace directory in a session. It starts with your uploaded files and is automatically saved to the cloud throughout the session.
Upload on Session Start
When you run catty new, your current directory is zipped and uploaded:
cd my-project
catty new
# → Uploading workspace...
# → Workspace uploaded (2.3 MB)
What Gets Uploaded
Your entire current directory, except:
- Files matching patterns in
.gitignore
- Default exclusions (see below)
Default Exclusions
Always excluded, regardless of .gitignore:
.git/
node_modules/
__pycache__/
*.pyc
.venv/
venv/
.env
.DS_Store
*.log
Add patterns to your .gitignore to exclude additional files.
Upload Limits
| Limit | Value |
|---|
| Maximum size | 100 MB |
- Add large files to
.gitignore
- Or use
--no-upload and clone your repo in the session:
catty new --no-upload
# Then in Claude: git clone https://github.com/...
Skipping Upload
Useful when:
- Workspace is too large
- You want an empty session
- You’ll clone a repo instead
Cloud Persistence
Workspaces are automatically saved to cloud storage throughout the session.
How It Works
- First save: ~10 seconds after session start
- Periodic saves: Every 30 seconds
- Final save: When session stops
What Gets Saved
Everything in /workspace except:
.git/
node_modules/
__pycache__/
.venv/
venv/
.cache/
.npm/
.yarn/
Why This Matters
- Recovery: Download your work even after stopping a session
- Backup: Get a snapshot of a running session
- Resilience: Don’t lose work if sync-back was disabled or you disconnected
Downloading Workspaces
To a New Directory
catty download brave-tiger-1234
# Creates: ./brave-tiger-1234/
To a Specific Path
catty download brave-tiger-1234 ./my-backup
As a Tarball
catty download brave-tiger-1234 --format tar.gz
Syncing to Current Directory
Overwrite your current directory with the remote workspace:
# Preview first
catty sync brave-tiger-1234 --dry-run
# Then sync
catty sync brave-tiger-1234
catty sync overwrites local files. Use --dry-run first.
See Also
