dsh-cctui

Readme

# dsh-ccTUI

**Claude Code style TUI for Deepseek-Harness** — 🐳 ported from the clawcodex `ui-tui` and
packaged as a `dsh` bundle plugin (npm package `dsh-cctui`).

The full Claude-Code-style look, feel, and interactions — streaming markdown transcript, tool trail
with diff cards, approval and question prompts, plan review, session switcher and resume,
slash commands, model picker, context bar — running **in-process** against harness services
(`ctx.agents`, `session/event`, the approval waterfall, `ctx.userQuestions`, `ctx.commands`).

```
 ██████╗ ███████╗██╗  ██╗         ██████╗ ██████╗████████╗██╗   ██╗██╗
 ██╔══██╗██╔════╝██║  ██║        ██╔════╝██╔════╝╚══██╔══╝██║   ██║██║
 ██║  ██║███████╗███████║ █████╗ ██║     ██║        ██║   ██║   ██║██║
 ██║  ██║╚════██║██╔══██║ ╚════╝ ██║     ██║        ██║   ██║   ██║██║
 ██████╔╝███████║██║  ██║        ╚██████╗╚██████╗   ██║   ╚██████╔╝██║
 ╚═════╝ ╚══════╝╚═╝  ╚═╝         ╚═════╝ ╚═════╝   ╚═╝    ╚═════╝ ╚═╝
 🐳 Claude Code style TUI for Deepseek-Harness

 ╭─── dsh-ccTUI v0.3.0 ─────────────────────────────────────────────────────────────────────────╮
 │                                                                                              │
 │           Welcome back, you                 │ ▾ Available Tools                              │
 │                                             │ harness: bash, create_goal, edit, …+22         │
 │                    : ' :                    │                                                │
 │                 ___'_______                 │ ▸ Available Skills (0)                         │
 │               /'  o        \--.             │                                                │
 │              |              ___\            │ ────────────────────────────────────────────── │
 │               \____________/  \/            │ 25 tools · 0 skills · /help for commands       │
 │                  \__/  \__/                 │                                                │
 │                                             │                                                │
 │                ────────────                 │                                                │
 │           Model deepseek-v4-flash           │                                                │
 │   Path ~/workspace/dsh-ccTUI                │                                                │
 │    Perms Ask for approval · /permissions    │                                                │
 │ Session cctui-56b37bee-41fd-4feb-b270-5988… │                                                │
 │                                                                                              │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────╯
```

## Install

Requires Node ≥ 22.19, npm, pnpm, and the `dsh` CLI (`npm install -g @deepseek-ai/dsh`).

```sh
git clone https://github.com/agentforce314/dsh-ccTUI.git
cd dsh-ccTUI
./install.sh           # builds, then: dsh plugin --profile dsh-cctui add "$PWD"
dsh --profile dsh-cctui # launch (or ./bin/dsh-cctui.js)
```

Model/provider configuration comes from your dsh profile (`agent-default-model` settings or
an `- id: cctui` config override in the profile's `cordis.patch.yml`: `provider`, `model`,
`cwd`, `sessionId`).

### API key

The TUI stores no key; the harness resolves one per request. Write it to the managed store
at `$DSH_HOME/.credentials.yaml` (default `~/.dsh/.credentials.yaml`) — a YAML mapping of
credential reference to value and nothing else:

```yaml
DEEPSEEK_API_KEY: sk-…
```

`chmod 600` that file and `chmod 700 ~/.dsh`: `dsh-credentials-local` refuses to read a
document carrying any group or other permission bit, and fails at boot naming the repair.
The document is watched, so a key stored while the TUI is running takes effect on the next
request — first run is "browse models, store the key, prompt again", no restart in between.
Until one resolves, the route stays registered and `/model` stays browsable; it is the
request that fails, with `MISSING_CREDENTIAL` naming every entry point it looked at.

