Dashboard: Browser-based agent sessions with SSE streaming #355

New issue

Open

opened 2026-04-15 08:44:49 +00:00 by mprihoda · 1 comment

mprihoda commented

2026-04-15 08:44:49 +00:00

(Migrated from github.com)

Layer: 3 — Agent Integration
Parent: #343

Problem

Currently, agent sessions are tied to tmux. To fully use the dashboard as the primary control plane, you should be able to start, monitor, and interact with agent sessions entirely from the browser.

Solution

Start new Claude Code sessions from the dashboard — select a worktree, provide an initial prompt, launch a session
Full conversation UI — see the entire conversation as it happens, with streaming responses via SSE
Session persistence — sessions run server-side and survive browser disconnects; reconnecting shows the current state
Session portability — ability to start a session in the browser and attach from CLI (and vice versa), since claude-code-query sessions are process-backed
Multiple concurrent sessions — one per worktree, matching the current tmux model

Architecture

Server manages session processes via claude-code-query Session API
SessionOptions configures: cwd (worktree path), model, systemPrompt, permissions
Browser connects via SSE for streaming, HTTP POST for sending messages
Session state persisted server-side (conversation history, process handle)
Optional: web-based terminal (xterm.js) for cases where a real terminal is needed

This is the culmination of the dashboard vision

When this is complete, tmux becomes optional — the dashboard handles the full agent interaction lifecycle. Terminal access becomes an escape hatch for exceptional cases (manual builds, file operations) rather than the primary interface.

Dependencies

Transcript viewer (#353) for conversation display
Send instructions (#354) for input handling
Layer 0 build infrastructure for claude-code-query dependency

**Layer:** 3 — Agent Integration **Parent:** #343 ## Problem Currently, agent sessions are tied to tmux. To fully use the dashboard as the primary control plane, you should be able to start, monitor, and interact with agent sessions entirely from the browser. ## Solution 1. **Start new Claude Code sessions from the dashboard** — select a worktree, provide an initial prompt, launch a session 2. **Full conversation UI** — see the entire conversation as it happens, with streaming responses via SSE 3. **Session persistence** — sessions run server-side and survive browser disconnects; reconnecting shows the current state 4. **Session portability** — ability to start a session in the browser and attach from CLI (and vice versa), since claude-code-query sessions are process-backed 5. **Multiple concurrent sessions** — one per worktree, matching the current tmux model ## Architecture - Server manages session processes via `claude-code-query` Session API - `SessionOptions` configures: cwd (worktree path), model, systemPrompt, permissions - Browser connects via SSE for streaming, HTTP POST for sending messages - Session state persisted server-side (conversation history, process handle) - Optional: web-based terminal (xterm.js) for cases where a real terminal is needed ## This is the culmination of the dashboard vision When this is complete, tmux becomes optional — the dashboard handles the full agent interaction lifecycle. Terminal access becomes an escape hatch for exceptional cases (manual builds, file operations) rather than the primary interface. ## Dependencies - Transcript viewer (#353) for conversation display - Send instructions (#354) for input handling - Layer 0 build infrastructure for claude-code-query dependency

Snailflyer commented

2026-05-30 05:10:21 +00:00

(Migrated from github.com)

This dashboard direction is strong. I would make one acceptance boundary explicit before tmux becomes optional:

Browser-visible session state should not be considered the same as a live writable target unless the server can prove where the next input lands.

For each worktree/session row, I would track a small receipt:

worktree path / project id
agent kind and server-side session id
live target kind: tmux pane, process handle, or claude-code-query session
process generation or start time
output cursor before/after the last browser-sent message
result: accepted, applied, stale, wrong-worktree, history-only, or no-live-target

That matters especially for the portability goal: browser-started -> CLI attach and CLI-started -> browser attach can both show the same transcript while disagreeing about whether the next input reaches the intended live process.

Faryo is a smaller project/mobile workbench around the same boundary: the project/control surface is only trusted after an action returns to the same live tmux-backed session. Public proof shape:
https://github.com/Snailflyer/faryo/releases/download/v1.0.7/faryo-public-redacted-same-session-handoff-walkthrough-20260528-0120.gif

This dashboard direction is strong. I would make one acceptance boundary explicit before tmux becomes optional: Browser-visible session state should not be considered the same as a live writable target unless the server can prove where the next input lands. For each worktree/session row, I would track a small receipt: - worktree path / project id - agent kind and server-side session id - live target kind: tmux pane, process handle, or claude-code-query session - process generation or start time - output cursor before/after the last browser-sent message - result: `accepted`, `applied`, `stale`, `wrong-worktree`, `history-only`, or `no-live-target` That matters especially for the portability goal: browser-started -> CLI attach and CLI-started -> browser attach can both show the same transcript while disagreeing about whether the next input reaches the intended live process. Faryo is a smaller project/mobile workbench around the same boundary: the project/control surface is only trusted after an action returns to the same live tmux-backed session. Public proof shape: https://github.com/Snailflyer/faryo/releases/download/v1.0.7/faryo-public-redacted-same-session-handoff-walkthrough-20260528-0120.gif