How It Works
Supported Operations
| Operation | Description |
|---|---|
| Create | New files appear locally |
| Modify | Changed files are updated |
| Delete | Deleted files are removed locally |
Enabled by Default
Sync-back is enabled when you run:Disabling Sync-Back
For new sessions:When to Disable
- Working on a large codebase where constant file writes are distracting
- Using version control and prefer to pull changes manually
- Testing or debugging sync-back issues
With sync-back disabled, use
catty download or catty sync to retrieve files.Security
Sync-back includes multiple 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.
No Executables
File permissions are normalized (no executable bits set unexpectedly).
Sync-Back vs Download/Sync
| Feature | Sync-Back | Download/Sync |
|---|---|---|
| Timing | Real-time | On-demand |
| Direction | Remote → Local | Remote → Local |
| Requires connection | Yes | No |
| Overwrites local | Yes | Yes |
Troubleshooting
Changes Not Appearing
- Check you didn’t use
--no-sync-back - Ensure Claude is editing files in
/workspace - Verify you’re in the correct local directory
Files in Wrong Location
You may have reconnected from a different directory. Sync-back writes to your current working directory, not where you originally created the session.Conflicts
Sync-back is one-way (remote to local). If you edit a file locally while Claude edits it remotely, the remote version overwrites your local changes. Best practice: Let Claude do the work during a session. Review when done.See Also
- Workspaces - Upload and cloud persistence
- catty download - Download on demand
- catty sync - Sync on demand