🤖 Shared remote Claude Code sessions — an Eleven group fronting a workstation

Date: 2026-08-05 · Status: accepted — open questions decided by Paul 2026-08-28 (see § Decisions) · Scope: design only — no implementation yet

What this is

A group in Eleven becomes a shared front-end to Claude Code sessions running on a remote workstation (the motivating box: docs-t1). Multiple people share the sessions: the chat on the left is where you steer — @claude is an ordinary member of the chat — and the right-hand pane is a live view of the remote sessions. Agent activity is translated into Eleven primitives (typed events, cards, views, action lines, notices) rather than mirrored as a terminal.

The design uses almost entirely existing machinery — no new group type, no new E2EE exceptions, one new sidecar-shaped process and one new mini-app.

┌────────────────────────────┬──────────────────────────────┐
│  Chat                      │  agents app (Interface pane) │
│                            │                              │
│  Paul: @claude fix the     │  ▸ fix-login   📁 messenger  │
│        flaky reminder test │    running · turn 3          │
│  @claude [fix-login]:      │    ⚙ go test ./internal/bot  │
│    Found it — the ticker…  │  ▸ ops-poke    🖥 workstation │
│  Ana: @claude also check…  │    waiting for approval      │
│                            │    [Allow] [Deny]            │
└────────────────────────────┴──────────────────────────────┘
   the shipped Chat | Split | widget-bar layout, nothing new

Trust model (read this first)

• The E2EE rule holds untouched. The server relays opaque ciphertext; every session.* event, prompt, approval, and view is encrypted under the thread key like any message. The server never learns what the sessions do, which repos exist, or that a box called docs-t1 is involved.
• The bridge is a bot-model process (docs/bots.md): an E2EE member whose "device" is the workstation. It runs ON the box, beside the sessions, holds its member private key + the Anthropic access there, and is a pure outbound client — dials the instance and the Anthropic API, no inbound ports. Bot code never runs inside the lchat server process.
• Group membership is the consent moment. Everyone in the group can steer sessions, which means everyone in the group has a lever on the box — filesystem, git credentials, whatever the bridge's unix user reaches. This is the operator-only dev-bot tier (docs/bots.md tier 4): chat input is untrusted input to a machine with authority. The bridge's config (below) enumerates exactly what that authority is; adding a member is granting it.
• Flat authority for v1. Any member can prompt, approve, and interrupt. Roles (driver/observer) are layerable later as ordinary fold state (agents.role events) without schema changes.

The pieces

1. The bridge — lchat agents run

A sibling subcommand of lchat bot run, reusing the Go sidecar runtime (WebSocket client, key unwrap, reconnect, trigger plumbing — all existing). It runs on the workstation and:

• joins the instance as the @claude member (one keypair, one roster row — the standard bot-member shape, not a charter persona);
• owns the Claude Code sessions: spawns them headless (claude -p --output-format stream-json, resumable via --resume <session-id>; the Agent SDK is the same thing as a library), consumes the structured event stream — assistant text, tool_use blocks with full inputs, tool results, turn boundaries. No terminal emulator: nothing scrapes a TTY. The only terminal-ish work is stripping/basic-rendering ANSI colours out of Bash tool output (~50 lines, no cursor addressing exists in a -p session);
• translates the stream into encrypted session.* events (vocabulary below) posted into the group thread, and reads members' prompt/approval/interrupt events back off the same thread;
• serializes turns per session (a session is one-turn-at-a-time), queues prompts that arrive mid-turn, and attributes prompts by speaker — "Paul: fix the flaky test" — so the model knows it's talking to a room.

Config, per group the bridge serves:

groups:
  <thread-id>:
    roots:  ["~/github.com/elevenmessenger/messenger"]  # scoped sessions live here
    plain:  false                                       # whole-workstation sessions allowed?

The config is the blast radius, written down in one place on the box.

2. Sessions — two flavors, chosen at spawn

• Scoped (default): bound to a directory — an allowed root, normally a fresh git worktree under it so parallel sessions don't trample each other. A scoped session gets that project's own .claude/ settings, CLAUDE.md, hooks, and permission config exactly as a human dev would — the repo's existing guardrails govern the remote session with zero new machinery.
• Plain (opt-in via plain: true): no pinning — cwd = home, the whole workstation at the bridge's unix user's reach. The "shared computer" mode for ops-ish, cross-repo work. Off by default because it hands every member the entire box.

Flavor is visible everywhere: carried on session.spawn, badged on the session's view ("📁 messenger @ fix-login" vs "🖥 full workstation") and on its chat card. Nobody wonders which kind of hands are on the box.

Birth is conversational: "@claude fix X" with zero live sessions spawns a scoped session in the group's default root; /claude new <name> names one; /claude new --plain <name> when the config allows. Session state persists on disk on the box (Claude Code's own session files), so a human on the workstation can claude --resume <id> from a real terminal after the bridge lets go — continuity is preserved; concurrent dual-driving is not pretended.

3. Chat — @claude plus focus-based routing

One bot member; the mental model is "a colleague in the chat who happens to be several sessions deep."

