Sync-Back

Sync-back automatically copies file changes from the remote session to your local machine in real-time. When Claude creates or modifies a file, it appears locally within seconds.

How It Works

sequenceDiagram
    participant Claude as Claude Code
    participant Exec as Session Machine
    participant WS as WebSocket
    participant CLI as Catty CLI
    participant FS as Local Files

    Claude->>Exec: Writes file
    Exec->>Exec: fsnotify detects change
    Exec->>WS: FileChange message
    WS->>CLI: Receives message
    CLI->>CLI: Validates path
    CLI->>FS: Writes file locally

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:

catty new
catty connect <label>

Disabling Sync-Back

For new sessions:

catty new --no-sync-back

When reconnecting:

catty connect brave-tiger-1234 --no-sync-back

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

Use sync-back for live collaboration with Claude.

Use download/sync to retrieve files after disconnecting or if sync-back was disabled.

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.