WorkBuddy session sync — continue on any device

Last updated 2026-09-17 · MIT licensed · free for personal self-hosting

WorkBuddy is the most project-oriented agent in the list: it keeps a project inventory in workbuddy.db (the workspaces table), so syncing carries both your sessions and your projects into the shared pool.

Where WorkBuddy keeps its sessions

Item Value
Data directory ~/.workbuddy-ai (legacy builds: ~/.workbuddy)
Sessions projects/<project-slug>/*.jsonl
Database workbuddy.db — sessions holds conversations, workspaces holds the project list (path + last_opened_at)

Connecting it

  1. Open the setup help page, pick WorkBuddy, and download the client package (server address pre-filled).
  2. On first run, execute install-deps.bat (Windows) or ./install-deps.sh (macOS / Linux).
  3. Register with the generated command — your workspace API key is already filled in. The client starts as HERMES_SYNC_AGENT=workbuddy.
  4. Restart WorkBuddy.

First start pulls incrementally; an empty server gets a full push to complete the pairing; then it syncs every 5 minutes.

Behaviour worth knowing

  • Append-only — sessions are appended to as JSONL; existing entries are never rewritten.
  • Split copies are merged — if a session's files were scattered across several project directories (a moved project folder will do it), reads merge them instead of showing you half a conversation.
  • Running sessions are skipped — a session held by a lock file is left alone for that round and picked up on the next one, which is what keeps writes from colliding.
  • A session written from the server needs a WorkBuddy restart to appear in its list — that is WorkBuddy's own load timing, not a failed sync. The web console shows it immediately if you want to confirm.
  • Timestamp units are handled — the adapter converts between seconds and milliseconds, so nothing lands in 1970.

The project pool

WorkBuddy's workspaces table goes into the shared project pool (with an identity sidecar so the same project lines up across machines), which is why project cards stay consistent. One rule to know: drive roots and the user home never enter the pool — such a path would turn one card into a catch-all for every session beneath it, and it means a different directory on every machine.

Across devices, across agents

One machine at the office, one at home, both connected to the same workspace: sessions and projects live in the pool, and you can continue the same project in Hermes or OpenCode as well.