Quick start

CodeRoam keeps your Claude Code chats in step across your Windows PCs, so you can pick up a conversation wherever you sit down. Everything is encrypted on your PC first and stored in a private repository on your own GitHub account. There is no CodeRoam server and no account to create with us.

You need: Windows 10 or 11, a free GitHub account, and about five minutes.

Set up your first PC

1. Run CodeRoam-Setup.exe and click Install and continue. One window installs CodeRoam (for your Windows user only, with no administrator rights) and then carries straight on into the steps below. If Windows shows a blue "Windows protected your PC" box, choose More info, then Run anyway. CodeRoam isn't signed with a paid certificate.
2. Create your private vault repository. Setup opens GitHub with the name and Private already filled in. Click Create repository.
3. Connect to GitHub. Your browser opens and GitHub asks you to create a private app on your own account (one click) and then to choose your vault repository and click Install & Authorize. The app belongs to you, and only this PC uses it.
4. Choose your vault from the list.
5. Set a passphrase of 14 or more characters. Four or five random words works well. Save it in your password manager. If you lose it, nobody can recover your vault, including us.
6. Wait for the first sync. The first upload can take a few minutes if you have a lot of chats.

CodeRoam now lives in the notification area by the clock. Right-click its icon for the menu.

Add another PC

1. Install CodeRoam and start setup, exactly as above.
2. At Create your private vault, skip ahead. You already have one.
3. After you connect, choose the same vault repository and enter the same passphrase.
4. If your folders live in different places on this PC (for example a different Windows user name), CodeRoam offers to match your folders for you.

Chats from your other PCs download and appear in Claude Code's /resume list for the matching folder.

Everyday use

You don't have to do anything. CodeRoam syncs a few seconds after a chat changes, and checks for other PCs' changes every couple of minutes.

• Tray icon dot: none = up to date, blue = syncing, grey = paused, amber = needs setup, red = needs attention.
• Your chats (double-click the icon) lists every chat from every folder. Search, then Resume in a folder to carry on any chat anywhere.
• Pause syncing and Sync now are in the tray menu.

Finish on one PC and let the icon settle before continuing the same chat on another. Syncing is quick, but it isn't instant.

User guide

What CodeRoam syncs

Claude Code saves each conversation as a file (.jsonl) in ~/.claude/projects/<folder>/. CodeRoam syncs exactly those chat files and nothing else.

Chats can contain anything that was shown during a conversation: file contents, command output, and any secrets that appeared on screen. That is why they are encrypted before they leave your PC.

How it works

• Each chat is cut into pieces of up to 32 MB. Each piece is encrypted separately, so there is no limit on chat size, and a chat that grows only uploads and downloads its newest piece.
• The encrypted pieces are stored in your vault: a private GitHub repository. The vault always holds a single, current snapshot, so it never accumulates history.
• Your PC's own files are always the master copy. The vault is just how PCs hand chats to each other.
• Nothing is ever deleted by syncing. If you delete a chat on one PC, it stays on your others and in the vault.

The tray menu

Right-click the CodeRoam icon by the clock.

Notifications

CodeRoam stays quiet while it syncs. It shows a popup only when something needs your attention: a new chat arrives from another PC, two PCs changed the same chat and it was merged, or something is wrong. Everyday updates to chats you already have never pop up, because they happen all the time while you work. The status line in the tray menu always shows what's happening. Turn the new-chat popups off with Notify me about new chats in the tray menu.

Your chats (the library)

Claude Code's /resume only lists chats started in the folder you are in. Your chats shows every chat on this PC, from every folder and every PC.

