Build first-class dreb web dashboard

[aebrer]

Summary

Build a first-class dreb web dashboard: a visual, real-time, mobile-friendly interface for browsing projects and sessions, controlling multiple dreb agents, watching subagents live, and using dreb from devices that are not sitting at the host terminal.

This replaces the previous "hard-fork Pi Mobile" direction for this issue. The updated direction is not to fork pi-dashboard or depend on a pile of third-party Pi extensions. The dashboard should be owned in the dreb monorepo, designed around dreb's RPC/session model, and kept small enough that we can reason about security and correctness.

Motivation

pi-dashboard validates the product shape: agent sessions in a browser can be much more approachable than a terminal-only workflow, especially on mobile. But the goal for dreb should be a first-party implementation rather than a vibe-coded fork:

• dreb needs a web UI that can control multiple sessions and projects from one place.
• The UI should work well on both desktop and mobile.
• The system should be usable from the same machine via localhost, while using Tailscale for any access from other devices — whether those devices are on WAN or the same LAN.
• We should avoid inheriting untrusted Pi extension dependencies or fragile assumptions from a Pi-specific dashboard.
• The visual design should be minimalist and dreb-native, not the default purple/orange glowing "AI slop" aesthetic.

Proposed Behavior

Add a first-party dashboard server and browser UI to dreb. A rough architecture:

Browser dashboard
  <-> local dreb dashboard server
  <-> dreb session manager / RPC / event stream
  <-> active dreb agents, subagents, tools, files, and settings

Localhost should work without authentication friction only when using the browser on the same host machine. Any access from another device should go through Tailscale, even if that device is on the same LAN, with authorization based on specific allowed Tailscale identities/devices rather than exposing a LAN-reachable or public web app. First login from a browser/device should require a short-lived PIN shown in the host CLI/TUI so accidental or unauthorized access is not granted just because the network identity is allowed.

MVP Scope

The first useful version should include:

• Project/folder explorer

  • Browse filesystem folders/projects visible to the host.
  • Open/select a project context for a dreb session.
  • Upload files into a selected folder.
  • Download files from the host.

• Session picker and history

  • List existing dreb sessions across projects.
  • Create a new session in a selected project.
  • Resume/open a previous session.
  • Show session metadata such as cwd, model, last activity, and status where available.

• Chat interface with TUI parity

  • Send prompts, steering/follow-up messages, and interrupts/abort.
  • Render assistant messages, user messages, tool calls/results, errors, thinking/status, task lists, and suggest-next events.
  • Preserve important dreb TUI behaviors rather than becoming a reduced chat-only client.

• Live subagent visibility

  • Show background subagents as first-class live work units.
  • Surface agent start/progress/completion/error states.
  • Make it clear which parent session spawned each subagent and what remains running.

• Settings tab

  • Configure model/provider choices and dreb-relevant runtime settings exposed by the existing config system.
  • Prefer explicit validation/errors over silent fallback behavior.

• Responsive desktop/mobile UI

  • The same dashboard should be usable on desktop browsers and mobile browsers.
  • Mobile does not need to be a separate native app for the MVP, but the layout must be intentionally designed for small screens.

Stretch / Later Scope

• Embedded terminal pane

  • Optional zsh/bash terminal for commands that should run on the host without opening a separate terminal.
  • Treat this as security-sensitive and separate from model tool execution.

• Agent-team coordination

  • Coordinate multiple sessions working on the same project in one place.
  • Show which sessions/subagents are active, what files/areas they are touching, and where human attention is needed.

• Native app shell

  • If a native app becomes worthwhile, consider React Native or another shared-code approach rather than reinventing desktop/mobile UI twice.

Security / Access Model

• Localhost access should "just work" only for the user on the host machine.
• Any non-localhost access should be Tailscale-first, including access from another device on the same LAN.
• Do not bind an unauthenticated dashboard to the LAN; other machines on the local network must not be able to control the host PC just because they can reach its IP.
• Allowlist specific Tailscale identities/devices for dashboard access.
• Require PIN pairing on first login from a browser/device; the PIN should be short-lived, generated by the host, and displayed in the CLI/TUI/dashboard server logs for the local user.
• Do not require Tailscale for same-machine localhost-only use cases, including work environments where the dashboard is only opened on the host machine.
• Avoid loading arbitrary third-party dashboard extensions by default.
• Be explicit about dangerous capabilities: file upload/download, host filesystem browsing, terminal access, and agent control.

