dsh-phosphor

Readme

# dsh-phosphor

A full-screen, Matrix-styled TUI frontend for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — built with React + Ink as a Cordis bundle plugin.

[中文文档](README.zh.md)

```
█▓▒ PHOSPHOR ▒▓█
```

![matrix theme](docs/screenshots/matrix.png)
![terminal theme](docs/screenshots/terminal.png)

## 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](https://github.com/deepseek-ai/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
```

```sh
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:

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

An alias saves the typing:

```sh
# ~/.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`:

```yaml
- 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

```sh
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](LICENSE) © 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.