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). Commands from multiple operators are processed FIFO against a single PTY, with no merge. 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.
Input arbitration
Multiple operators on one session is supported. Commands are processed FIFO server-side against a single PTY:
There is no merge or conflict resolution — last command for stateful operations wins. For the persistent multi-command shape (one channel, many commands within one operator), see Remote Sessions — that’s the sessionmgr ringbuf 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.
Related
TAGS: multi-client, operator, observer, collaboration, device-switching DEPENDS_ON: [sessions, remote-sessions, ai-operators]
Cmdop