Workspaces Overview

The Workspaces view is a full-screen overlay that shows every workspace your account tracks — on this device, on every host you've pushed to, and on every other device signed into the same account. It's reached from the sidebar Workspaces button under Automations.

Before this view existed, the sidebar only showed workspaces on the current device. Once you started pushing workspaces to a remote host or working on more than one machine, there was no surface for "show me everything I have, everywhere." This is that surface.

Opening the Overview

• Sidebar — click the Workspaces button under Automations in the left sidebar.
• Close — Escape or the back arrow.

Device Sections

Workspaces are grouped into device sections in a fixed order:

1. This device — workspaces on the machine you're using.
2. Configured hosts — every SSH host registered in Settings → Hosts, in the order they appear there.
3. Sibling devices — every other device signed into the same account, regardless of whether it's currently online.
4. Removed host — orphan bucket for workspaces whose host row has been deleted (so rows never silently disappear).

Each section header shows the device name, workspace count, and a "filtered" pill if any of the bucket's workspaces are currently hidden by an active filter.

Project Grouping

Within a device section, workspaces belonging to the same project cluster under a subtle project header (folder icon · project name · count) once a project has two or more workspaces in that bucket — so a repo's main checkout and its per-branch worktrees read as one project instead of unrelated cards. Projects with a single workspace stay in a flat grid with no header.

Grouping uses a stable project identity, not the folder path: the same repository cloned at different paths on different devices or hosts still groups together, while two unrelated repositories that happen to share a folder name do not. Each card also carries a repo root or worktree badge so the project's root checkout is distinguishable from its branch worktrees at a glance.

Repo Root Protection

Codemux treats a git repository as one connected unit — the root checkout and all of its branch worktrees share the same history. The root checkout (your project on its default branch) is protected:

• It carries a repo root badge, and its action menu offers Close workspace… (detach it from the sidebar, files left untouched on disk) instead of Delete worktree…. You can't accidentally delete the whole repository the way you'd remove a throwaway worktree.
• Pulling a repo root to another device brings the repository over once and lands it cleanly, so the root and its worktrees stay on one shared history rather than drifting into an independent copy.

If you pulled a project to a device before this behavior existed, its root may instead show an amber standalone copy warning chip — a full, disconnected copy of the repo that will drift from the real history over time. Its action menu has a Reconcile copy… item that detaches the card without touching the files on disk (it refuses if the copy has uncommitted changes or unpushed commits, so nothing is ever lost), after which you can Pull project to land a clean, connected repo root. Reconciling never deletes your work — it just removes the disconnected card so the project reads cleanly again.

Filters

A sticky filter bar at the top of the overview lets you narrow the list:

A Clear chip appears whenever any non-default filter is set.

Per-Row Actions

Each workspace card has a hover-revealed ⋯ action menu:

• Open workspace — switches to it and closes the overlay.
• Copy branch name — clipboard copy.
• Rename… — inline prompt + save.
• Push to host… — submenu of every configured host. Opens a confirmation dialog before the push runs (see Safety guardrails below).
• Pull back to this device — only appears for workspaces currently on a host. Pulls the worktree back to your local machine.
• Pull to this device — only appears for sibling-device rows (workspaces that live on another device of your account). See Sibling-device adoption below.
• Open on host — only appears for a workspace that lives on a host you've configured on this device. Drives the workspace in place on the host without copying it down. See Open a workspace on its host below.
• Delete worktree… / Close workspace… — for a branch worktree this is a destructive Delete worktree… gated by a confirm dialog; for a protected repo root it becomes Close workspace… (detach only, files left on disk). See Repo Root Protection.

The whole card is also clickable — clicking opens the workspace.

Status Dots

The dot to the left of each title carries the same agent state the sidebar shows:

When no live agent state is set, the dot falls back to: Emerald (currently open in this app), Sky blue (lives on a remote host), Violet (OpenFlow workspace), Amber (push or pull in flight), Muted (local, not currently attached).

Sibling-Device Adoption

When the overview shows you a workspace on another device of yours, the Pull to this device action brings it to your current machine. Codemux picks the right adoption strategy automatically:

