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.

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.

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.
• 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.