Cross-device sync

Cross-device sync keeps your Plexus settings, workspaces and projects the same on every machine you sign in on — and it sends nothing until you have read a list of everything that would leave this computer and said yes.

It needs a Plexus account, because the account is the thing your machines have in common, and it needs a plan — either your own, or a seat on an organization's. And it is off on every machine, including the second one: a laptop syncs nothing until somebody sitting at that laptop turns it on there and reads the list for themselves.

What travels

Four things, and nothing else:

• Your global settings — every setting you changed from its default, except the fifteen listed below. That includes the free text you typed: your AI code-review instructions, your review-and-fix and commit-message prompts, your list of files to copy into new worktrees.
• Your workspaces — each one's name, description, position in the sidebar, and which one is the default.
• Your projects — each one's name, position, base branch, which workspace it belongs to, the host/owner/name slug of every git remote it has, and its origin remote's clone URL with any password stripped out.
• Workspace- and project-level overrides of the same settings, so a per-repository review prompt arrives attached to the right repository.

Your keyboard shortcuts travel too — they are ordinary settings, so one machine's rebinding becomes every machine's.

What stays on this machine

Fifteen settings are classified as machine-local. They describe this computer rather than a preference about how Plexus behaves, so they are never sent, and they are refused on arrival — another machine cannot write them here even if it tried.

Beyond settings, none of this is synced and none of it can be: your sessions and everything on one (names, branches, activity, reserved ports, transcripts), your worktrees, the lifecycle scripts you wrote and the ones a repository commits in .plexus/hooks.json, your pull request records and review comments, everything in your OS keychain (your GitHub, Bitbucket and Plexus credentials), every absolute path on your disk, and your code — no file contents, no file names, no diffs, no commit messages.

The settings that govern how hooks run do travel, because they are ordinary settings. The scripts themselves never leave the machine or the repository they live in.

Everything under Settings → Appearance stays here too, along with your imported custom notification sound: those are per-machine preferences that were never layered settings to begin with.

Turning it on

Open Settings → Sync. If you are signed in and your plan covers sync, the page shows the two settings and a button:

1. Press Show me what would be sent… — or turn Sync this machine on, which opens the same setup rather than switching anything on. The setup opens in the side panel. Nothing has been written yet.
2. Read the list. A line at the top counts what is there — settings, workspaces, projects sent, settings staying here — and below it every item is spelled out: every setting key and the exact value you gave it, every workspace and project name and description, every repository slug and every clone URL that would go. A key the app would send but the setup did not show is treated as a defect, and a test fails the build over it.
3. Turn off the switch beside any workspace or project you would rather keep off your account. Excluding a workspace excludes every project inside it, and nothing about an excluded project crosses — not its name, not its repository, not the fact that it exists.
4. Press Send this and turn on sync. It sits in a bar pinned to the bottom of the side panel, beside Cancel, so it stays in reach however far down the list you have scrolled.

The list is split into sections, each with its count on its heading:

• Workspaces and projects — open, with the send switches.
• Settings — collapsed. Click the heading to expand it.
• Staying on this machine — collapsed.
• Your account already holds some of this — only when it does; see below.

A collapsed section still holds every row it counts; collapsing only saves you scrolling, it never changes what is sent.

Three parts of the setup are worth slowing down for.

