Blue

English | 中文

Blue is an interactive terminal UI (TUI) for DeepSeek Harness (dsh): a pi-tui renderer mounted as an out-of-tree Cordis plugin bundle on top of the dsh-base bundle. This repository contains sixteen workspace packages — twelve in the 0.1.2-alpha.1 release set and four validation-only adapters — built and tested against the published Harness 0.1.2-alpha.2 line.

Blue in action: streaming transcript, tool cards, and dock panes — watch the full demo video.

Design philosophy

A TUI is not a package — it is a Cordis plugin tree. Every render component, interaction provider, command, and status entry is a separate plugin with its own fiber lifecycle: hot-swappable and omittable at will.

• Registration is an effect — mounts, provider registrations, and keybindings bind through ctx.effect/ctx.on, so unloading a plugin rolls everything back; HMR and session switching come free.
• Dependency-derived loading — plugins inject what they need and wait until the services exist; a provider hot-swap unloads and reloads its dependents automatically.
• plain-first — every non-trivial surface is a seam plus a plain default implementation. Blue's own enhancements register through the same seams as downstream plugins; the bundle with every enhancement row removed still boots and works.
• One pi-tui import — only packages/core imports @earendil-works/pi-tui, and no public contract mentions a pi-tui type.

The full story: docs/blue-architecture.md · decisions (ADR): docs/blue-decisions.md (both Chinese).

Usage

Prerequisites: Node ^22.19 || >=24 and pnpm 11. The recommended launcher includes its tested dsh runtime.

npm i -g @deepseek-ai/dsh
dsh plugin --profile blue add @dsh-blue/blue@alpha
dsh --profile blue

Or use the recommended one-command blue launcher; it carries the tested Harness tree as common and platform archives, so npm never resolves that graph during installation:

npm i -g @dsh-blue/blue-cli@alpha
blue

Set DEEPSEEK_API_KEY before the first run. Key bindings and slash commands are listed live by /help and documented in the key reference and command reference; the quickstart walks through the first run, and the configuration guide covers providers, models, and themes.

Architecture

flowchart TB
    ROOT["dsh process — a single Cordis tree<br/>Loader · Fiber lifecycle · event/service bus"]

    subgraph BASE["dsh-base rows · Harness domain plugins"]
        HAR["agents · sessions · tools · approval<br/>commands · events"]
    end

    subgraph BLUE["Blue rows — 34 Fiber plugins composed by cordis.patch.yml (unload rolls back · hot-swappable · omittable)"]
        direction TB
        subgraph DOM["Domain side — the only holder of Agent/Session objects"]
            direction LR
            CONV["blue-conversation<br/>Harness events → projections"]
            APP["blue-app<br/>blueSessionReader · blueSessionActions"]
        end
        subgraph UI["UI side — sees only readonly data and actions"]
            direction TB
            FE["blue-api · blue-ui · blue-frontend<br/>UI wire/builders · readonly models · provider host"]
            ADP["blue-transcript · blue-interaction<br/>transcript · commands · panels · status bar · dock"]
            KRN["blue-core — TUI kernel<br/>the tree's only pi-tui import"]
            FE --> ADP
            ADP --> KRN
        end
        CONV -- "projection · current state" --> FE
        APP -- "readonly snapshot" --> FE
        UI -- "action · write request with BlueResult" --> DOM
    end

    TERM["Terminal — pi-tui · ANSI · keyboard"]

    ROOT --> BASE
    ROOT --> BLUE
    HAR ==> CONV
    HAR ==> APP
    KRN --> TERM

    linkStyle 2,3,4 stroke:#2bc8e8,stroke-width:3px

The runtime flow is Harness domain -> projection/action boundary -> renderer-neutral models -> TUI feature plugins -> core. Events state facts, projections hold current state, and actions are write requests with structured results; Blue never keeps a second agent truth, and Agent/Session objects never cross into renderers. The row-by-row bundle composition (34 Blue-owned rows over dsh-base) is documented in the bundle guide, and the feature tour is on the website.

Documentation

• User manual — quickstart · features · key & command reference (中文: 指南 · 功能 · 参考)
• Plugin marketplace — browse & install plugins · submit yours (中文: 插件市场 · 收录指南)
• Developer manual — writing a plugin · UI kit · seam reference · contributing
• Harness handbook — dsh concepts, profiles, tools, MCP
• Design documents (Chinese, repo-internal) — the living/archived index is docs/README.md; repo-wide conventions live in AGENTS.md and each package's own AGENTS.md.

License

MIT. Every package under the @dsh-blue scope declares license: MIT.