• Routing: the target is the active view. Each member's client knows which session view they have focused in the right pane; a message to @claude carries target: <session-id> inside the encrypted payload. Focus is per-member — two people can steer two sessions from the same chat simultaneously.
• Routing is visible at send time. When more than one session is live, the composer shows a chip — "→ fix-login" — tappable to retarget without touching the pane.
• Replies pin the target. Every @claude bubble carries a subtle session tag; replying to a bubble routes to that session regardless of pane focus — this is also the mobile/chat-only answer. The tag works the other way too: tapping it focuses that session's view.
• Degenerate cases collapse. One live session: everything routes there, no chip. Zero sessions: @claude answers as the workstation ("no sessions running — want one?") and a prompt spawns one.

Output posts as @claude with the session tag on each bubble — the feed reads as one assistant working several desks, which is the truth.

4. The right pane — one app, one view per session

• One agents mini-app (web/static/apps/agents.js), chat-placed (places: ["chat"]), added to the group like any app — one glyph in the widget bar, rendering in the standard Interface pane. The shipped Chat | Split | widget-bar toggle IS the "chat left, session right" layout; nothing new is built for it.
• Its Interface is the fleet board: one card per session (name, flavor badge, status, current activity line, waiting-on-approval chips), folded from durable session.* events.
• Per-session status rides the views engine (views.js, view.create/view.update from the bridge): one engine view per session. Views are declarative SCHEMA + DATA interpreted by both web and the Swift twin engine, so session boards render on iOS/Mac with no per-feature Swift. Chips on @claude's replies open the session's view; /views lists them.
• Fidelity is "board + drill-in" (option c). Tap a session to focus it: the durable board plus a live tail — tool-call chips ("Ran go test ./..."), collapsed monospace output, file-edit lines, assistant prose — streamed as ephemeral events (relay-only frames, the existing primitive): live viewers see the chatter; nobody replays it; the encrypted log stores only what deserves permanence. The views engine cannot host the tail (views are durable documents; streaming through view.update would bloat the log) — the tail is the app's own render over the ephemeral stream, web-first.

5. Event vocabulary

Durable (thread log; the fold state every member converges on):

| event | payload sketch | why durable | |---|---|---| | session.spawn | id, name, flavor, root/worktree, by | fleet board exists offline | | session.status | id, state (running/idle/waiting/dead), activity line | board truth | | session.prompt | id=target, text, by | the steering history IS the log | | session.turn | id, assistant text (final, per turn) | the conversation with the agent | | session.result | id, summary card (files changed, tests, links) | milestones as cards | | session.approval | id, request (tool, input digest), state, decided-by | audit trail of authority used | | session.end | id, reason, by | lifecycle honesty |

Ephemeral (relay-only; live tail + presence):

• session.tool — tool_use started/finished, truncated output chunks
• session.stream — assistant text deltas while a turn is in flight
• typing-style "session is thinking" indicators

Streaming into chat has no partial-message primitive, so @claude's chat bubbles are post-per-turn (the durable session.turn), with the live delta visible in the drill-in tail instead — no post-then-edit churn in the feed.

6. Approvals

Claude Code's permission gate surfaces as a chip row — on the session's board and as a @claude chat card: "fix-login wants to run git push — [Allow] [Deny]". A tap emits an encrypted session.approval decision event; the bridge reads it and answers the gate. Flat authority: first decision wins, attributed in the event and shown in the feed ("Ana allowed git push"). Notices/push ride the existing E2EE notify path, so "waiting for approval" reaches pockets.

7. Liveness

Derived, never declared (the docs/bots.md pattern): the bridge heartbeats (ephemeral presence + a periodic durable status touch); a session whose bridge is gone must read as dead/stale in the board — "last seen 4m ago" — not linger as "running". A dead bridge silently eating prompts is the worst failure mode; staleness is always rendered from event age, client-side.

What the server gains

Nothing. Every piece rides existing surfaces: bot membership, thread events, ephemeral frames, the views engine, the mini-app framework, notify/push. The bridge is a new subcommand of the existing binary; the app is one new file under web/static/apps/.

Hard parts, named

• The approval round-trip — latency between the gate firing and a human tapping Allow; the session blocks meanwhile. Mitigations: push notices, per-session auto-allow lists (later; config-side, never chat-grantable).
• Log discipline — a busy session emits a lot; the durable/ephemeral split above is the design's load-bearing wall. Anything high-churn must be ephemeral or it bloats every member's encrypted log forever.
• Prompt-injection containment — session output is model output over untrusted repo/web content; it lands in chat as content, never as commands. The bridge only ever acts on typed events from members.

Deferred (deliberately)

• Driver/observer roles — layer later as agents.role fold state.
• Fleet-across-groups overview — a "you"-placed app aggregating every workstation group; needs nothing new from this design.
• Attaching to a human's interactive TUI session — ruled out for v1 (tmux-scraping + keystroke injection fights the one-writer TUI; the honest handoff is --resume after the bridge lets go).
• Auto-allow permission profiles per session flavor.
• Native drill-in tail — boards are native-free via the views engine; the live tail ships web-first.

Decisions (Paul, 2026-08-28)

1. Naming: agents stands. lchat agents run, apps/agents.js, session.* events, and the member reads as @claude.
2. The prompt IS the chat message. One session.prompt event, two projections — the member's visible bubble in the feed and the bridge's steering input, tagged with the target. No separate chat.msg.
3. Closing a session closes its worktree. Sessions are closable from within Eleven, and session.end is the cleanup moment: the bridge removes a scoped session's worktree then. The branch (any committed work) survives worktree removal as an ordinary git branch; only the checkout goes.