• Search by title, folder or id. Tick Also search inside chats and press Enter to search the full text of every chat.
• Resume in a folder… lets you continue a chat in any folder you choose. CodeRoam places a copy of the chat in that folder's history and opens a terminal there running claude --resume.
• Copy resume command copies the same command, for use in your own terminal.
• Resume in VS Code... opens a folder in Visual Studio Code to carry on the chat there. A folder picker appears with the chat's own folder (as matched to this PC) already selected, so one OK is enough, or you can choose a different folder, exactly like Resume in a folder... does for the terminal. The chat is also placed in that folder's history, so Claude Code's VS Code extension can resume it there. It uses the code command when it can find it, and VS Code's own link otherwise.
• Show file reveals the chat file in Explorer.

Resuming a chat in a different folder keeps the original too. Both copies are the same chat, and whichever you continue becomes the up-to-date one.

Matching folders between PCs

Claude Code files each chat under the folder it was started in. If the same project lives at a different path on another PC, for example C:\Users\alex\Projects\app on one and D:\Code\app on the other, tell CodeRoam:

Other PC: C:\Users\alex\Projects → This PC: D:\Code

Matching works on whole folder paths, so C:\Users\Rob will never accidentally match C:\Users\RobW. When you set up a second PC, CodeRoam looks for chats whose folders don't exist here and suggests rules automatically for different Windows user names. Add or change rules any time from Match folders.

Chats whose folder isn't on this PC are still synced and listed in Your chats (marked folder not on this PC), so you can resume them in any folder.

If two PCs changed the same chat

If you continue the same chat on two PCs before they have synced, CodeRoam merges them:

• Chats are a tree of messages, so keeping every message from both copies keeps both branches.
• The merged chat has everything from both PCs, in time order, and both PCs end up with the identical file.
• The two originals are saved in the conflicts folder, so nothing is ever lost.
• You'll see a "Chats merged" notification.

In the rare case that two copies differ too much to merge, the newer one is kept and the other is saved in the conflicts folder.

Updating CodeRoam

Run the newer CodeRoam-Setup.exe. If CodeRoam is already installed and set up on that PC, it goes straight to a short Update screen: no GitHub, no passphrase, no setup. It swaps in the new version, restarts CodeRoam, and syncing carries on where it left off. Your vault, sign-in and settings are untouched. To change vault or sign in again instead, run the installer with /setup, or use Setup and reconnect in the tray menu.

Pausing, quitting and uninstalling

• Pause stops syncing but keeps CodeRoam running. Quit closes it.
• Uninstall from Settings → Apps. It removes the program and offers to remove this PC's saved sign-in and settings. Your chats and your vault are never touched.
• To stop using CodeRoam entirely, also delete the vault repository and the private app on GitHub (Settings → Developer settings → GitHub Apps).

Good to know

• Size: GitHub recommends keeping a repository under a few GB. Years of heavy use is usually well under that. If your vault grows too large, create a new vault and set up your PCs again.
• GitHub limits: CodeRoam uses GitHub's API politely. If GitHub asks it to slow down, it waits and carries on.
• Several PCs: every PC you set up creates its own private app on your GitHub account. That's deliberate: you can revoke one lost PC without affecting the rest.
• Changing your passphrase: the passphrase is the key to the vault and can't be changed in place. To change it, create a new vault repository and set up each PC again.
• Different monitors and scaling: CodeRoam looks sharp at any Windows display scaling and follows Windows light and dark mode.

Security and privacy

In short

• Your chats are encrypted on your PC before they are uploaded. GitHub only ever holds scrambled data.
• The key comes from your passphrase, which is never stored or sent anywhere.
• CodeRoam talks only to GitHub (github.com and api.github.com). It has no server, no accounts, no analytics and no telemetry.
• Its GitHub access is limited to one repository that you choose.

What is encrypted

Every piece of every chat, and the list that says which chats exist, is encrypted with AES-256 and authenticated with HMAC-SHA256 (encrypt-then-MAC). The key is derived from your passphrase with PBKDF2-SHA256 at 600,000 iterations. Each piece's authentication tag also covers which piece it is, so a stored piece cannot be swapped for another, replaced, or edited without CodeRoam noticing. Data is checked before anything is decrypted or written to your PC.

What GitHub can and can't see

What is kept on your PC

