lumbridge-code/docs/PRODUCT_SPEC.md

Product specification

One sentence

Lumbridge is a high-performance, local-first terminal and workspace multiplexer that lets engineers run, steer, compare, and understand many coding agents without surrendering control of their accounts, keys, repositories, or shells.

Primary user

An engineer who works across several repositories and routinely keeps multiple coding agents, shells, test watchers, servers, and review surfaces alive at once. The product should feel faster and calmer as concurrency rises.

Core jobs

1. Open a repository and create a durable workspace with terminals and panes.
2. Launch a supported harness through its subscription login or a BYOK profile.
3. See whether each agent is working, waiting, blocked, complete, or disconnected.
4. Steer work without losing terminal fidelity or bypassing approval prompts.
5. Review file and Git changes by workspace or worktree.
6. Understand usage, rate-limit windows, burn rate, and likely exhaustion time.
7. Resume the entire workspace after the UI or machine restarts.
8. Work from a laptop while selected panes and agents run durably on a user-owned machine reached through SSH or Tailscale.
9. Follow a project's Buzz channel and intentionally share a redacted pane image without leaving the workspace.
10. Inspect terminal, browser, tools, context, goal, and review views without losing the pane's process identity or execution target.
11. Ask a local or selected-provider analyst for a small set of next actions, then choose, edit, dismiss, or explicitly authorize one.

Local and remote workspaces

Every Lumbridge installation is useful on its own and owns its local settings, history, usage observations, and workspace views. A pane can execute locally or on a saved remote host. Remote hosts may be normal SSH destinations, entries in the user's SSH config, Tailscale MagicDNS names, or tailnet IPs.

For durable remote work, a per-user Lumbridge runtime on the destination owns the PTY and process tree. The desktop app connects to that runtime over an SSH stdio channel and can later reconnect without moving the process to a cloud service. The same remote workspace may be opened from another authorized Lumbridge installation, but local UI state is not silently merged between devices.

Initial harnesses

• Claude Code
• OpenAI Codex
• DeepSeek Harness
• Pi and compatible Pi distributions
• Hermes Agent
• OpenClaw
• Goose
• Gemini CLI
• OpenCode

An arbitrary command remains a supported harness through the generic PTY adapter.

Pane surfaces and decision shelf

A pane is the durable unit of work; its surface is a view over that work. The first surface set is Terminal, Browser, Tools, Context, Goal, and Review. A surface change never silently launches a process, moves the pane to another host, or changes which agent owns the session. Unsupported surfaces are shown as unavailable rather than simulated.

The default workspace has three horizontal bands: the top 20% shows context, pane/agent state, tools, and goal; the middle 60% is a responsive set of vertical work lanes; and the bottom 20% is the decision shelf. The work band shows one lane in compact windows, three at normal desktop widths, and up to five on an ultrawide display. One lane owns keyboard input at a time, and selecting a lane never pauses the others. Explicit split trees and dashboard layouts remain supported, but they do not displace this terminal-first default.

An optional decision shelf sits below the active work surface. It may show an answer draft, two or three concrete choices, why each was suggested, and the capability each choice would need. Suggestions are inert data. Choosing one may prepare a typed workspace plan, but any command, file mutation, credential use, or external message still passes through the normal approval and command plane.

Lumbridge Harness

Lumbridge Harness is an optional orchestrator distributed as a separately versioned component. It can analyze explicitly shared workspace state, refine prompts, recommend next steps, and coordinate supported agents. It does not own the desktop shell and is not required for terminal multiplexing.

Its model boundary is provider-neutral. Initial development targets an OpenAI-compatible API so the same contract can use a local Spark/Qwen endpoint, Cerebras, or another user-selected provider. Credentials stay in the OS credential store and are resolved by opaque handle. Endpoint profiles must not embed secrets in workspace layouts, command arguments, or traces.

Trace analysis is off until the user enables it for a workspace and selects the fields or sessions to share. Local analysis remains local. Sending trace data to a hosted provider requires a destination preview and a separate consent. The Harness receives only the Observe, Configure, or Execute capability granted for that run; autopilot cannot manufacture a broader grant.

Provider modes

Subscription mode delegates authentication to the installed upstream harness. Lumbridge observes only documented status, usage, and protocol surfaces.

BYOK mode supports OpenAI, Anthropic, Google Gemini, Groq, Cerebras, DeepSeek, and OpenAI-compatible endpoints. Keys live in the operating-system credential store. A provider adapter receives an opaque secret handle, never a value stored in project state.

Provider and harness selection are independent. For example, a generic harness may use Cerebras by API key while Codex uses a ChatGPT subscription.

Usage footer

The footer answers five questions in a glance:

• Which harness, provider, model, and account profile is active?
• How much of the current usage window has been consumed?
• When does the window reset?
• What is the recent and projected burn rate?
• How trustworthy is the number?

Every value is labeled internally and in detail views as provider-reported, harness-reported, locally measured, estimated, or unavailable. Lumbridge must not scrape browser cookies or reverse-engineer private account APIs to manufacture an exact remaining balance. When only local observations exist, the UI says so.

Buzz collaboration

Buzz is optional and deeply integrated: an engineer can connect an existing identity, bind channels to workspaces, read and send messages, see channel agents, and share a pane image. Sharing always previews the exact capture, redactions, caption, and destination before upload. Buzz identity secrets stay in the operating-system credential store.

Non-goals for the first release

• A new foundation-model training or inference service.
• A hosted account or mandatory Lumbridge cloud.
• Replacing every coding harness with one Lumbridge-owned agent loop.
• Making Lumbridge Harness, trace analysis, or autopilot mandatory.
• Windows support.
• Mobile control or collaborative hosted sessions.
• Arbitrary third-party remote compute provisioning; the first release connects only to machines and SSH/Tailscale access the user already controls.
• Bundling third-party subscriptions or reselling model tokens.

Experience principles

• Terminal truth first: no hidden process state and no fake terminal emulation.
• Keyboard fast, mouse understandable.
• Dense information with a quiet default presentation.
• Approval and security boundaries stay visible.
• Local and offline workflows remain useful.
• Estimates are useful only when their uncertainty is honest.