Shared projects

Share a project from one computer running Agent Grid and open it on another. Panes, terminals, notes, titles, and layout sync live in both directions, and an in-progress Claude, Codex, Antigravity, or terminal pane resumes on the second device with its full screen intact.

This is desktop ↔ desktop. For the phone/tablet companion, see Mobile app.

Mark a project as shared

A project is only reachable from a paired device once you've explicitly shared it — sharing IS the authorization gate. Two equivalent surfaces:

• Right-click the project tab → Share with paired devices. The same menu shows Unshare with paired devices once a project is shared.
• Settings → Devices → "Shared projects" card. Lists every currently-shared project; each row has an Unshare button.

Sharing is keyed by absolute path on the host. A paired peer can only read or write workspaces under a shared project — anything outside is rejected server-side.

Pair another device

Pairing is a one-time, two-sided handshake. Both devices need to be running Agent Grid and reachable to each other on the network.

On the device that has the project (the host)

1. Settings → Devices → "Allow a device to connect" → click Allow a device.
2. A pairing panel appears with:
   • A 6-character code (expires in 5 minutes).
   • A QR code encoding the host address and code together.
   • The host's reachable addresses, with the Tailscale address marked primary when one exists.
   • Copy buttons for the code and the address.

On the second device (the client)

1. Open Connect to a device — either from Settings → Devices → Connect to a device, or from the empty project picker (the "drop a folder here" state offers it as an option).
2. Enter the 6-character code and the host's address, or paste the combined host:port|CODE string into the code field and both halves fill in.
3. Submit. The host now lists this device under Paired devices, and this device lists the host under Paired hosts.

Pair codes are kept in memory on the host — restarting Agent Grid invalidates any outstanding code.

Open a shared project on the second device

From the second device's empty project picker, click Open Remote Project, choose a paired host, and the list of that host's shared projects loads automatically. Click a row to open it.

If the host hasn't shared anything yet you'll see "This host hasn't shared any projects yet — ask them to share one, or enter a path manually."

What syncs

Sync is live and two-way. Anything you do on one device shows up on the other within the same tick:

• Panes — added, removed, and reordered in the canvas z-stack.
• Layout — pane position and size as you drag and resize.
• Titles — both pane titles and title panes.
• Notes — title and body, as you type.
• Terminals and agents — the underlying PTY is owned by the host; both devices see the same live output and either device can type into it.

Resume an in-progress session on another device

Long-running panes — claude, codex, agy, and plain terminals — don't get re-spawned on the second device. The host's daemon owns the PTY and replays a snapshot of the terminal buffer when the second device attaches, so the pane opens with its full transcript already painted and you continue where you left off. Keystrokes from either device flow into the same PTY.

The shared-tab indicator

A small share icon appears next to the label of every tab whose project is in your local shared list, with the tooltip "Shared with paired devices". The normal tab status dot still renders — the share icon is an additional indicator, not a replacement.

Revoking a pairing

Settings → Devices → Paired devices lists every device that has connected to this host. The Revoke button on a row closes every live connection from that device immediately and removes its token; the device has to pair again from scratch to come back.

Network and transport

A remote pairing token is bound to the Tailscale address range it was issued for and can't be replayed from a public address. Loopback tokens are bound to 127.0.0.1 / ::1.

Shared projects vs. the mobile companion

Settings has two pairing categories and they do different things:

• Settings → Devices — desktop ↔ desktop. The flow on this page.
• Settings → Mobile — the iOS / Android companion. See Mobile app.

Both share the same underlying protocol server, but the pairing UI and what each peer is allowed to do are different. Pick the category that matches the device you're pairing.

Related

• Spaces and project folders — sharing is per project folder; a shared folder opens as a normal space on the second device.
• Mobile app — the phone/tablet companion flow.
• Terminals — the same PTY model that makes terminal panes resume cleanly on a second device.