• Your passphrase is not stored. The key derived from it is saved in %LOCALAPPDATA%\CodeRoam, protected with Windows DPAPI, so it can only be read by your Windows user on that PC.
• The GitHub sign-in token is stored the same way. It expires after 8 hours and renews itself.
• Anything running as you on that PC can read both, just as it can read your chat files. If your PC is compromised, so are your chats.

How CodeRoam connects to GitHub

CodeRoam creates a private GitHub App on your own GitHub account (using GitHub's official "app manifest" flow). The app:

• is private: only you can install it;
• has one permission, Contents: read and write, on only the repository you select. If GitHub's install page was left on "All repositories", CodeRoam notices, will not continue, and takes you to the page to limit it;
• belongs to you. You can see it, and delete it, at GitHub → Settings → Developer settings → GitHub Apps.

During setup, CodeRoam briefly listens on 127.0.0.1 (your own PC, ports 47655-47664) to receive GitHub's redirect. It stops listening as soon as setup finishes.

Protection against tampering

• A wrong passphrase is rejected up front.
• Tampered, swapped or damaged stored data is rejected and nothing on your PC is overwritten.
• A vault that has been rolled back to an older state is detected, and nothing is changed.
• A downloaded chat must match its recorded fingerprint before it replaces anything.

Someone with write access to your vault repository (for example, who has taken over your GitHub account) can't read or forge chats, but could delete files or roll the vault back. Protect your GitHub account with two-factor authentication.

If you lose your passphrase

Nobody can recover the vault: not CodeRoam, not GitHub. Your chats on your PCs are unaffected. To start again, create a new vault repository and set up each PC with a new passphrase.

What to do if you think your vault was exposed

1. Delete the vault repository, and the private apps, on GitHub.
2. Set up a new vault with a new passphrase.

Because chats are encrypted with a key derived from a strong passphrase, an exposed vault is only readable by someone who also guesses your passphrase. A long, random passphrase makes that impractical.

Licence and third-party notices

• CodeRoam is released under the MIT licence (the LICENSE file in the package).
• Inter typeface, © The Inter Project Authors, SIL Open Font License 1.1. The licence is included with CodeRoam.
• CodeRoam is an independent tool. It is not made, endorsed or supported by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic and are named here only to describe what CodeRoam works with.

Troubleshooting

CodeRoam's tray icon shows a red dot and the menu's top line explains what's wrong. The log (tray menu → Open log) has the detail.

Messages and what to do

Common questions

My browser shows a "127.0.0.1" or "localhost" error during setup. During sign-in, CodeRoam briefly listens on your own PC (127.0.0.1) to receive GitHub's reply. You see an error if you reopen or refresh a GitHub tab from an earlier attempt, after CodeRoam has finished with it. It's harmless. Close the old tabs, go back to the CodeRoam window and click Connect to GitHub again, then use only the newest tab.

I deleted my vault repository and made a new one with the same name, and CodeRoam can't see it. GitHub treats a recreated repository as a different repository, even with the same name, and the private app's access belonged to the old one. At Choose your vault, click Add or change repositories, tick the new repository and Save, then Refresh list.

I deleted CodeRoam's private app on GitHub. What now? Nothing special. Open Setup and reconnect (or run CodeRoam-Setup.exe again). CodeRoam notices the app is gone, creates a fresh one and walks you through the two GitHub clicks. Your vault and chats are not affected.

A chat from my other PC doesn't show in /resume. Claude Code lists a folder's chats only when you open it in the same folder path. Use Your chats to see everything, or Match folders if the folder lives somewhere else on this PC.

Windows says "Windows protected your PC" when I run the installer. CodeRoam isn't signed with a paid code-signing certificate. Choose More info, then Run anyway.

My antivirus flags CodeRoam. CodeRoam is a small unsigned program that writes files in your profile and talks to GitHub, which some tools treat cautiously. You can check that your download is the genuine file by comparing its SHA-256 with the one shown on the download page.

The first sync is slow. It uploads everything once. Large chats are sent in 32 MB pieces, and after that only what changed is sent. You can keep working while it runs.

I deleted a chat on one PC and it came back. Syncing never deletes. Delete the chat on each PC. To remove it from the vault, delete the vault and start a new one.

I set up the same PC twice and now see two private apps on GitHub. That's harmless. Delete the older one at GitHub → Settings → Developer settings → GitHub Apps.

I lost my passphrase. Your chats on your PCs are fine. The vault can't be recovered. Create a new vault repository and set up each PC again with a new passphrase.

CodeRoam isn't in the notification area. Windows sometimes hides it. Click the small arrow by the clock, and drag the icon out to keep it visible.

Where things live on your PC

Still stuck?

Open the log from the tray menu. It never contains your passphrase or your chat text. Then open an issue in the project repository with the relevant lines.

Releases

Every minor release gets a name, in alphabetical order, from a theme that fits what CodeRoam does: carrying your chats between places. Patch releases (1.0.1, 1.0.2 ...) keep the name of their minor release. The current name is shown in the About box, the installer and the top of this guide.

Theme 1: Ways to roam (1.0 to 1.25)

Next themes, saved for later

When the alphabet runs out, the next theme starts again at A with the next major version.

Theme 2: Famous bridges (2.0 to 2.25). A bridge connects two places, like CodeRoam connects two PCs. Akashi, Brooklyn, Charles, Dragon, Erasmus, Forth, Golden Gate, Humber, Iron, Jacques Cartier, Kintai, London, Millau, Nanpu, Oresund, Pont Neuf, Quebec, Rialto, Sydney Harbour, Tower, Union, Verrazzano, Waterloo, Xihoumen, Yichang, Zakim.

Theme 3: Navigation stars (3.0 to 3.25). Travellers steered by them. Altair, Betelgeuse, Capella, Deneb, Elnath, Fomalhaut, Gacrux, Hadar, Izar, Jabbah, Kochab, Lesath, Mizar, Nunki, Okab, Polaris, Quasar, Rigel, Sirius, Thuban, Unukalhai, Vega, Wezen, Xamidimura, Yildun, Zubenelgenubi.

(The Q entries are the weak spot in both lists and can be swapped before we get there.)

Backpack (1.1)

1.1.1: the VS Code button is now Resume in VS Code..., matching Resume in a folder.... It shows the folder picker every time, with the chat's own folder pre-selected, so you can carry a chat on in a different folder.

1.1.0: Open in VS Code in the chat library: open a chat's project folder in Visual Studio Code, with the chat ready for Claude Code's extension to resume.

Amble (1.0)

1.0.11: the MIT licence is added and included in every package.

1.0.10: the Update screen shows the release name of the version you have and the one you are moving to.

1.0.9: release names. The About box, installer and guide now show the release name.

1.0.8: quieter notifications. Existing chats updating no longer pop up; only new chats do, at most once every five minutes, with a Notify me about new chats switch in the tray menu. Merges and problems always notify.

1.0.7: updating skips setup. Running a newer installer on a PC where CodeRoam is already set up shows a short Update screen: no GitHub, no passphrase.

1.0.6: limits access to the vault. If the private app was installed on all your repositories, setup explains why that is too broad and takes you to the page to limit it.

1.0.5: the CodeRoam icon on the taskbar and in Alt+Tab, at the right sizes.

1.0.4: fixed large chats that never finished their first upload.

1.0.3: copes with a deleted private app, and with browser tabs left over from earlier attempts.

1.0.2: reuses the private app already created on a PC, and clearer wording on GitHub's install step.

1.0.1: real upload progress ("Uploading... 142 of 384 MB"), smaller batches, finishing setup early while the first upload continues in the tray app, and the version stamped into the program.

1.0.0: first release. Encrypted two-way sync of Claude Code chats through your own private GitHub repository, tray app, chat library, folder matching, merging, and a one-window installer.