deep-flow

A terminal UI (TUI) for DeepSeek Harness: an interactive Ink REPL shipped as an out-of-tree dsh bundle riding over dsh-base. No Host, HTTP server, or browser — everything runs in-process against the composed Cordis tree.

Published on npm as @jkxie/dsh-deep-flow. 中文说明见 README.zh-CN.md。

░████  ░█████ ░█████ ░████     ░█████ ░█     ░████ ░█   █
░█   █ ░█     ░█     ░█   █    ░█     ░█     ░█  █ ░█   █
░█   █ ░███   ░███   ░████     ░███   ░█     ░█  █ ░█   █
░█   █ ░█     ░█     ░█        ░█     ░█     ░█  █ ░█ █ █
░████  ░█████ ░█████ ░█        ░█     ░█████ ░████  ░█ █

Features

• Default new session — boot drops you straight into a fresh conversation; /sessions opens the session picker.
• Session management — /sessions opens a Gemini-style searchable session picker (create / resume / switch); the live session title shows above the composer and can be pinned with /rename.
• Streaming conversation — assistant output streams in, rendered as Markdown with lowlight (highlight.js) syntax highlighting, in a scrollable transcript with auto-follow.
• Rich tool cards — file edits as inline diffs, reads with line numbers + highlighting, terminal output, search results, and web sources, driven by the tool render-intent contract.
• Inline human collaboration — slash commands (local /new /rename /init /sessions /models /keys /help /exit plus the harness's own commands), permission prompts (y/n), and ask-user questions, all answered in a focused dialog layer.
• Input UX — / command completion and @path completion with inline ghost text (Tab to accept), plus ↑/↓ input history.
• Model switching — /models opens a picker over ctx.llm's provider/model catalog, persisted through the default-model settings.
• Provider setup — /provider opens a picker over a curated provider roster (OpenAI / Anthropic / OpenCode), then collects the API key inline (masked) and wires it end to end: the key goes to the harness credential store and the llm-pi-ai provider profile lands in the user settings document, live — no restart.
• Gemini-style theme — semantic color tokens, gradient logo + spinner, > prompt, and a centralized, documented keymap.
• Status observability — a live working line (driven by the dsh-working-activity plugin) over a segmented context bar (system / prompt / assistant / thinking / tools / free), a TPS gauge + sparkline, and per-run stats — cache hit rate, reasoning effort, and input → output tokens — on the status line.
• Git branch badge — when the working directory is a git repo, the current branch shows as a ⎇ <branch> badge on the status line (read at boot and refreshed each time a model turn completes).
• Session metrics commands — /status (model, effort, session id, cwd, tokens, context %, tps), /cost (input / output / cache read / cache write), and /tokens (input → output) report right in the transcript.
• Goals & todos — /goal and /todo open panels projecting goal/change and todo/write session events into a live goal + todo list.
• Trace timeline — /trace opens a filterable session timeline (turn / tool / reasoning / token categories), with ↑/↓ switching filters.
• Export to Markdown — /export writes the current session (user / assistant / tool sections) to a Markdown file in the current working directory (cwd).
• Agent presets — /preset opens a picker over the harness's agent-preset roster; picking one switches the agent's preset on a blank session (a session with history reports that preset switching needs an empty conversation).
• Session modes — Shift+Tab cycles Default / Plan / Full access: each mode is a named bundle of optional DSH plane switches — plan mode (dsh-plan-mode /plan), sandbox policy, and approval policy.
• Side questions — /btw <question> fires an independent llm.stream call against the current model selection, shown in a panel that never blocks or interrupts the main turn.
• Rewind — double-Esc on an empty input opens a picker of past user messages; picking one forks the conversation back to that point (a fresh agent via sessions.fork + agents.create) and pre-fills the input with that message.
• Startup tips — on an empty session, three randomized usage tips show under the logo/version — command token highlighted, description dimmed — chosen by system locale; the tips live in src/tips.txt and are editable without touching code.

Requirements

• Node ^22.19.0 or >= 24 (older 22.x lacks node:zlib.createZstdDecompress).
• pnpm >= 11 — dsh plugin add shells out to pnpm; pnpm 10.x hits ERR_PNPM_ADDING_TO_ROOT.
• DEEPSEEK_API_KEY — only required to send real model requests; boot and the UI work without it.

Install and run

# Prerequisite: the official harness CLI
npm install -g @deepseek-ai/dsh

# Install deep-flow globally (first run auto-initializes the profile)
npm install -g @jkxie/dsh-deep-flow

# Start
deep-flow

The deep-flow launcher keeps the profile in sync with the installed package:

• First run — the uninitialized profile is bootstrapped automatically via dsh plugin --profile deep-flow add @jkxie/dsh-deep-flow@<version>, then it launches.
• Version drift — if the installed profile version differs from the globally installed launcher's version, the profile is re-pinned to the launcher's version automatically, then it launches. So upgrading is just npm install -g @jkxie/dsh-deep-flow@<new version> followed by deep-flow — the profile updates itself on the next launch.
• In sync — launches directly.

Manual / advanced equivalent:

dsh plugin --profile deep-flow add @jkxie/dsh-deep-flow@latest
dsh --profile deep-flow

Install a specific version:

dsh plugin --profile deep-flow add @jkxie/dsh-deep-flow@0.2.0

Update to the latest:

dsh plugin --profile deep-flow add @jkxie/dsh-deep-flow@latest

@deepseek-ai/* packages resolve from the dsh installation's flat profile fallback (tsx paths in source launches), so they are not npm dependencies of this package — you never install them yourself.

Keymap

Surface	Keys	Action
Conversation	↑ / ↓	recall previous inputs
	← / →	move the cursor
	PgUp / PgDn / mouse wheel	scroll the transcript
	Tab	accept a / command or @path suggestion
	Shift+Tab	cycle session mode (default / plan / full access)
	Enter	send the message
	Ctrl-C	clear input → cancel the turn → quit
	/new	start a new session
	/rename	rename the current session
	/init	generate AGENTS.md by analyzing this directory
	/sessions	pick a session
	/models	pick a model
	/provider	set up a model provider (API key)
	/keys	manage API keys
	/help	list slash commands
	/status	show session info
	/cost	show token usage
	/tokens	show token details
	/goal	show the goal panel
	/todo	show the todo panel
	/export	export session to Markdown
	/trace	show session trace timeline
	Esc Esc	cancel the running turn / rewind to a past message (empty input)
	/preset	switch the agent preset
	/btw	ask a side question (non-blocking)
	/exit	quit
API keys	↑ / k · ↓ / j	move selection
	Enter	edit the selected key (masked)
	Esc	back to sessions
	q / Ctrl-C	quit
Prompts	y / n	allow / reject a permission request
	1-9	pick a question option
	c	type a custom answer
	Enter	confirm / skip a question
	Esc	dismiss (cancel the request / question)

How it works

deep-flow is a Cordis bundle (dsh.bundle.patch → cordis.patch.yml) that disables the shared module-reload hmr row and inserts the deep-flow-runner plugin. The runner injects the core services (agents, sessions, agentDefaultModel, tools, commands, userQuestions, approval), awaits loader settlement, then renders an Ink tree that:

• reads the durable session log through session/event and projects it through a Channel (src/store/channel.ts) into the immutable snapshot the React layer subscribes to via useSyncExternalStore; TPS, context-bar and token metrics derive from that session/event projection (assistant/message usage, request/header, request/context, user/message, tool/call), while live activity/status frames from dsh-working-activity feed only the working-status line,
• submits user input through agent.followup(),
• cancels in-flight turns through agent.cancel(),
• creates / resumes agents through ctx.agents.create() / ctx.agents.resume() — resume first runs src/compat/sessionLog.ts, which repairs the persisted log in place so the ephemeral activity/status frames are marked ignorable and seed validation accepts the session,
• answers the interaction seams through ctx.commands, the approval/request waterfall, and ctx.userQuestions.

Concept	Mechanism
Event stream	session/event
Prompt the agent	agent.followup()
Interrupt	agent.cancel()
Create / resume session	ctx.agents.create() / ctx.agents.resume()
Permissions / commands / Q&A	ctx.approval / ctx.commands / ctx.userQuestions
Model catalog / selection	ctx.llm / ctx.agentDefaultModel
Status observability	activity/status (dsh-working-activity) → working-status line only; TPS / context-bar metrics come from the session/event projection

The working line comes from the dsh-working-activity plugin, re-exported from src/working-activity.ts under this package's own @jkxie/dsh-deep-flow/working-activity subpath so the dsh loader always resolves it from the profile's direct dependency (pnpm's isolated layout never links transitive deps into the profile root).

Project layout

src/
  index.tsx             entry — re-exports name/inject/apply from plugin.tsx
  plugin.tsx            runner plugin boundary (services, controller, boot, render)
  app.tsx               App surface (view state, single useInput dispatcher, dialogs wiring)
  commands.ts           deep-flow slash commands + parser (/status /cost /tokens /goal /todo /export /trace, pure)
  controller.ts         Controller / HomeSession / CommandOutcome / StatusSnapshot types
  prompt.ts             prompt queue bridging boot ↔ React
  working-activity.ts   re-export of dsh-working-activity (loader-resolvable subpath)
  store/
    channel.ts          Channel — session/event → transcript lines + live metrics snapshot
    metrics.ts          context bar, TPS gauge + sparkline, token formatters (pure)
    goal-todo.ts        goal/change + todo/write event reducers (pure, replay-safe)
    rewind.ts           rewind candidates + fork-boundary computation (pure, replay-safe)
    session-modes.ts    configurable session modes (plan/sandbox/approval bundles, pure)
    trace.ts            bounded, filterable trace timeline projection (pure)
  screens/
    chat.tsx            ChatScreen — transcript + composer + status line
    status-line.tsx     status line + segmented context bar footer
  components/
    goal-panel.tsx      goal panel (/goal) — live goal from goal/change events
    todo-panel.tsx      todo panel (/todo) — whole-list todo/write snapshot
    trace-view.tsx      /trace filterable timeline view
    btw-panel.tsx       /btw side-question panel (independent llm.stream call)
    preset-picker.tsx   /preset agent-preset picker
    rewind-picker.tsx   double-Esc rewind picker (past user messages)
    session-picker.tsx  /sessions Gemini-style session picker
  hooks/
    useStore.ts         thin useSyncExternalStore wrapper
  compat/
    sessionLog.ts       pre-resume session-log repair for third-party events
  transcript-view.tsx   ToolLine / LineView
  header.tsx            gradient logo + version + startup tips (top of the transcript)
  tips.ts               parse tips.txt, pick randomized subset, locale detection (pure)
  tips.txt              bilingual startup-tip data (one cmd|desc|cmd|desc line per tip; edit freely)
  composer.tsx          bordered input box + spinner/footer
  file-completion.ts    @ path completion (pure)
  git-branch.ts         readBranch — current git branch of the cwd (pure)
  init-prompt.ts        buildInitPrompt — /init analysis prompt (pure)
  spinner.tsx           gradient color-cycling spinner
  useTerminalSize.ts    terminal size hook
  markdown.tsx          markdown-it → Ink renderer (streaming-aware)
  highlight.ts          lowlight/highlight.js syntax highlighter (→ Ink token colors)
  tool-cards.tsx        read / terminal / search / web result cards
  diff.tsx              inline file-diff view
  dialogs.tsx           approval / question / model-picker / help dialogs
  keys.tsx              API-key management view (masked editor over ctx.credentials)
  theme.ts              color theme (single dark theme, decoupled)
  keymap.ts             centralized keymap + help text
  logo.tsx              the startup ASCII art (gradient; swap this to rebrand)
cordis.patch.yml      bundle patch (disables hmr, inserts deep-flow-runner)

Development

Build (produces lib/index.js, ESM):

pnpm run build

Run locally from a deepseek-harness checkout (requires pnpm install and at least pnpm run build:lib:host):

pnpm dsh plugin --profile deep-flow add ../deep-flow
pnpm dsh --profile deep-flow

There is no test, lint, or typecheck script — pnpm run build is the main verification command, plus pnpm run verify:metrics / verify:goal-todo / verify:trace / verify:rewind / verify:session-mode for the pure logic (metrics, goal/todo reducers, trace projection, rewind candidates/boundaries, session-mode folding). Rendering is verified offline by mounting components over a fake stdin/stdout with interactive: false; interactive behavior requires a real terminal. See PLAN.md for the milestone plan (M0–M5, all complete) and the design lessons recorded along the way.

Publishing

npm version patch    # or minor / major — npm forbids re-publishing the same version
npm publish --access public --registry https://registry.npmjs.org/

prepublishOnly runs pnpm run build automatically. Use --tag beta to publish a pre-release without moving the latest tag.

License

MIT