Design Direction

• Minimalist, readable, and utilitarian.
• Avoid generic AI-dashboard tropes: purple/orange glow, heavy gradients, fake glassmorphism, oversized sparkle branding.
• Use dreb's existing product language where possible; entropist.ca is a reasonable visual reference for "nice and minimalist."
• Prioritize information density, mobile ergonomics, and clear status over decorative animation.

Acceptance Criteria

• A first-party dashboard package/app exists in the dreb monorepo.
• dreb can launch or document launching the dashboard server locally.
• The dashboard can connect to dreb sessions without relying on Pi-specific protocols or extensions.
• Same-machine localhost access works without Tailscale.
• Access from any other device, including devices on the same LAN, requires Tailscale or an equivalent authenticated path.
• Tailscale-based access can restrict access to configured identities/devices.
• First login from a browser/device requires successful short-lived PIN pairing before dashboard control is granted.
• Users can browse projects/folders and upload/download files.
• Users can list, create, open, and resume dreb sessions across projects.
• Users can interact with a session through a chat UI with practical parity for core TUI events and controls.
• Background subagents are visible live from the dashboard.
• Settings relevant to model/runtime selection are available in the dashboard.
• The UI is responsive enough to be usable on both mobile and desktop.
• Documentation explains local-only use, Tailscale remote use, security implications, and supported workflows.

Technical Notes

Relevant dreb areas likely involved:

• packages/coding-agent/src/modes/rpc/
• packages/coding-agent/src/core/session-manager.ts
• packages/coding-agent/src/core/agent-session.ts
• packages/coding-agent/src/config.ts
• Existing TUI event rendering/state concepts that should inform web UI parity
• Existing tool/event types for task updates, suggest-next, and background-agent lifecycle events

Likely implementation questions:

• Should the dashboard server be part of packages/coding-agent, a new workspace package, or a separate app package in the monorepo?
• Should the dashboard talk to dreb through the existing JSONL RPC mode, a new local server API, or a shared internal event/session layer?
• Which event/state normalization should be shared between TUI and web UI so parity does not require duplicating rendering logic?
• What is the minimal safe file API for browsing, upload, and download?
• What Tailscale identity data is available reliably enough for allowlisting?

Non-goals for this issue

• Do not hard-fork pi-dashboard as the implementation foundation.
• Do not hard-fork pi-mobile as the primary path for this issue.
• Do not depend on third-party Pi extensions for core dashboard behavior.
• Do not expose the dashboard as a public unauthenticated web app.

[aebrer]

Update: the draft implementation PR was closed without merging: #310

The implementation attempt made it clear that this needs a UX/UI design pass first. The dashboard should not start as backend scaffolding plus panels; it needs a coherent product design for:

• first launch and project selection
• session history and resume/create flows
• chat parity for prompts, steering, follow-ups, aborts, tool events, tasks, and suggest-next
• live subagent visibility
• file upload/download safety UX
• settings/model controls
• responsive mobile layout
• localhost vs Tailscale remote access and PIN pairing
• minimalist dreb-native visual language

I opened a blocking design issue for that work: #311

Recommendation: treat dashboard implementation as blocked until the UX/UI spec from that issue is accepted. Once the design is clear, implementation can be replanned from the product flows instead of from API scaffolding.

[m-aebrer]

RPC prerequisite sub-issues

The assessment on the design issue (#311) identified RPC surface gaps that block a pure-RPC dashboard client. These are now tracked as sub-issues so they can run through the pipeline independently of (and in parallel with) the UX design work:

• Expose cross-project session listing and session deletion over RPC #312 — cross-project session listing (list_all_sessions) and session deletion (delete_session), needed for the fleet-centric overview screen
• Expose session tree inspection and navigation over RPC #313 — session tree inspection (get_tree) and navigation (navigate_tree), needed for /tree parity in the session view
• Expose settings read and write over RPC #314 — settings read/write (get_settings + typed persistent writes), needed for the settings tab

Design direction update from the design issue: the dashboard home screen is fleet-centric (multi-session/multi-project overview with live subagent activity), with drill-in to any session for one-on-one interaction. These RPC extensions make that possible without the dashboard server importing SessionManager directly (the hybrid boundary the closed draft PR used).

Implementation remains blocked on the UX spec from #311; the RPC sub-issues are not blocked and can proceed immediately.