Product #

Platform #

web

Shard is a multi-client coding agent harness. The web surface documented here is one client among several (web, orchestrator, SDK); all clients are thin views + controllers over one transport-agnostic protocol spoken to shardd. Platform web covers the browser SPA served by the daemon. Other surfaces retain their own design records (the web lives in src/web/DESIGN.md); this record is the shared product truth across all clients.

Users #

Developers driving long-running coding agents, head-down and often mid-task. They want to launch, watch, steer, and answer permission prompts for one or many agents at once, then detach and reattach later without losing state. The web serves both a single-conversation lens and a multi-agent dashboard: the same developer, supervising several agent runs side by side, drilling into any one of them for the same three-questions scan — what did I just ask, what is the agent doing right now, what did the agent say — and reattaching to live agents from a browser.

User state of mind #

Focused, time-pressured, occasionally debugging a tool failure. Never "exploring" the UI. They want to find the next boundary between their input, tool activity, and the agent's prose in one glance, then get back to the code. On the dashboard, the same focus applies to "which agents are running, which need me, what changed" before drilling in.

Product Purpose #

Make a long-running coding agent safe to leave running and reachable from any client. The agent runs detached in its own process; a client attaches, drives a turn, answers a permission prompt, watches progress, then detaches; the agent keeps going. Success is an agent you can start, walk away from, and come back to from any surface — and a transcript where the boundary between user message, tool block, and assistant prose is obvious without reading the words.

Positioning #

shardd is to agents what tmux is to sessions: a supervisor daemon that owns isolated agent processes and lets any number of clients (web, orchestrator, SDK) attach and detach live over one shared protocol. The meaningfully-different mechanism is that the agent process is detachable and multi-client by design — not a single-process CLI you happen to reconnect to, but a daemon-supervised agent any client can join, steer, and leave running. Transports differ; the protocol and the conversation are the same.

Operating Context #

The agent loop lives in a server process (shardd, the daemon). Clients render + control; they never run agent logic.
One agent session = append-only JSONL, never deleted; compaction partitions it into addressable spans and recall recovers pre-compaction work.
Clients attach over a transport-agnostic protocol: stdio JSONL (daemon↔agent, SDK), unix socket (short-lived job clients), WebSocket (web/orchestrator).
Permission prompts and UI dialogs broadcast to all attached clients; first response wins; a reattaching client receives pending prompts.
Workflow: start an agent (or pick one from the registry), drive or watch it, answer prompts inline, detach, reattach later from the same or a different client.

Capabilities and Constraints #

Render a scrolling conversation transcript: user prompts, streamed assistant text, tool calls + results, permission prompts, compaction notices, errors, turn/usage markers — the same block model across every client.
Tools return transport-neutral RenderDescriptors (text/kv/diff/tree/progress/status); each client renders the closed descriptor set its own way.
The web serves the orchestrator surface (list/create/attach/kill/status agents across the registry) and the per-agent conversation surface (one agent's live stream + history) in one app — a registry view that drills into a single conversation. Both are confirmed in scope.
Multi-client: any attached client can answer a permission prompt or UI dialog on any agent.
Daemon is loopback-bound by default; web SPA is served same-origin by the daemon; token auth on the WS handshake; CORS allowlist only for dev/separate-host cases.
Platform confirmation: web. (Other shards' native surfaces are out of scope here.)
Undecided (do not fabricate): specific web accessibility standard; whether the web ships a distinct "single-agent-only" entry vs always-the-dashboard-with-drill-in; remote/TLS mode.

Brand Commitments #

Voice: precise, calm, tool-like. Copy is minimal. Icons are structural, not decorative. No exclamation marks, no cheer. This voice is a cross-surface commitment.
Register: design serves the task. The client must disappear into the work; the user is oriented, not entertained. Familiarity with the best tools is a feature, not a deficit.
Name: Shard. Daemon: shardd. No brand assets, logos, or identity system have been confirmed yet.

Evidence on Hand #

ARCHITECTURE.md — layered architecture, process model, protocol, multi-client model, subagents, security. The source of structural truth.
PROTOCOL.md — the wire protocol (commands + events across transports).
src/daemon/** — orchestrator.ts, registry.ts, socket-server.ts, proxy.ts, supervisor.ts, runtime-manager.ts: the server surface the web talks to is implemented.
src/web/DESIGN.md — the web surface's design record. It is the web's truth, not a constraint on other surfaces' visual language.
Absences future work must not fabricate: no customer testimonials, no usage benchmarks, no pricing/licensing, no confirmed deployment claims beyond loopback local-first.

Product Principles #

The client is a thin view + controller. It renders the protocol and routes input; it never owns agent logic. Design follows the seam, not vice versa.
Design serves the task. Orient the user, don't entertain them. The boundary between user input, tool activity, and agent prose must be legible without reading the words.
Detachable by design. A started agent must be safe to leave and reachable from any client later. Detach/reattach, replay, and pending-prompt delivery are product features, not edge cases.
One protocol, many clients. Transports differ; the conversation and the block model are the same. Visual language is per-surface; product truth is shared.
Data outlives behavior. The append-only session JSONL is self-describing; tools and extractors can change across versions and old sessions still replay and compact. Design never assumes the current renderer is the only reader.

Accessibility & Inclusion #

A product-specific accessibility standard has not yet been established for the web surface. Restore fidelity and keyboard-driven control are expected directions; defer the concrete standard to the web surface brief.