opencode/specs/tui-package.md

TUI Package Extraction

Goal

Move the canonical OpenCode terminal application from packages/opencode/src/cli/cmd/tui into a self-contained workspace package while the legacy CLI and the new CLI continue to use the same implementation.

Target package:

packages/tui
name: @opencode-ai/tui

Target dependency graph:

packages/opencode ---\
                      > @opencode-ai/tui -> @opencode-ai/sdk
packages/cli --------/

The TUI may directly depend on terminal and UI infrastructure such as @opentui/core, @opentui/solid, @opentui/keymap, solid-js, Effect, and generic presentation libraries. It must not depend on packages/opencode, packages/cli, or @opencode-ai/core.

The SDK is the TUI's OpenCode boundary. Missing backend data or operations must be added to the server API and generated SDK rather than imported from backend implementation modules.

Migration Rules

• Keep one canonical implementation of every TUI feature. Do not copy the full TUI into packages/cli and synchronize two trees.
• Land each section below independently and commit it before starting the next section.
• Keep each intermediate commit buildable and type-safe.
• Continue integrating team changes into whichever location is canonical for a file at that point in the migration.
• Use temporary compatibility re-exports only when they materially reduce the size or conflict risk of a section. Mark them for removal in a later section.
• Do not preserve private imports by creating aliases from packages/tui back into packages/opencode.
• Do not replace private packages/opencode imports with @opencode-ai/core imports merely to make the package compile.
• Keep tool rendering tolerant of unknown tools and wire-format changes. Local checks over unknown input and metadata are acceptable; importing backend tool implementations for type safety is not.
• Keep legacy CLI command parsing, server startup, worker management, authentication, and config discovery outside @opencode-ai/tui.

Ownership Boundary

@opencode-ai/tui Owns

• OpenTUI renderer lifecycle shared by both CLI hosts
• Solid application composition
• Components, routes, dialogs, themes, keymaps, and UI primitives
• SDK client synchronization and event consumption
• Tool-call and tool-result presentation
• TUI-facing plugin contracts and presentation slots
• Resolved TUI configuration types, defaults, and pure validation
• Terminal behavior such as selection, clipboard integration, and local editor launching when it is not host-specific
• TUI-local persistence such as prompt history, stash, frecency, selected model, and selected theme
• Presentation utilities such as locale formatting, error display, record checks, duration formatting, and layout helpers

CLI Hosts Own

• Command definitions and argument parsing
• Starting, locating, and stopping servers and workers
• Authentication and transport construction
• Process-level signal policy
• Config file discovery, precedence, migration, and environment substitution
• Plugin package discovery, installation, and backend activation
• Upgrade checks and installation metadata
• Executable build wiring and worker path defines

Server And SDK Own

• OpenCode domain data displayed by the TUI
• Session, message, workspace, file, provider, model, agent, and permission operations
• Retry, revert, fork, share, and other backend actions
• Stable wire shapes for tool parts and plugin metadata
• Server capabilities needed to conditionally expose UI behavior

Current Boundary

The canonical implementation currently lives under:

packages/opencode/src/cli/cmd/tui

