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.

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.

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, collaborative cloud sessions, or remote execution.
• 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.