• Host-backed adoption — if both devices have the same SSH host configured, Codemux rsyncs the worktree from that host. The adopted workspace replaces the original on the host (single source of truth).
• Clone-from-git fallback — if the workspace has a git remote but no shared host, Codemux runs git clone --no-checkout into ~/.codemux/projects/<basename>, adds a worktree on the right branch, and registers a fresh local workspace. Both devices end up with independent worktrees sharing the same git remote — push and pull from both ends to stay in sync.
• Same-branch guard — if you click Pull on a sibling row but you already have a local workspace on the same branch of the same project, the dialog refuses to create a parallel copy. Instead it shows the existing workspace with an Open the existing workspace button so a pull can't silently clobber work you're already doing. The match is on the workspace's stable project identity plus the git branch (falling back to project folder name when no identity is known), so it's reliable even when the same repo lives at different paths on the two devices.
• Neither — if the workspace has no host and no remote, the dialog tells you to push from the other device first.

Uncommitted work on the origin device is preserved by the host-backed path; the clone fallback warns you before it runs if there's anything that could be lost.

Pull an Entire Project at Once

When a sibling device has a whole project — the repo root plus several branch worktrees — you don't have to adopt each card one at a time. The project cluster header carries a single Pull project button that brings the entire repository over in one action:

1. The repo root lands first, as a protected root, so the repository exists locally on one shared history.
2. Each branch worktree is then recreated as a real linked worktree under that root — they share the root's history instead of becoming independent copies.

If one worktree fails to materialize (a branch that no longer exists, say) the rest still come over, and Codemux tells you which ones it skipped. This is the recommended way to move a multi-worktree project to a new machine.

Open a Workspace on Its Host

Pulling brings a host workspace's files down to your machine. Sometimes you don't want a copy — you just want to drive the workspace where it already lives. The Open on host action does exactly that: it opens a terminal (and agent) running on the host, in the workspace's real directory there, and streams the output live to your desktop. Nothing is copied to this device — no files land under ~/.codemux/.

This is the third way to work with a remote workspace, alongside Push (send a local workspace up to a host) and Pull (bring a host or sibling workspace down to this device):

Using it

Open on host appears on a host-backed workspace row when that host is registered in Settings → Hosts on this device (Codemux needs an SSH path to reach it). Click it and a workspace card appears with a single ready terminal already attached to the host — start typing and you're running commands in the workspace's directory on the remote machine.

The in-place workspace is marked with a sky on host badge, and its only teardown action is Close (leave running on host) — it can't be deleted, pushed, or pulled, because there's nothing local to act on.

Survives closing the app

The host process keeps running when you close Codemux or shut your laptop's lid — the agent on the host doesn't stop just because your SSH connection dropped. Reopen the app (or open the same workspace from another device that has the host configured) and Codemux re-tunnels and re-attaches to the still-running session. Each device attaches independently over its own connection.

What's available today

The terminal and agent are the supported surface for an in-place workspace. Local-only panels — the file tree, the Changes panel, and ports — are empty, because the files live on the host, not on this device. If you need those, Pull to this device instead so the workspace has a local copy.

A workspace that lives only on a sibling device (not on a configured host) doesn't offer Open on host — there's no SSH host to attach to — so use Pull to this device for those.

Your Conversation Follows the Workspace

Pushing or pulling a workspace doesn't just move the files — if you have an active agent conversation in it, that comes along too. When you push a workspace whose terminal is running a Claude Code or OpenCode session, Codemux carries the conversation to the host so the agent resumes there with its full context instead of starting cold. Pull it back and the conversation continues on your laptop. This holds across repeated push/pull cycles — messages are never lost or duplicated.

A few things worth knowing:

• The matching agent CLI must be installed on the host (claude or opencode, reachable from a login shell). If it isn't, the agent still launches — just without the carried-over history.
• It's best-effort. If the conversation can't be synced for any reason, the push or pull still succeeds and the agent still starts; you only lose the continuity, never the workspace.
• OpenCode sync only moves this workspace's session. OpenCode keeps all of its conversations in a single local database, so Codemux transfers just the one session tied to this workspace — the host's other OpenCode conversations are never touched.
• The same daemon that keeps agents running after you close the app powers this: a pushed workspace's agent runs on the host and survives your SSH connection dropping.

