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 is a 3×1 vertical composition: the top 20% shows context,
pane/agent state, tools, and goal; the middle 60% is the selected terminal or
work surface; the bottom 20% is the decision shelf. Multiple panes may continue
working offscreen and remain one shortcut away. Explicit split and dashboard
layouts remain supported, but they do not displace the primary-terminal 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.