ChatRelay Sync between devices
Upload, download and keep everything in step.
#Push and pull
- Push uploads the conversations of a project that changed since the last sync. Push all does every project.
- Pull downloads what's new. It always starts with a dry run that lists every file it would write and every path rewrite. Nothing is written until you confirm.
#Auto-sync
When Auto-sync is on:
- Claude Code: hooks in
~/.claude/settings.jsonrun ChatRelay when a Claude Code session starts (pull) and ends (push). - Codex: Codex has no such hook. The desktop app watches Codex's sessions and uploads a changed conversation about a minute after it goes quiet. Every 15 minutes (starting 20 seconds after launch) it also downloads new ones (skipped while Codex is running).
- Uploads that failed because you were offline are queued and retried.
You can turn auto-sync on or off in Settings, in the tray menu, or with chatrelay hooks install|uninstall.
#Status dots
| Dot | Meaning | What to do |
|---|---|---|
| Green | Synced | Nothing |
| Yellow / orange | Changes on this PC not uploaded yet | Push, or wait for auto-sync |
| Red | Last sync failed | Open Logs for the reason |
| Grey | Never synced | Push it once |
| Hollow circle | No project identity yet (not linked) | Push it (a link is created) or Link it to the project from the other PC |
| Crossed-out circle | Sync is off for this project on this PC | Turn sync on on the project's page, if you want it synced again |
#Keep a project on this PC only
Some projects should never leave a PC, for example client work that must stay on one machine. On the project's page click Don't sync (or hover a project in the Simple view and click don't sync). From then on nothing from that project is uploaded, and it is not downloaded automatically (auto-sync hooks, background sync, "Upload everything"). A manual Pull still works. The project shows a crossed-out status dot and "sync off on this PC"; Turn sync on undoes it. From the command line: chatrelay exclude <dir> (--remove to undo, no folder to list them).
#Backups
Every write is preceded by a backup in ~/.chatrelay/backups/<timestamp>-<what>/. Open Backups (or chatrelay backups) to see them, and Restore one to put every file back exactly as it was. A restore also removes files that the change had created.
#Logs
Logs shows everything ChatRelay did, with errors highlighted, and a button that copies an error report.
#Tray menu
Push now · Pull now · Auto-sync on/off · Last sync status · Open · Quit.