Auto-publish from codemux-remote Hosts

The overview also lists workspaces that an agent (or anything else) created directly on a host — without you ever clicking Push workspace to host from a dev device. The model is intentionally asymmetric:

• Dev devices (laptops, desktops running the Codemux app) keep their manual push/pull. Nothing leaves the device unless you say so.
• codemux-remote hosts auto-publish their workspace registry. They're always-on, SSH-reachable, and exist to be used as hosts — broadcasting what's on them is the unsurprising default.

How it works in practice: each dev device polls every configured host over SSH every ~60 seconds, runs codemux-remote workspace list on the host (which reads the daemon's local registry — no running daemon required), and republishes any new workspaces it finds to the cloud registry. Other devices see them on the next pull tick, so a workspace an agent creates on pandora overnight via the MCP workspace_create tool shows up in every dev device's overview within ~90 seconds.

Two consequences worth knowing:

• A device you've configured shows up immediately in the bucket list. You don't have to push a workspace to it first — the empty bucket renders the moment the host is added in Settings → Hosts, so you can see at a glance which devices are wired up.
• Host-discovered rows carry a project_remote when the host project has a git remote. Codemux records the project's canonical remote on the host, so pull-to-this-device for these rows works via either path — host-backed (rsync from the shared host) or the clone-from-git fallback. A host project with no resolvable remote is adoptable only via the host-backed path.

Cross-Device Divergence

When the same workspace exists on multiple devices via clone-adoption and their git HEADs have moved separately, both rows show an amber diverged chip. Hover the chip for the tooltip's suggested next move (push from one side, pull on the other). The chip clears automatically once both ends agree on the same commit.

Safety Guardrails

Every push and every adoption has two safety nets:

• Confirm before push — Move to host → <device> opens a confirmation dialog with the workspace title, the destination, and a three-bullet explanation of what's about to happen. A "Don't ask again for <host>" checkbox skips the dialog for that destination on this device (persisted in your browser's local storage). The same dialog is used when you push from the sidebar context menu.
• 10-second Undo — every successful push, pull, and adoption surfaces a toast with an Undo button that fires the reverse action. Double-click-guarded so the reverse only runs once. If the reverse action itself fails, you get a follow-up error toast.

Elapsed-Time Indicator

When a push or pull takes longer than ~2 seconds, a compact 12s pill renders next to the spinner — both in the overview row and in the sidebar row. Lets you tell at a glance whether the operation is still working or actually stalled. The counter ticks once per second until the operation completes.

First-Run Banner

The first time you open the overview, a welcome banner explains what you're looking at. It has three state-aware variants:

• Brand-new — no hosts configured, no sibling devices. Banner offers an Add a device CTA pointing at Settings → Hosts.
• Device configured — at least one host set up. Banner nudges you to push your first workspace.
• Has siblings — other devices are publishing workspaces. Banner counts them and explains the pull flow.

Dismiss the banner once and it stays dismissed (persisted in local storage).

How It Works Popover

The overview header has a ? icon that opens a How it works popover summarizing the device buckets, the push/pull flow, and the adoption strategies — useful when you've forgotten the rules.

What Syncs Across Devices

The cross-device registry that powers sibling-device rows syncs a deliberately small set of fields through the Codemux API (Bearer-token authenticated, scoped per user):

Synced: title, host the workspace lives on, project path, git remote URL, branch, HEAD SHA (for divergence detection), project identity + name + type (main / worktree, so grouping and badges line up across devices), and create / update / delete timestamps.

Not synced (per-device runtime state): working directory, worktree path, pane statuses, terminal sessions, surface tree, git ahead/behind/changed-file counts (read from each device's local git tree), notification counts, mute state.

A workspace mutation propagates to other devices within ~30 seconds via a background pull/push loop. Last-write-wins; there is no conflict UI — if two devices edit the same workspace simultaneously, the later push overwrites.

Empty States

• No workspaces yet — the overview surfaces a New workspace shortcut to bootstrap your first one.
• Filters hide everything — a Clear filters button restores the default view.

See Also

• Workspaces — creating and managing individual workspaces.
• Settings → Hosts — registering an SSH host so you can push workspaces to it.
• Automations — scheduled agent runs that also use the host routing layer.