dsh-phosphor

A full-screen, Matrix-styled TUI frontend for DeepSeek Harness — built with React + Ink as a Cordis bundle plugin.

中文文档

█▓▒ PHOSPHOR ▒▓█

Status: source-only distribution (for now)

dsh is in developer preview and explicitly warns about breaking changes. This plugin is tightly coupled to the host's internal plugin APIs — a host upgrade can break it silently (we have been bitten by exactly this). Shipping an npm package or tarball today would fake stability: no update channel, no version guard, and a broken TUI after the next host rc.

So, until dsh ships a stable release:

• Source only. You clone, build, and link against your own dsh checkout — which forces you to know exactly which host revision you are running.
• Pinned baseline: dsh v0.1.1-rc.2 (commit b150a551b8). Other revisions may work, but are untested.
• dsh plugin add github:... is NOT supported. pnpm runs prepare inside its own cache directory, where this repo's link: devDependencies cannot resolve. Use the source flow below.
• Once dsh stabilizes, we will realign the code and publish to npm properly.

Requirements

• Node.js ^22.19 || >=24, pnpm
• A deepseek-harness source checkout, built (pnpm install && pnpm run build)
• Developed against Windows Terminal; other terminals are untested (see Known limitations)

Install from source

The plugin resolves its @deepseek-ai/* dev dependencies through relative links, so the two repositories must sit in the same parent directory:

<workspace>/
├── deepseek-harness/     # dsh source checkout (pinned baseline)
└── dsh-phosphor/         # this repo

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness && git checkout b150a551b8 && pnpm install && pnpm run build && cd ..

git clone https://github.com/yaotongsb/dsh-phosphor.git
cd dsh-phosphor && pnpm install && pnpm build

# One-time registration into a profile (run from the dsh checkout,
# so the relative path resolves):
cd ../deepseek-harness
pnpm dsh plugin --profile tui add ../dsh-phosphor

Run

dsh treats the launch directory as the workspace root — start it from whatever project you want to work on. pnpm dsh only exists inside the dsh checkout; for daily use, launch the built CLI directly from any directory:

cd your-project
node /path/to/deepseek-harness/apps/cli/lib/bin.js --profile tui

An alias saves the typing:

# ~/.bashrc
alias dsh-tui='node /path/to/deepseek-harness/apps/cli/lib/bin.js --profile tui'

Rebuild after any plugin change (pnpm build in dsh-phosphor) — the profile links to the directory, so the next launch picks up the new lib/.

Commands

Phosphor's own commands:

Command	Description
/help	Command help
/model	Model picker — type to filter, Shift+Tab cycles reasoning effort
/new	New session (Ctrl+N)
/resume	Session picker — type to filter, a archives the highlighted session
/attach <path>	Attach an image to the next message (requires a vision model; png/jpeg/webp/gif)
/detach	Clear pending attachments
/plugins	Host plugin inventory (loader reflection: state, fiber phase, config)
/settings	Runtime settings panel (permission presets + visuals)
/theme matrix|terminal	Switch theme
/exit, /quit	Quit

Provided by the host (dsh-base), routed through phosphor's UI:

Command	Description
/compact	Compact conversation history
/plan	Plan mode (full-screen review overlay)
/goal	Track a session goal
/permission	Permission settings
/feedback	Send feedback

Key bindings

Global:

Key	Action
Ctrl+C	Quit
Ctrl+L	Full-screen repaint (clears any ghost frames)
PgUp / PgDn	Scroll transcript back/forward

Editor:

Key	Action
Tab / ↑ / ↓	Navigate slash-command hints
@	File-reference completion (fuzzy, cwd-rooted)
↑ ↓ ← → Home End	Cursor movement (multiline-aware)
Ctrl+U	Clear current line
Esc	Cancel / close overlay

With an empty input buffer:

Key	Action
Alt+T / Alt+J / Alt+F	Open side panel: TRACE / JOBS / FILES
Alt+O	Collapse/expand the side panel
Alt+1..9	Jump to a recent session
Ctrl+N	New session
x	Kill the selected job (JOBS panel, ↑/↓ to select)

Overlays:

Context	Keys
Plan review	↑↓ / PgUp/PgDn scroll · y approve · n keep planning · o feedback · Esc exit to talk
Approval bar	y approve · n reject
Resume picker	type to filter · a archive · Enter open

Configuration

All options are validated by a Schemastery schema and set through cordis.yml layers — e.g. your profile's ~/.dsh/profiles/tui/cordis.patch.yml:

- id: phosphor
  config:
    theme: matrix
    matrixRainFps: 8

Key	Type	Default	Description
theme	matrix | terminal	matrix	Color scheme
matrixRain	boolean	true	Digital-rain background layer
matrixRainFps	2–24	8	Rain frame rate cap (auto-throttles under load)
scanlines	boolean	false	CRT scanline overlay
panelWidth	16–48	26	Side panel width in columns
panelMode	trace | jobs | files	trace	Panel shown at startup
showReasoning	boolean	false	Expand reasoning blocks by default
showInjected	boolean	false	Render injected context (AGENTS.md, hooks) in full
verboseStatus	boolean	false	Verbose status-bar counters

Runtime toggles for the visual options live under /settings; the config file sets the persistent defaults.

Themes

• matrix — black + three-tone neon green, digital rain, breathing status dot, optional scanlines. The rain renders only through empty cells and halves its frame rate under load.
• terminal — your terminal's 16-color palette; every animation degrades to static.

Known limitations

• Version-locked to dsh v0.1.1-rc.2; host upgrades may break things until the declared stable release.
• Images are never rendered in the terminal — a dim placeholder line (▣ name (W×H)) marks attachments.
• No persistent plan-mode badge (the mode itself works; only the indicator is missing).
• Resuming very long sessions is slow (host-side log replay), and the rain frame rate adapts to system load on purpose.
• No un-archive in V1; archiving shares web UI state (~/.dsh/storages), and concurrent dsh processes are last-writer-wins.
• Developed and tested on Windows Terminal only.

Development

pnpm install     # requires the sibling deepseek-harness checkout
pnpm test        # vitest, 426 tests
pnpm typecheck   # tsc --noEmit
pnpm build       # tsdown → lib/

The development loop runs from the dsh checkout: pnpm dsh --profile tui.

The codebase is compact and layered (bridge/ → store/ → ui/, with pure-function transcript projection in between); start from src/index.ts and the tests sitting next to each module. Contributions welcome.

License & credits

MIT © yaotongsb

The markdown renderer (src/ui/markdown.ts: block structure, table column-width algorithm, streaming fence trim, inline base-style restore) is ported from PI (packages/tui/src/components/markdown.ts) — MIT License, Copyright (c) 2025 Mario Zechner.