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.

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.
• Delete worktree… / Close workspace… — destructive, gated by a confirm dialog.

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. Heuristic is (project basename, git branch) — false positives are bounded to two distinct projects sharing a basename AND a branch on the same device.
• 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.

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 have no project_remote field. Pull-to-this-device for these works via the host-backed path (rsync from the shared host); the clone-from-git fallback isn't available for them.

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), 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.