The launching environment beats the store (`DEEPSEEK_API_KEY=… dsh --profile dsh-cctui`) and
is deliberately read-only from inside; the store in turn beats `<cwd>/.env` and
`~/.dsh/.env`. Keep the key itself out of `cordis.patch.yml` — adapter config carries only
`apiKeyEnv`, the reference to resolve. One key covers both the conversation and the
`web_search` tool.

Mode `0600` stops other OS users, not the model: the harness never hands it the document's
path and never loads the value into the environment, but bash and the filesystem tools run
as you and the shipped policy confines writes rather than reads.

## Highlights

- **Conversation loop**: streamed deltas render live; reasoning shows a line or two with the
  whole chain of thought behind Ctrl+O; busy verbs and spinners; Esc interrupts (Ctrl+C never
  kills the app).
- **Tools**: Claude-style `⏺ Tool(args)` / `⎿ result` trail — every call keeps its own row
  with the path it opened or the command it ran, over a few lines of what came back and
  `… +N lines (ctrl+o to expand)`; a failed call carries the tool's own message and a running
  one its own clock; write/edit diffs render as structured diff cards; sandbox-escalation
  approvals pop the approval box (`1` approve / `2`+Enter deny); todo lists pin under the
  busy line.
- **Subagents**: a delegation reads `⏺ Subagent(Review the diff)` / `⎿ Done (2 tool uses ·
  1.2k tokens · 11s)`, and its children stream into `/agents` — goal, live tool calls,
  tokens, spawn tree.
- **Sessions**: `/sessions` (Ctrl+X) lists live and persisted sessions; `/resume <id>`
  replays a persisted transcript, tool results and all; `/new`, `/title`, `/rename`.
- **Commands**: every harness `ctx.commands` entry (e.g. `/plan`, `/goal`) appears in the
  completion menu and dispatches through the harness; `/model` opens the picker backed by
  the llm catalog; `/effort`, `/context`, `/usage`, `/help`, `/status`.
- **Modes**: Shift+Tab cycles default → plan → bypassPermissions (mapped onto the harness
  plan-mode controller and approval policy).

## Configuration

Environment knobs use the `DSH_CCTUI_` prefix — e.g. `DSH_CCTUI_INLINE=0` (alternate screen
instead of inline scrollback), `DSH_CCTUI_THEME=light|dark`, `DSH_CCTUI_HOME` (data dir,
default `~/.dsh-cctui`), `DSH_CCTUI_FPS=1`. `CLAUDE_CODE_SCROLL_SPEED` is still honored as a
migration fallback for people coming from Claude Code.

## Development

```sh
npm install
npm run typecheck && npm test    # 149 files / ~1900 tests
npm run e2e                      # PTY e2e against a real dsh boot + scripted LLM
npm run e2e:install              # the real `dsh plugin add` install path
```

Tool rows are the fiddliest surface to eyeball, so they have their own harness:
`python3 scripts/tool-gallery.py [tool…] [--expand]` drives a real dsh boot through one
harness tool per scenario (via the scripted `test/e2e/probe-llm.mjs`) and prints the trail it
rendered — the thing to diff against the same call made to Claude Code.

### Versioning

Each shipped change increments the **patch** digit by one; it runs to 99 before rolling over
into the minor digit:

```
0.2.0 → 0.2.1 → … → 0.2.13 → … → 0.2.99 → 0.3.0 → 0.3.1 → …
```

Write patch numbers without leading zeros (`0.3.1`, not `0.3.01` — the latter is not valid
semver and npm rejects it). Bump `package.json` in the change's own commit, then tag
`v<version>` on `main` after it merges.

Architecture and porting details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md),
[docs/PLAN.md](docs/PLAN.md), [docs/PORTING-NOTES.md](docs/PORTING-NOTES.md). The adapter
boundary (`src/harness/` is the only place that may import `@deepseek-ai/*`) is CI-gated.

## Provenance & license

MIT. Substantial portions are ported from the MIT-licensed clawcodex `ui-tui` (including its
forked Ink renderer) with integration patterns from the MIT-licensed dsh-TUI project — see
[NOTICE.md](NOTICE.md).