Multi-Client
In the execution-state continuity layer, one single-homed CMDOP session can have many clients attached at once, all viewing the same output stream. Clients of every kind — Desktop, CLI, mobile, SDK, and AI — attach as either operators (may send input) or observers (read-only). Operators take turns steering the one shared session, with no merge — last write wins. This powers collaborative debugging, shadowing, audit, AI assist, and seamless device switching.
A CMDOP session can have many clients attached at once. All of them see the same output stream. Some have permission to send input (operators); others can only watch (observers). This is how collaborative debugging, AI assist, and seamless device switching work.
The model
Same session object on the agent. Each client opens its own stream and sees output as it arrives. Operators can submit input; observers cannot.
Operator vs Observer
| Capability | Operator | Observer |
|---|---|---|
| View output | yes | yes |
| Send input | yes | no |
| Execute commands | yes | no |
| File read | yes | yes |
| File write | yes | no |
| Resize terminal | yes | no |
| Send signals (SIGINT, …) | yes | no |
Observer mode is useful for shadowing, audit/compliance, and AI-assisted analysis where you want the LLM to see output without changing it.
Taking turns
Multiple operators can be attached to one session at once. They take turns steering it — each operator’s input lands in the one shared live session, and everyone sees the same result. There is no merge or conflict resolution: for stateful work, the last operator to act wins, so coordinate (or use observer mode) when several people are attached.
For the persistent multi-command shape (one channel, many commands within one operator), see Remote Sessions — that’s the persistent-session flow, not the terminal session described here.
Use cases
- Collaborative debugging. Two engineers attach to the same session; one types, both watch. Same output, no screen-share latency.
- Shadowing / training. Senior runs the session as operator; junior attaches as observer.
- Audit / compliance. Security observer attaches while production work happens.
- AI assist. AI joins as observer, watches output, raises suggestions; humans stay in control. See AI Operators.
- Device switching. Start in Desktop on the laptop, attach on the phone after closing the lid, keep watching the deploy. Sessions outlive any single device — see Sessions.
Reading the attached-client list
The session metadata exposes every attached client:
{
"session_id": "prod-1:slot3",
"attached_clients": [
{ "user": "[email protected]", "mode": "operator", "client": "desktop" },
{ "user": "[email protected]", "mode": "observer", "client": "cli" }
]
}Use this in tooling to warn before attaching as a second operator, or to record audit trails of who saw what.
Limits
- One PTY per terminal session.
- Commands are queued, not merged.
- Output is broadcast to every attached client — bandwidth scales linearly with audience. For large observer audiences, prefer observer-only attaches.
For multiple persistent commands per machine (rather than multiple clients on one PTY),
use the connect_session agent tool. See Remote Sessions.
Reconnecting from any device
Sessions are addressable by ID. You can detach from the laptop and reconnect from the phone:
# laptop
cmdop connect prod-1
# (laptop closes; session continues)
# phone — list sessions, then reattach interactively
cmdop session list
cmdop connect prod-1 # live interactive reattach
cmdop session attach <session-id> # metadata only (takeover pending)Interactive reattach (a live terminal) is done with cmdop connect; cmdop session attach
currently reports the session’s metadata, with interactive takeover planned but not yet
implemented. The 30-second grace period on terminal sessions covers brief network blips so a
quick reconnect resumes seamlessly.
Cmdop