Worth a second look appears at the top when one of your values arms something on the other machine rather than just recording a preference. It is never folded away: unlike the sections below it, it has no collapsed state. Three settings qualify: Run scripts committed to the repository (a repository's committed scripts start running on every machine this follows you to), Let the agent work without asking permission, and When you remove a session set to Delete immediately.

Staying on this machine is the other half of an honest preview: the machine-local settings you hold an override for, listed by name with the reason beside each. A path setting is checked again at the moment it would leave, so if an older version of Plexus stored something absolute in Where to create session folders, Files and folders to copy or Write ports to file, it is held back and named here instead of shipping your username and your folder layout.

Cancel changes nothing. It closes the setup, leaves Sync this machine off and sends nothing.

If the page shows something else, it is one of two answers rather than an error. Signed out, it offers Sign in to Plexus and no lock icon — nothing is being withheld for money there, there is simply no account for your machines to have in common. Signed in without a plan that covers sync, it names what the feature does and offers See plans.

If your account already holds settings

Turning sync on for the second machine is where a decision appears. The setup adds a section, Your account already holds some of this, with three ways forward as cards to choose between:

With Merge selected, the section also lists Both sides have a value for these — every setting the two disagree about, with this machine's value and your account's side by side, each with its own switch. The two replacing choices have nothing to settle key by key, so the list is not shown for them.

Both replacing choices are undoable, and by the person who made them. Take the account's writes this machine's state into the version history before it overwrites anything; Keep this machine's overwrites a version that is already in that history, because every version your account has held is kept there. Either way the state that was replaced is one Restore away.

After it's on

Sync runs quietly in the background. There is no progress bar and nothing to press.

• Two machines that changed different settings both keep their changes. Sync sends the keys this machine actually touched rather than a whole document, so there is no conflict to resolve and nothing asks you to choose.
• The same setting changed on both resolves to whichever change reached your account last.
• Plexus checks on its own at three moments: when it starts, when you switch back to its window, and a couple of seconds after you change anything that syncs. Check for changes every (minutes) is the shortest gap between any two of those, not a schedule — a check that would fall too soon after the last one is skipped, and what you changed goes with the next one instead.
• Sync now checks immediately, ignoring that floor, and postpones the next automatic check rather than racing it. It is the button to press when you have just changed something and want to watch it land.
• A machine that can't reach the internet keeps working exactly as it did. So does one whose check failed: the failure is a quiet line on this page, never a toast, and a background check can never sign you out.
• Those same three moments also fetch your organization's workspaces, the settings it manages and the prompts it publishes, if you are in one that shares them, so a workspace an administrator creates or withdraws — or a setting they enforce, or a prompt they publish or roll back — reaches you without restarting the app. That half runs whether or not Sync this machine is on — see Shared workspaces, Managed settings and Prompts your organization publishes.

What your account holds lists each of the two things sync tracks — Settings, and Workspaces and projects — with the version your account is on, how many changes are still waiting to be sent from here, when this machine last checked, and which of your machines wrote the current version.

The two settings

Both are per machine on purpose: turning sync off on one laptop never turns it off on another.

Reviewing and changing what you send

What this machine sends… opens the same list at any time, right on the page, with the same per-workspace and per-project switches — the button reads Hide what this machine sends while it is open, and Done closes it too. It shows only what goes and what stays: there is no choice of mode here, because that decision belongs to turning sync on. This is the door that stays open — the setup appears once, and everything after it crosses without asking.

Excluding something you had already synced retracts it: the next sync removes that workspace or project from your account, and your other machines drop it on their next check. A machine that has a session in that project is the exception — see Deleting things — where the project stays put and simply stops being synced.

Anything you exclude shows up under Not synced on the Sync page, with Sync it again beside it if you change your mind. That list outlives the thing it names on purpose, so a project you deleted here can still be un-excluded later.

Version history

Your account keeps the last twenty versions of each of the two things it tracks. Press History on either row to read them.

Each row says which of your machines wrote it, when, how it came to exist — Saved from a device, Replaced by a device, or Restored from an earlier version — and how many items it holds. The machine name is a snapshot, so it still reads "MacBook Pro" after you have signed that laptop out.

Restore puts one back, and it does so by writing it forward as a new version rather than rewinding the counter. Three consequences, all of them the point:

• Nothing is lost. The version you restored from is still in the list.
• A restore is itself undoable — restore the version before it.
• Every other machine you sign in on picks the restore up on its next check, through the ordinary path. There is nothing to do on the other machines.

The version your account currently holds has no Restore button; it is marked current instead.

Projects from your other machines

A project you added on another computer appears in this one's sidebar, in the workspace it belongs to, marked Not on this machine. It is an ordinary row rather than a warning — the only fact it reports is that a repository you have elsewhere is not checked out here — and it names the repository as well as the project, because two workspaces can both hold a project called api.

If this machine already has a checkout whose remotes match, Plexus links the two silently and you never see the row at all. When it can't, the row offers three answers — the first two as the small buttons on the row itself, the third in its ⋯ menu:

• Locate… — you already have the repository somewhere. Point at the folder and Plexus links it, so the project's settings and its place in the tree follow. If the folder's remotes don't match the synced ones — which is what a fork looks like — Plexus says so and links it anyway rather than refusing.
• Clone… — you don't have it. This opens the usual Add repository dialog with the clone URL already filled in; you choose where it goes, and the new checkout is linked the moment the clone finishes.
• Stop showing … here — you don't want it on this machine at all. The row goes away here and nothing changes on any of your other devices.

When several repositories on this machine could be the one, Plexus asks rather than guessing. Choose a matching repository…, also in the ⋯ menu, lists each candidate with its path and the remotes it has in common. It is offered whether or not there are several — the dialog says plainly when nothing on this machine matches.

A project whose clone URL never crossed — a repository with no git remote configured — arrives with Clone… disabled and Locate… as the only way to link it.

When a folder moves

A project whose folder has been moved or removed is marked on its own row, with a tooltip naming the path it is looking for. Nothing is deleted: its settings, its sessions and its synced identity are all kept, and the row goes back to normal the moment the folder does. A drive that is merely unplugged is the case this exists for.

Workspaces your organization shares

If you are in an organization that shares workspaces, those arrive on this machine too — but not through sync, and the distinction is deliberate rather than an implementation detail.

Sync carries your account: your settings, your workspaces, your projects. An organization's workspaces are the organization's, so each of your machines fetches them from the organization directly, on its own. Three things follow from that.

• They are never sent from here. An organization's names and repository lists are not written into your account, do not appear in the preview of what this machine sends, and are not counted in either version number on this page.
• They arrive whether or not sync is on. Turning Sync this machine off does not stop them; they need only that you are signed in and hold a seat. Signing out stops them, along with everything else on your account.
• They cannot be excluded, and they do not need to be. The way to stop receiving one is to leave it, which is in the workspace's ⋯ menu and never refused.

The projects an organization attaches also appear as Not on this machine rows, and they read like the ones above with one difference: they offer Clone only. There is no Locate… and no candidate picker, so cloning one can never re-parent a checkout that is already part of your own account. See Shared workspaces.

The same shape holds for the settings an organization manages: an enforced value never enters your settings at all — it sits above them — and a recommended one is planted on each of your machines by the organization rather than carried between them by sync.

Deleting things

Deleting a workspace or a project on one machine deletes it on the others, on their next check — with deliberate exceptions.

A workspace or project that holds a session on the receiving machine is never deleted there. The row stays exactly where it is, with its sessions and its worktrees; it simply stops being the synced one. A delete on one laptop must not be able to destroy work in progress on another. A session counts whether it is running or archived — an archived session still owns a branch, and may still own a worktree, and the Archived drawer is where you expect to find it.

Two more rows are never removed by a delete made somewhere else: your default workspace, and your only workspace. Plexus refuses both of those deletions when you make them here, and an instruction arriving from another machine is not allowed to do what a local one is forbidden to do.

Renaming, reordering and moving a project between workspaces all travel like any other change.

Turning it off

There are two ways off, and they are different.

Sync this machine → Off stops this computer sending and receiving. Your account keeps everything it holds, your other machines are unaffected, and turning it back on resumes without asking you to review the list again — the account still holds exactly what you approved. Nothing on this machine is changed or removed.

Stop syncing and forget what we hold deletes everything sync has stored on your account: both resources, every value, and all twenty retained versions. It asks you to confirm. Your settings, workspaces and projects on this machine are untouched and Plexus keeps working exactly as it does now — and so are your other machines' copies, until they next check in.

Because your account then holds nothing, turning sync on again starts over: the setup opens and you approve what goes, exactly as you did the first time. The Not on this machine rows go too — there is no longer an account holding those projects to deliver them from.

One thing deliberately survives a forget: your Not synced list. A workspace or project you said must never leave this machine stays excluded, because that decision outlives the data it was protecting — you do not have to remember to make it again.

If you sign out

Nothing is sent or received while this machine is signed out, and your settings, workspaces and projects here are untouched — the app behaves exactly as it does for somebody who never signed in at all. Settings → Sync says so and offers the way back in. Sign in again and it resumes where it left off; your account kept everything in the meantime.

Signing a device out from Signed-in devices never deletes what that device synced. The account keeps the data and the version history keeps the name, which is the point: revoking a stolen laptop is a security action, and it must not take your configuration history with it.

If your plan lapses

A cancelled plan runs to the end of the period you already paid for, and everything on this page works normally until that day. After it, sync stops: nothing is sent, nothing is received, and Settings → Sync goes back to naming what the feature does and how to get it. Nothing on any of your machines is changed or removed by a lapse, and nothing is deleted from your account either — start a plan again and your machines catch up on the next check.

One thing keeps working after a lapse, on purpose: the delete. Stop syncing and forget what we hold stays on the page under that locked panel, and still empties your account, however long ago you stopped paying. A plan buys the storing and the exchanging; it has never bought the right to get your data back out, and holding what you already gave us behind a subscription is not something this app will do. Deleting your Plexus account removes everything sync held as well, if you would rather go that way.

What leaves your device

When sync is on, and only then:

1. The key and value of every global setting you changed from its default, where that setting is portable — including free text you typed, like your review prompts.
2. The relative, in-tree paths you configured — Where to create session folders, Files and folders to copy, Write ports to file. Each is re-checked as it leaves, and a value that is not relative and inside the project is held back and named in the preview, so none of them is ever a path on your machine.
3. Each workspace's name, description, position and whether it is the default.
4. Each project's name, position, base branch, and which workspace it is in.
5. Each project's repository slugs — github.com/codedwords/plexus, for every remote it has. Never a path.
6. Each project's clone URL — the origin remote's fetch URL, with any password removed, and on https the username removed with it.
7. Workspace- and project-level overrides of the same portable settings, keyed to an identifier generated on your machine.
8. A name and a stable identifier for each of your devices, so the version history can say which machine made a change. The name is the one you were shown and accepted when you signed in.
9. Up to twenty previous versions of all of the above, kept until you use Stop syncing and forget what we hold or delete your account.
10. The time of each change and which of your devices made it.

Items 3 to 7 do not cross for anything you excluded, and excluding a workspace excludes every project inside it.

The Privacy Policy states the same list in full, alongside everything else about what does and does not leave your machine.

Related

• Your Plexus account — signing in, devices, and signing out.
• Plans, seats and billing — the plan sync comes with.
• Settings — the full settings reference, including which layer each one is set at.
• Shared workspaces — the workspaces an organization hands you, and why they are not part of this.
• Managed settings — the settings an organization recommends or enforces, which arrive the same way.
• Prompts your organization publishes — the prompt templates an organization publishes, which arrive the same way and never enter your own library.
• Core concepts — workspaces, projects and sessions.