Its private dependency on packages/opencode is primarily expressed through the @/* TypeScript alias, which resolves to packages/opencode/src/*. @tui/* imports are internal to the TUI and are not themselves a package boundary problem.

The main private dependency groups are:

• @/util/*: presentation helpers plus filesystem/process/RPC helpers
• @/tool/*: backend tool implementations used by renderers
• @/session/*, @/provider/*, and @/reference/*: backend data and actions
• @/config/*: config discovery, parsing, variables, and plugin resolution
• @/plugin/*: plugin loading and installation
• @/cli/*: yargs adapters, network setup, errors, and CLI presentation
• @/server/*: authentication and embedded server behavior
• Global.Path, Flag, and process environment reads

The initial extraction should reduce these dependencies in place before moving the application root.

Section 1: Create The Package Skeleton

Status: Completed. The private @opencode-ai/tui workspace package now has an independent OpenTUI Solid JSX configuration, narrow root export, package-local alias, and in-memory render smoke test. Neither CLI consumes the package yet.

Create packages/tui without moving the application root yet.

Tasks:

• Add packages/tui/package.json with the name @opencode-ai/tui.
• Add a package tsconfig.json configured for OpenTUI Solid JSX.
• Add bunfig.toml with the OpenTUI Solid preload for package-local development and tests.
• Add package scripts for typecheck and package-local tests.
• Add direct dependencies used by the TUI. Do not rely on workspace hoisting.
• Add a narrow package export, initially only the package root and any explicit testing entrypoint needed by migrated tests.
• Establish a package-local import convention. A local alias such as @tui/* is acceptable, but it must resolve entirely inside packages/tui.
• Add a minimal package entrypoint and smoke test proving OpenTUI Solid TSX can typecheck and render.
• Do not make either CLI consume the package yet.

Exit criteria:

• packages/tui typechecks independently.
• Its test command runs from packages/tui.
• The package has no dependency on opencode, @opencode-ai/cli, or @opencode-ai/core.

Checkpoint commit:

feat(tui): add standalone package skeleton

Section 2: Move Presentation Utilities And Leaf UI

Status: Completed. Presentation utilities, bundled themes and their pure theme engine, keybinding/keymap mechanics, and low-coupling border, link, and spinner primitives now live in @opencode-ai/tui. The legacy host consumes explicit package exports and retains only integration wrappers or compatibility re-exports where backend and process concerns have not moved yet.

Move low-coupling code first so subsequent team changes land in the new package without waiting for the application root migration.

Tasks:

• Move TUI presentation utilities into packages/tui/src/util, including the portions of locale, error display, record checks, duration formatting, and small functional helpers used by TUI code.
• Move pure TUI utilities already under the old TUI directory.
• Move themes and bundled theme JSON files.
• Move UI primitives and leaf components that have no private backend imports.
• Move pure keybinding schemas and keymap helpers that do not read host flags.
• Move related unit and snapshot tests.
• Update remaining old-tree consumers to import the new canonical modules.
• Use temporary compatibility re-exports from old TUI paths only if needed to avoid a large unrelated import rewrite.
• Do not move Filesystem, Process, Rpc, worker startup, or config discovery as generic utilities in this section.

Exit criteria:

• Moved files have no @/... imports.
• Tests for moved code run from packages/tui.
• Existing legacy TUI behavior and typecheck remain unchanged.

Checkpoint commit:

refactor(tui): move presentation utilities and primitives

Section 3: Remove Backend Tool Implementation Imports

Status: Completed. Legacy and V2 tool renderers now dispatch on SDK wire names, accept Record<string, unknown> input and metadata, and use local guards for nested presentation data. Web-search labels and structured metadata extraction are TUI-owned, unknown tools retain the generic fallback, and no TUI source imports backend tool implementations. The route components remain in the legacy tree until the SDK state and route move in Section 6.

Make tool rendering depend only on SDK wire data and local presentation logic.

Tasks:

• Remove imports from @/tool/* in TUI routes and feature plugins.
• Key built-in renderers by SDK tool name strings such as read, write, edit, apply_patch, grep, glob, bash, question, and task.
• Treat tool input, output metadata, and plugin-defined fields as unknown at the package boundary.
• Add small local type guards only where a renderer needs a particular field.
• Preserve a generic fallback renderer for unknown and plugin-provided tools.
• Keep renderer failures local: malformed metadata must not crash the entire session view.
• Replace backend-derived labels or IDs with TUI-owned presentation constants or SDK-provided values.
• Move the affected tool presentation components and tests to packages/tui.

Exit criteria:

• No TUI source imports @/tool/*.
• Unknown tools render through the generic fallback.
• Existing built-in tool snapshots remain equivalent unless intentionally updated and reviewed.

Checkpoint commit:

refactor(tui): decouple tool rendering from backend tools

Section 4: Make Runtime Inputs Explicit

Status: Completed for the shared runtime contract and legacy host. The TUI now receives immutable launch-directory, path, capability, terminal/editor, startup, and build inputs through @opencode-ai/tui/runtime. Movable app, component, route, and feature-plugin code no longer reads OpenCode globals or process state; command, config, plugin-loading, custom-theme discovery, editor/clipboard, and Windows lifecycle adapters remain host-owned. packages/cli does not consume this contract yet; that integration remains deferred to Section 9.

Replace process-global OpenCode state with resolved TUI inputs.

Define narrow inputs rather than one unstructured host object. Expected groups include:

type TuiCapabilities = {
  mouse: boolean
  copyOnSelect: boolean
  terminalTitle: boolean
  workspaces: boolean
  showTimeToFirstDraw: boolean
}

type TuiPaths = {
  home: string
  state: string
  config: string
  data: string
}

type TuiBuildInfo = {
  version: string
  channel?: string
}

Tasks:

• Inventory direct reads of Flag, Global.Path, and relevant environment variables in movable TUI code.
• Pass resolved capabilities into the application/provider tree.
• Pass local path roots or a narrow TUI storage capability into persistence contexts.
• Pass build/version information explicitly.
• Keep environment reads needed by legacy command or worker startup in packages/opencode adapters.
• Give packages/tui sensible host-neutral defaults only when behavior is truly local to a terminal client.
• Move contexts and components after their global dependencies are removed.

Exit criteria:

• Movable TUI code does not import Flag or Global.
• TUI tests can supply deterministic capabilities and storage paths.
• The legacy host constructs the required input through the public package API; the new CLI integration remains deferred to Section 9.

Checkpoint commit:

refactor(tui): make runtime capabilities explicit

Section 5: Separate Resolved TUI Config From Host Config Loading

Status: Completed for the package config contract and legacy host adapter. @opencode-ai/tui/config now owns schemas, defaults, keybind resolution, the resolved config type, and the Solid config provider. The legacy host retains file discovery, precedence, JSONC parsing, substitutions, migration, source-relative sound paths, plugin origins, dependency installation, and Effect services. packages/cli remains untouched until Section 9.

Move config semantics needed by rendering while retaining filesystem discovery and migration in the legacy host.

Tasks:

• Move TUI config schemas, keybind schemas, defaults, and pure resolution to packages/tui.
• Define the resolved config accepted by the public TUI entrypoint.
• Keep config path discovery, project/global precedence, migration, variable expansion, and plugin package installation in packages/opencode initially.
• Make the legacy host produce the same resolved config shape.
• Add a new CLI adapter that can initially provide defaults or its own resolved configuration.
• Update schema-generation imports to use the package's explicit config export if schema generation still needs TUI schemas.
• Move pure config tests; retain discovery and migration integration tests in packages/opencode.

Exit criteria:

• packages/tui does not import @/config/*.
• Config discovery can change without changing TUI rendering code.
• The old CLI still honors existing config precedence and migration behavior.

Checkpoint commit:

refactor(tui): separate config resolution from loading

Section 6: Move SDK State, Routes, And Backend Operations

Status: Completed for the SDK/domain boundary. SDK, project, event, legacy sync, V2 sync, local model state, prompt persistence, and pure prompt helpers are now canonical in @opencode-ai/tui. Configured references resolve through the new generated reference.list SDK operation; prompt payloads rely on optional server-assigned IDs; local attachment reads use the package platform contract. Legacy route files remain in place until the plugin slot boundary and app-root move, but their only private dependencies are plugin presentation or local host adapters rather than OpenCode domain implementations.

Make the SDK the only OpenCode domain boundary used by the TUI.

Tasks:

• Move SDK client providers, event synchronization, routes, prompt UI, and session views into packages/tui.
• Replace direct imports from @/session/*, @/provider/*, @/reference/*, @/lsp/*, and other backend domains with SDK data or TUI-owned presentation helpers.
• Replace direct backend actions such as retry with SDK calls.
• For each missing operation, add or adjust the server endpoint, regenerate the JavaScript SDK with ./packages/sdk/js/script/build.ts, and consume the generated SDK API.
• Keep transport creation outside the package. Accept a base URL, headers, custom fetch, event source, or constructed SDK client as appropriate.
• Keep local-only UI state in the TUI package rather than adding it to the server API.
• Move affected tests and fixtures. Use real SDK/server integration where practical instead of mocking backend modules.

Exit criteria:

• Domain-facing TUI code imports OpenCode data and operations only from @opencode-ai/sdk.
• No TUI source imports private session, provider, reference, LSP, server, or core domain implementations.
• SDK generation is clean after any API changes.

Checkpoint strategy:

This section may be split into multiple commits when an SDK gap is substantial. Each commit must leave both the old TUI host and package tests working. Suggested commit pattern:

feat(sdk): expose <operation> for tui clients
refactor(tui): move <area> to sdk boundary

Final section checkpoint:

refactor(tui): move sdk state and routes into package

Section 7: Isolate Plugin Presentation From Plugin Loading

Status: Completed. Plugin slots, route registration, TUI-facing APIs, runtime presentation state, and built-in feature plugins now live in @opencode-ai/tui. The legacy host injects a narrow plugin host that retains discovery, installation, manifest/config mutation, external module execution, pure-mode filtering, and cleanup ownership. Missing or failing plugin hosts degrade to the base TUI without blocking startup.

Keep plugin UI extensibility without importing the legacy plugin installer and loader into the TUI package.

Tasks:

• Move plugin presentation slots, route contracts, and TUI-facing APIs into packages/tui or the existing public plugin TUI contract package.
• Keep package discovery, installation, manifest resolution, backend activation, and process lifecycle in the host.
• Define the serialized or runtime plugin presentation data the TUI requires.
• Prefer SDK-delivered plugin metadata when the behavior must also work for a remote server.
• Make plugin absence or incompatibility degrade gracefully.
• Move plugin rendering tests to packages/tui; retain installation/loading integration tests in packages/opencode.

Exit criteria:

• packages/tui does not import @/plugin/* or the old TUI plugin runtime.
• Remote and local TUI clients have a defined plugin behavior.
• Plugin UI failures cannot prevent the base TUI from starting.

Checkpoint commit:

refactor(tui): separate plugin presentation from loading

Section 8: Move The Application Root And Renderer Lifecycle

Status: Completed. packages/tui now owns the canonical application root, provider composition, routes, components, parser presentation, renderer configuration, and renderer lifecycle. Process mutation, Windows console handling, backend worker startup, config loading, plugin loading, native audio, and legacy platform implementations remain injected host adapters. Old source paths are temporary compatibility re-exports for the legacy command host.

Move the canonical app composition after its dependencies have already crossed the package boundary.

Tasks:

• Move app.tsx, remaining providers, routes, components, attention handling, keymaps, and renderer lifecycle to packages/tui.
• Export a narrow public API such as:

export type TuiInput = {
  url: string
  directory?: string
  headers?: RequestInit["headers"]
  fetch?: typeof fetch
  config: TuiConfig.Resolved
  capabilities: TuiCapabilities
  paths: TuiPaths
}

export function run(input: TuiInput): TuiHandle
export function createRenderer(config: TuiConfig.Resolved): Promise<CliRenderer>

• Preserve the existing lifecycle guarantees: readiness, waiting until exit, idempotent cleanup, renderer destruction, SIGHUP handling where appropriate, and terminal restoration.
• Keep Windows process adapters outside the package if they mutate host process state; invoke them from CLI adapters around the package lifecycle.
• Keep OpenTUI parser-worker embedding in executable build scripts.
• Move app lifecycle and rendering tests to packages/tui.

Exit criteria:

• packages/tui contains the canonical application root.
• The package has no imports from packages/opencode, packages/cli, or @opencode-ai/core.
• The package public API is sufficient for both old and new CLI adapters.

Checkpoint commit:

refactor(tui): move application root into package

Section 9: Convert Both CLIs To Thin Adapters

Status: Completed. The legacy thread and attach commands now lazily invoke the public @opencode-ai/tui root while retaining worker/server/config/plugin and process adapters. The new CLI default command launches the same package against its authenticated daemon transport with a minimal local platform/host. Missing legacy provider/config APIs currently degrade to the shared provider-connect screen; source and compiled new-CLI behavior match, while named commands remain outside the TUI path.

Make both executable packages consume the same TUI package.

Tasks:

• Keep the legacy yargs commands corresponding to current thread.ts and attach.ts in packages/opencode.
• Keep the legacy embedded worker and server startup in packages/opencode.
• Change those adapters to load config, create transport inputs, and call the public @opencode-ai/tui API.
• Change packages/cli's default command handler to call the same public API.
• Remove the temporary packages/cli/src/tui shell after the shared package is integrated.
• Remove duplicated OpenTUI lifecycle code from both hosts.
• Ensure non-TUI subcommands remain lazily isolated from OpenTUI startup.
• Update executable build scripts to bundle the shared package, parser worker, assets, and any retained host worker.

Exit criteria:

• Both CLIs launch the same package implementation.
• There is no duplicate TUI source tree in packages/cli.
• Legacy attach and local-worker modes still work.
• Named non-TUI commands do not launch or eagerly initialize the TUI.

Checkpoint commit:

refactor(cli): share tui package across command hosts

Section 10: Remove Compatibility Paths And Finish Ownership

Status: Completed. Package source imports are self-contained, package exports are narrowed to active host contracts, package-owned tests and snapshots live under packages/tui, and the obsolete compatibility tree has been removed. Legacy command, worker, config, plugin-loader, process, editor, audio, and event adapters now live in explicit host-owned locations outside src/cli/cmd/tui/.

Delete migration scaffolding only after both hosts consume the package.

Tasks:

• Remove old TUI compatibility re-exports and the obsolete directory tree under packages/opencode/src/cli/cmd/tui.
• Retain and relocate only true host adapters such as legacy commands, worker, transport setup, and config loading.
• Remove obsolete @tui/* path mappings from packages/opencode.
• Remove stale test fixtures and update all imports to package exports.
• Narrow @opencode-ai/tui exports to intentional public entrypoints.
• Verify package manifests list every direct dependency and no accidental dependency is supplied only by workspace hoisting.
• Update repository documentation describing TUI ownership and development.

Exit criteria:

• No production import references the old TUI source location.
• No source under packages/tui imports @/..., @opencode-ai/core, or either executable package.
• The old TUI directory contains no canonical implementation files.
• The dependency graph has no cycle.

Checkpoint commit:

refactor(tui): complete standalone package extraction

Invariants To Preserve

• There is one canonical TUI implementation at every migration stage.
• Legacy TUI behavior remains available until its host is intentionally removed.
• The default new CLI command launches the TUI, while named subcommands continue to route to their own handlers.
• Renderer cleanup restores the terminal on normal exit, interruption, startup failure, and renderer destruction.
• TUI package imports do not reach into executable or backend implementation packages.
• SDK wire data is treated as the source of truth for OpenCode domain state.
• Unknown tools and plugin data render safely without backend type imports.
• Remote-server use remains possible; the TUI must not require an in-process backend implementation.
• TUI-local persistence remains local and does not become server state unless there is an explicit product requirement.
• Team changes should be moved with their canonical file, not manually copied between old and new implementations.

Verification Gates

Run verification after every section, adding narrower tests for the area being moved.

Package checks:

cd packages/tui && bun typecheck
cd packages/tui && bun test
cd packages/opencode && bun typecheck
cd packages/cli && bun typecheck

Dependency checks:

rg "from ['\"]@/" packages/tui/src
rg '@opencode-ai/core|packages/opencode|packages/cli' packages/tui
rg 'src/cli/cmd/tui|@tui/' packages/opencode/src packages/opencode/test

SDK checks when server APIs change:

./packages/sdk/js/script/build.ts
git diff --check

Interactive smoke checks should run in tmux so the terminal can be captured and cleaned up reliably:

• Start the legacy local TUI and confirm initial render.
• Start legacy attach mode against a server.
• Start the new CLI default command and confirm it renders the same package.
• Exit each mode with Ctrl-C and verify the process and terminal are restored.
• Run representative named commands in both CLIs and verify they do not launch the TUI.

Compiled checks:

• Build the current-platform packages/opencode binary.
• Build the current-platform packages/cli binary.
• Run TUI and non-TUI smoke checks against both compiled binaries.
• Verify theme JSON, audio assets, OpenTUI parser worker, and retained backend worker assets are included.

Progress Tracking

• Section 1: Create the package skeleton
• Section 2: Move presentation utilities and leaf UI
• Section 3: Remove backend tool implementation imports
• Section 4: Make runtime inputs explicit
• Section 5: Separate resolved TUI config from host config loading
• Section 6: Move SDK state, routes, and backend operations
• Section 7: Isolate plugin presentation from plugin loading
• Section 8: Move the application root and renderer lifecycle
• Section 9: Convert both CLIs to thin adapters
• Section 10: Remove compatibility paths and finish ownership

Update each section's status and this checklist in the same commit that completes the section.