deepseek-cli-mode 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek Harness CLI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,258 @@
-# Temporary Holding Version
+# deepseek-cli-mode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Terminal (CLI) mode for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)** — an interactive,
+Claude Code-style coding agent that lives in your shell instead of a browser or an Electron window.
+
+> **Community project.** This is an independent, unofficial project. It is **not** affiliated with, endorsed by, or
+> sponsored by DeepSeek. "DeepSeek" and "DeepSeek Harness" are used only to describe what this tool connects to.
+> Use it at your own risk and review the code before running it against your own API keys.
+
+DeepSeek Harness ships two surfaces: the **Web** app and the **Desktop** app. This package adds the third one — a real
+interactive **CLI** that boots the *same* Harness runtime (`dsh-base` + `dsh-headless`: agent loop, tools, sandbox,
+session persistence, approvals) and keeps **one live Agent for the whole session**, so multi-turn context, tool state,
+and the model's request prefix stay warm between messages.
+
+```
+❯ explain what changed in this repo and run the tests
+
+  ⌕ grep diff --stat
+  $ pwsh npm test
+  ◇ read package.json
+The working tree has three modified files …
+```
+
+---
+
+## Requirements
+
+| | |
+|---|---|
+| Node.js | 20 or newer |
+| DeepSeek Harness runtime | `@deepseek-ai/dsh` **0.2.1** or newer, installed locally |
+| Credentials | an API key saved by the Desktop/Web app, or `DEEPSEEK_API_KEY` in the environment |
+
+The CLI is a front-end for the Harness runtime; it does not bundle the runtime itself. Install both:
+
+```powershell
+npm install -g @deepseek-ai/dsh
+npm install -g deepseek-cli-mode
+```
+
+The CLI reuses the key already stored in `$DSH_HOME/.credentials.yaml` by the GUI, so in most setups there is nothing
+extra to configure.
+
+---
+
+## Installation
+
+### Global install (recommended)
+
+```powershell
+npm install -g deepseek-cli-mode
+deepseek --version
+```
+
+This installs three equivalent command names: **`deepseek`** (primary), `deepseek-cli-mode`, and `dsh-cli`.
+
+### Run without installing
+
+```powershell
+npx --yes deepseek-cli-mode
+```
+
+### From a local checkout
+
+```powershell
+cd deepseek-cli-mode      # the folder containing package.json
+npm install
+npm link                  # optional: exposes the `deepseek` command
+```
+
+---
+
+## Usage
+
+```
+deepseek                        start an interactive session
+deepseek "task text..."         answer one task and exit (scriptable)
+deepseek -r, --resume [id]      resume a session (newest in this directory by default)
+deepseek -c, --continue         continue the newest session without prompting
+deepseek --list                 list recent sessions in this directory
+deepseek -y, --yes              auto-approve tool actions that would ask
+deepseek --model <id>           override the model for this run
+deepseek --reasoning <effort>   override the reasoning effort (off|high|max)
+deepseek --help                 show help
+deepseek --version              show the version
+```
+
+### Examples
+
+```powershell
+# interactive — the normal way to work
+deepseek
+
+# scriptable one-shot; stdout carries only the final answer
+deepseek "summarize the uncommitted changes" > summary.md
+
+# continue the previous conversation in this folder
+deepseek -c
+
+# let it edit files and run commands unattended (approvals auto-accepted)
+deepseek -y "fix the failing test in tests/auth.spec.ts"
+
+# pipe a task in
+Get-Content .\error.log | Select-Object -First 50 | deepseek "what causes this error?"
+
+# attach a file or an image to the next message
+deepseek "review @src/app.ts and tell me what is risky"
+```
+
+### Inside a session
+
+| Command | What it does |
+|---|---|
+| `/help` | command list, including the live Harness command registry |
+| `/new` | start a fresh session (new id, keeps the process warm) |
+| `/sessions` | recent sessions in this directory (with a ▶ running marker) |
+| `/resume <id>` | switch to another session |
+| `/model [id]` | show or switch the model for the next message |
+| `/reasoning [off\|high\|max]` | show or set the reasoning effort |
+| `/permission [preset]` | switch the sandbox + approval preset |
+| `/skills` | list the skills discovered in this workspace |
+| `/jobs` | list this session's background jobs |
+| `/todos` | show the current todo list |
+| `/image <path>` | attach an image to the next message (or mention `@photo.png`) |
+| `/export [file]` | write this run's transcript as markdown |
+| `/thinking` | print the last turn's reasoning (collapsed by default) |
+| `/session` | print the current session id (for `--resume`) |
+| `/clear` | clear the screen |
+| `/quit`, `/exit` | leave (Ctrl+C at an empty prompt also exits) |
+
+Harness commands are shared with the Web and Desktop apps and run through the same registry:
+
+| Command | What it does |
+|---|---|
+| `/compact` | compact older conversation history |
+| `/goal [objective\|clear\|edit\|pause\|resume]` | long-running goal mode |
+| `/plan [off]` | plan mode (design first, approve, then execute) |
+| `/feedback` | record feedback about the session |
+
+Mention a file with `@path` to attach its text (up to 200 KB); mention an image (`@shot.png`) or use `/image` to attach
+it durably through the same attachment store the GUI uses.
+
+Ctrl+C **during a turn** cancels the turn; Ctrl+C **again** force-quits. Approval prompts (`Allow write …? [y/N]`) appear
+when a tool wants to leave the workspace or act outside the sandbox policy.
+
+---
+
+## Configuration
+
+| Environment variable | Default | Meaning |
+|---|---|---|
+| `DSH_HOME` | `~/.dsh` | Harness home (profiles, sessions, credentials) |
+| `DEEPSEEK_API_KEY` | stored key | API key override |
+| `DSH_CLI_DSH_BIN` | auto-detected | explicit path to `@deepseek-ai/dsh/lib/bin.js` |
+| `DSH_PERMISSION_MODE` | `workspace-write` | `read-only` \| `workspace-write` \| `danger-full-access` |
+| `DSH_CLI_REASONING` | unset | `1` streams reasoning text instead of collapsing it |
+| `DSH_CLI_YES` | unset | `1` auto-approves tool actions (same as `--yes`) |
+| `NO_COLOR` | unset | disable ANSI styling |
+
+Model and reasoning effort come from the Harness settings (the same selection the Desktop app shows). `--model`,
+`--reasoning`, `/model`, and `/reasoning` override them for the session.
+
+---
+
+## How it works
+
+```
+deepseek (bin/deepseek.js)
+  ├─ finds the local @deepseek-ai/dsh installation
+  ├─ self-heals $DSH_HOME/profiles/dsh-cli  (manifest + patch + runner.js)
+  └─ spawns:  dsh --profile dsh-cli <your arguments>
+                └─ profile bundles: @deepseek-ai/dsh-base + @deepseek-ai/dsh-headless
+                     └─ runner/runner.js  (Cordis plugin, this package)
+                          ├─ agents.create() / agents.resume()
+                          ├─ agent/assistant-stream  → token-level streaming
+                          ├─ session/event           → tool calls, todos, usage
+                          ├─ user-questions/request  → plan review, ask_user_question
+                          └─ approval/request        → y/N prompts
+```
+
+Why a profile instead of a standalone program? The Harness is a Cordis plugin tree; running the CLI as a profile means
+it gets the identical system prompt, tools, sandbox, permission policy, session store, and compaction behavior as the
+GUI. This package only adds the terminal front-end.
+
+Files this package writes (once, under `$DSH_HOME/profiles/dsh-cli/`):
+
+```
+package.json         profile manifest (bundles)
+cordis.yml           empty root
+cordis.patch.yml     disables the one-shot headless driver, re-enables the
+                     credential store, mounts ./runner.js
+pnpm-workspace.yaml
+runner.js            copy of runner/runner.js (kept in sync)
+.cli-version         version stamp for the files above
+```
+
+Your Web/Desktop profiles are untouched.
+
+### Feature parity with the Web/Desktop apps
+
+Roughly four fifths of the agent-facing product is shared by construction (tools, policies, sessions, plans, goals,
+compaction, skills, subagents, workflows). A feature-by-feature comparison — including what stays GUI-only — is in
+[docs/PARITY.md](docs/PARITY.md).
+
+---
+
+## Troubleshooting
+
+**`deepseek: cannot find @deepseek-ai/dsh`** — install the runtime once: `npm i -g @deepseek-ai/dsh`, or set
+`DSH_CLI_DSH_BIN` to the `lib/bin.js` path.
+
+**`@deepseek-ai/dsh 0.1.x is too old for this CLI`** — upgrade with `npm i -g @deepseek-ai/dsh@latest`. This CLI needs
+the `agent/assistant-stream` and `agentDefaultModel.saveSelection` APIs introduced in 0.2.1.
+
+**`MISSING_CREDENTIAL` / no API key** — save a key in the Desktop/Web app (Models page), or
+`$env:DEEPSEEK_API_KEY = "sk-…"` before starting `deepseek`.
+
+**Approvals keep rejecting actions** — the default policy is `workspace-write`, so writes outside the working directory
+ask first. Use `-y` for unattended runs, or start with `$env:DSH_PERMISSION_MODE = "danger-full-access"`.
+
+**Command not found after `npm i -g`** — the npm global prefix may not be on `PATH`. Check `npm prefix -g` and add its
+`bin` folder, or run through `npx deepseek-cli-mode`.
+
+**`npx` with an absolute Windows tarball path does nothing** — pass a relative path or a `file:` spec:
+`npx --yes .\deepseek-cli-mode-1.0.0.tgz`.
+
+**Input looks garbled in Git Bash / MSYS** — use Windows Terminal, PowerShell 7, or `cmd.exe`; the runner uses Node's
+readline and expects a normal Windows console.
+
+**Startup shows `[llm-deepseek-api-key] model listing …`** — the adapter is discovering models; it is written to stderr,
+so piped stdout stays clean.
+
+---
+
+## Development
+
+```powershell
+npm install
+npm test                       # reports the CLI version
+npm start                      # same as `deepseek`
+node bin/deepseek.js --list    # boot the profile without a model call
+npm run pack:check             # inspect the publish archive
+```
+
+The runner is plain ESM with no build step. It is copied to the profile on every launch when its content changed, so
+editing `runner/runner.js` and re-running `deepseek` picks the change up.
+
+Compatibility note: the runner targets the 0.2.1 `@deepseek-ai/dsh` API surface (Cordis plugin entry, `agents.create`,
+`agent/assistant-stream`, `session/event`, `user-questions/request`, `approval/request`,
+`agentDefaultModel.saveSelection`). A future dsh release that changes those internals needs a matching runner update.
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 DeepSeek Harness CLI contributors.
+
+This project is independent and community-maintained; see the disclaimer at the top.

package/bin/deepseek.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// deepseek — the DeepSeek Harness terminal CLI launcher.
+//
+// DeepSeek Harness (dsh) ships Web and Desktop surfaces. This launcher adds the
+// missing third surface: a Claude-Code-style terminal session. It resolves the
+// locally installed `@deepseek-ai/dsh`, self-heals a dedicated `dsh-cli` profile
+// under $DSH_HOME/profiles, and boots that profile with this package's runner.
+//
+// The profile keeps ONE live Agent for the whole session, so tools, approvals,
+// session persistence, and the model's request prefix stay warm between turns.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+const requireFromHere = createRequire(import.meta.url);
+
+const PROFILE = "dsh-cli";
+const VERSION = readVersion(join(root, "package.json"));
+const DSH_MIN = "0.2.1";
+
+function readVersion(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+const args = process.argv.slice(2);
+
+// Help/version are answered here so they never pay for a profile boot.
+if (args.includes("--version") || args.includes("-v")) {
+  console.log(VERSION);
+  process.exit(0);
+}
+if (args.length === 0 ? false : args[0] === "--help" || args[0] === "-h") {
+  printHelp();
+  process.exit(0);
+}
+
+function printHelp() {
+  console.log(`deepseek ${VERSION} — DeepSeek Harness in your terminal.
+
+Usage:
+  deepseek                       start an interactive session
+  deepseek "task text..."        answer one task and exit (scriptable)
+  deepseek -r, --resume          resume the newest session in this directory
+  deepseek -r <id>               resume a specific session
+  deepseek -c, --continue        continue the newest session without prompting
+  deepseek --list                list recent sessions in this directory
+  deepseek -y, --yes             auto-approve tool actions that ask
+  deepseek --model <id>          override the model for this run
+  deepseek --reasoning <effort>  override the reasoning effort (off|high|max)
+  deepseek --help                this help
+  deepseek --version             print the version
+
+Inside a session:
+  /help            commands            /new             fresh session
+  /sessions        recent sessions     /resume <id>     switch session
+  /model [id]      show/switch model   /reasoning [e]   show/set effort
+  /thinking        last reasoning      /session         current session id
+  /clear           clear the screen     /quit, /exit     leave
+
+Environment:
+  DSH_HOME           Harness home (default: ~/.dsh)
+  DSH_CLI_DSH_BIN    explicit path to @deepseek-ai/dsh/lib/bin.js
+  DSH_PERMISSION_MODE  workspace-write (default) | read-only | danger-full-access
+  DEEPSEEK_API_KEY   API key; otherwise the key saved by the Desktop/Web app is used
+
+Requires a local install of @deepseek-ai/dsh (npm i -g @deepseek-ai/dsh).`);
+}
+
+// ---------------------------------------------------------------------------
+// 1. Locate the dsh installation.
+// ---------------------------------------------------------------------------
+function resolveDshBin() {
+  const candidates = [
+    process.env.DSH_CLI_DSH_BIN,
+    // Same global prefix as this node binary (npm default layout).
+    join(dirname(process.execPath), "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js"),
+    // Common global prefixes.
+    process.env.APPDATA ? join(process.env.APPDATA, "npm", "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js") : undefined,
+    process.env.NPM_CONFIG_PREFIX ? join(process.env.NPM_CONFIG_PREFIX, "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js") : undefined,
+    process.env.npm_config_prefix ? join(process.env.npm_config_prefix, "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js") : undefined,
+    join(homedir(), "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js"),
+    join(homedir(), ".npm-global", "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js"),
+    join(process.cwd(), "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js"),
+  ].filter(Boolean);
+  for (const candidate of candidates) if (existsSync(candidate)) return candidate;
+  // Resolve like a normal import from this package, then from the cwd.
+  for (const req of [requireFromHere, createRequire(join(process.cwd(), "resolve-dsh.js"))]) {
+    try {
+      return req.resolve("@deepseek-ai/dsh/lib/bin.js");
+    } catch {}
+  }
+  // Last resort: ask npm where its global root is (covers custom prefixes).
+  try {
+    const npmCli = join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+    if (existsSync(npmCli)) {
+      const result = spawnSync(process.execPath, [npmCli, "root", "-g"], { encoding: "utf8", timeout: 20000 });
+      const dir = result.stdout?.trim();
+      if (dir) {
+        const candidate = join(dir, "@deepseek-ai", "dsh", "lib", "bin.js");
+        if (existsSync(candidate)) return candidate;
+      }
+    }
+  } catch {}
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Self-heal the dedicated profile.
+// ---------------------------------------------------------------------------
+const PROFILE_MANIFEST = JSON.stringify(
+  {
+    name: "dsh-profile-dsh-cli",
+    private: true,
+    type: "module",
+    dependencies: {},
+    dsh: { profile: { bundles: ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless"] } },
+  },
+  null,
+  2
+) + "\n";
+
+const PROFILE_ROOT =
+  "# dsh profile root — an empty entry list. The tree is composed as patches:\n" +
+  "# each bundle in package.json's dsh.profile.bundles, then cordis.patch.yml.\n[]\n";
+
+const PROFILE_PATCH = `# dsh-cli — interactive terminal profile for the DeepSeek Harness.
+# Bundles: dsh-base (core machinery) + dsh-headless (coding persona, tools,
+# sandbox policy). This layer disables the one-shot headless driver, restores
+# the managed credential store the headless bundle disables, and mounts the
+# interactive runner from ./runner.js.
+- id: headless-startup
+  disabled: true
+
+- id: headless-runner
+  disabled: true
+
+# The CLI is interactive: use the API key saved by the Desktop/Web app.
+- id: credentials
+  disabled: false
+- id: authorization
+  disabled: false
+- id: deepseek-account
+  disabled: false
+
+- insert:
+    - id: cli-runner
+      name: './runner.js'
+    - id: tool-ask-user
+      name: '@deepseek-ai/dsh-tool-ask-user'
+`;
+
+const PNPM_WORKSPACE = "packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\n";
+
+function ensureProfile() {
+  const dshHome =
+    process.env.DSH_HOME && process.env.DSH_HOME.trim() !== ""
+      ? process.env.DSH_HOME
+      : join(homedir(), ".dsh");
+  const profileDir = join(dshHome, "profiles", PROFILE);
+  mkdirSync(profileDir, { recursive: true });
+
+  const stamp = join(profileDir, ".cli-version");
+  let stampVersion = "";
+  try {
+    stampVersion = readFileSync(stamp, "utf8").trim();
+  } catch {}
+
+  const staticFiles = {
+    "package.json": PROFILE_MANIFEST,
+    "cordis.yml": PROFILE_ROOT,
+    "cordis.patch.yml": PROFILE_PATCH,
+    "pnpm-workspace.yaml": PNPM_WORKSPACE,
+  };
+  for (const [name, content] of Object.entries(staticFiles)) {
+    const target = join(profileDir, name);
+    if (!existsSync(target) || stampVersion !== VERSION) writeFileSync(target, content);
+  }
+
+  // Keep the runner exactly in sync with this package.
+  const runnerSrc = join(root, "runner", "runner.js");
+  const runnerDst = join(profileDir, "runner.js");
+  const src = readFileSync(runnerSrc, "utf8");
+  if (!existsSync(runnerDst) || readFileSync(runnerDst, "utf8") !== src) writeFileSync(runnerDst, src);
+
+  writeFileSync(stamp, VERSION + "\n");
+  return profileDir;
+}
+
+// ---------------------------------------------------------------------------
+// 3. Boot.
+// ---------------------------------------------------------------------------
+const dshBin = resolveDshBin();
+if (dshBin === undefined) {
+  console.error(
+    "deepseek: cannot find @deepseek-ai/dsh.\n" +
+      "  Install it once:  npm i -g @deepseek-ai/dsh\n" +
+      "  Or point DSH_CLI_DSH_BIN at .../@deepseek-ai/dsh/lib/bin.js"
+  );
+  process.exit(1);
+}
+
+const dshVersion = readVersion(join(dshBin, "..", "..", "package.json"));
+if (compareVersions(dshVersion, DSH_MIN) < 0) {
+  console.error(
+    `deepseek: @deepseek-ai/dsh ${dshVersion} is too old for this CLI (needs >= ${DSH_MIN}).\n` +
+      "  Upgrade with:  npm i -g @deepseek-ai/dsh@latest"
+  );
+  process.exit(1);
+}
+
+function compareVersions(a, b) {
+  const parse = (v) => String(v).split(/[.+-]/).slice(0, 3).map((n) => Number.parseInt(n, 10) || 0);
+  const [x, y, z] = parse(a);
+  const [p, q, r] = parse(b);
+  if (x !== p) return x < p ? -1 : 1;
+  if (y !== q) return y < q ? -1 : 1;
+  if (z !== r) return z < r ? -1 : 1;
+  return 0;
+}
+
+ensureProfile();
+
+const child = spawn(process.execPath, [dshBin, "--profile", PROFILE, ...args], {
+  stdio: "inherit",
+  env: { ...process.env, DSH_CLI_VERSION: VERSION },
+  windowsHide: false,
+});
+
+// The child shares this console, so it receives the user's Ctrl+C directly and
+// tears down gracefully (flush + dispose + exit). This process must not die
+// first, or the child's session flush is lost: only hard-kill on a second
+// Ctrl+C or after a grace period.
+let sigints = 0;
+process.on("SIGINT", () => {
+  sigints += 1;
+  if (sigints >= 2) {
+    if (child.exitCode === null && !child.killed) child.kill();
+    return;
+  }
+  setTimeout(() => {
+    if (child.exitCode === null && !child.killed) child.kill();
+  }, 15000).unref();
+});
+process.on("SIGTERM", () => {
+  if (child.exitCode === null && !child.killed) child.kill();
+});
+
+child.on("error", (error) => {
+  console.error(`deepseek: failed to start dsh: ${error.message}`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  process.exit(code ?? (signal ? 1 : 0));
+});

package/docs/PARITY.md

@@ -0,0 +1,108 @@
+# Feature parity: Web/Desktop vs. the CLI
+
+This page is the honest audit of how much of the DeepSeek Harness Web/Desktop product the terminal CLI reproduces.
+Two facts drive it:
+
+1. The CLI is **not a re-implementation**. It boots the same `dsh-base` + `dsh-headless` bundles the GUI runs, so the
+   agent loop, tools, sandbox, approvals, session store, compaction, goals, plans, skills, subagents, workflows and
+   MCP resource plumbing are literally the same code.
+2. The **surface** differs. A terminal has no sidebar, no drag-and-drop, no browser panel, and no pixel cards. Some
+   GUI features map to a command; some are meaningless; a few are genuinely missing.
+
+Legend: ✅ works · 🟡 terminal adaptation · ❌ not available in the CLI
+
+## Chat and conversation
+
+| Web / Desktop | CLI | Notes |
+|---|---|---|
+| ✅ Streaming assistant text | ✅ | Token-level via `agent/assistant-stream` |
+| ✅ Markdown rendering | 🟡 | Headings, bold, inline code, fenced code; no tables/images layout |
+| ✅ Stop a running turn | ✅ | Ctrl+C → `agent.cancel()` |
+| ✅ Multi-turn context | ✅ | One live Agent per process; `/new` starts a fresh session |
+| ✅ Resume a conversation | ✅ | `deepseek -r [id]`, `-c`, `/resume <id>`, `/sessions` |
+| ✅ Session titles/list | 🟡 | `/sessions` lists ids + age; titles are generated in the log but not shown |
+| ✅ Rename / delete / pin sessions | ❌ | Not exposed by any CLI surface |
+| ✅ Message edit & retry | ❌ | No rewind/retry command |
+| ✅ Message feedback | 🟡 | `/feedback` (native Harness command) writes the record |
+| ✅ Attach images (paste/drag) | 🟡 | `/image <path>` or `@photo.png`; stored durably, model sees them |
+| ✅ Attach files | 🟡 | `@path` inlines text up to 200 KB; no binary upload |
+| ✅ @-file references | ✅ | `@path` resolves against the working directory |
+| ✅ Token usage meter | ✅ | Per-turn `· 12.3k in / 456 out` line |
+
+## Tools and agent control
+
+| Web / Desktop | CLI | Notes |
+|---|---|---|
+| ✅ Tool cards (read/write/edit/grep/glob/pwsh/web/…) | 🟡 | One-line icons + path preview; results summarized |
+| ✅ File diffs in cards | ❌ | No diff renderer (use `/diff`-style tooling or git in another shell) |
+| ✅ Approval prompts | ✅ | `Allow write …? [y/N]`; `-y/--yes` auto-approves |
+| ✅ Permission presets | ✅ | Native `/permission`, plus `/permissions` alias |
+| ✅ Todo checklist | ✅ | Live `☑ 2/3` checklist with incremental updates |
+| ✅ Subagent cards | 🟡 | `↳ subagent … started/finished` progress lines |
+| ✅ Jobs panel | ✅ | `/jobs` lists id, status, label, progress |
+| ✅ Workflow run view | 🟡 | Tool calls stream; no dedicated tree view |
+| ✅ Deliverables / present cards | ❌ | No card surface in a terminal |
+| ✅ Plan mode | ✅ | Native `/plan`, `/plan off`; plan review uses the terminal question provider |
+| ✅ Goal mode | ✅ | Native `/goal set/view/pause/resume` + goal tools |
+| ✅ Compaction | ✅ | Automatic, plus native `/compact` |
+| ✅ Ask-user questions | ✅ | Rendered with numbered options in the terminal |
+| ✅ Scheduled reminders | ❌ | Needs the Host Web session controller; not mountable in a CLI-only profile |
+| ✅ Skills | 🟡 | `/skills` lists them; the model invokes them through the skill tool |
+
+## Models, auth, settings
+
+| Web / Desktop | CLI | Notes |
+|---|---|---|
+| ✅ Pick model / reasoning effort | ✅ | `/model`, `/reasoning`, `--model`, `--reasoning` |
+| ✅ API key management UI | 🟡 | Reuses the key saved by the GUI; `DEEPSEEK_API_KEY` override |
+| ✅ Account / balance panel | ❌ | No account surface |
+| ✅ Provider list / model discovery | 🟡 | Adapter discovery runs on boot; no picker UI |
+| ✅ Permission, theme, font, language settings | 🟡 | Permission via `/permission`; the rest via env vars/`$DSH_HOME` config |
+| ✅ Plugin manager / marketplace | ❌ | Use `dsh plugin --profile dsh-cli add <pkg>` from a shell |
+| ✅ MCP server management | ❌ | The CLI profile does not mount `mcp-client` |
+
+## Workspace and host surface
+
+| Web / Desktop | CLI | Notes |
+|---|---|---|
+| ✅ File tree / file preview | ❌ | The terminal is the workspace |
+| ✅ Git changes panel | ❌ | Use git in the shell (tools can run it) |
+| ✅ Integrated terminal panel | ❌ | The CLI *is* a terminal |
+| ✅ Browser panel | ❌ | Desktop-only |
+| ✅ Document preview / Office conversion | ❌ | Office skills still work through tools |
+| ✅ Voice input | ❌ | Desktop/Web only |
+| ✅ Session trajectory / outline / stats / log download | 🟡 | `/export` writes the current run as markdown; no trajectory viewer |
+| ✅ Multiple tabs / concurrent sessions | 🟡 | Run several `deepseek` processes (each owns one session) |
+| ✅ Notifications, tray, auto-update | ❌ | Desktop shell features |
+
+## Commands and workflows that are identical
+
+Because the CLI executes the shared `ctx.commands` registry, these behave exactly like the GUI:
+
+- `/compact` — compact older history
+- `/goal …` — set/view/pause/resume a long-running goal
+- `/plan …` — enter/leave plan mode
+- `/permission …` — switch the sandbox + approval preset
+- `/feedback` — record session feedback
+- Any command added by a third-party plugin in the profile
+
+Run `/help` inside a session to see the live list.
+
+## What is deliberately different
+
+- **No GUI chrome.** No sidebar, cards, drag-and-drop, browser, or settings screens.
+- **One session per process.** The Web app multiplexes many sessions in one host; the CLI keeps one live Agent (spawn
+  another terminal for another conversation).
+- **stdout is scriptable.** One-shot mode prints only the final answer on stdout, all progress on stderr.
+- **Local paths only.** Attachments come from the filesystem (`@path`, `/image`), never from a browser upload.
+
+## Bottom line
+
+Roughly **four fifths of the agent-facing product is shared by construction** (tools, policies, sessions, plans, goals,
+compaction, skills, subagents, workflows). The CLI adds terminal equivalents for most user-facing controls
+(`/plan`, `/goal`, `/permission`, `/compact`, `/jobs`, `/todos`, `/skills`, `/image`, `/export`). What remains
+Web/Desktop-only is the **visual host**: sidebar and cards, file/browser/terminal panels, diff viewer, drag-and-drop,
+voice, account and plugin-management screens, and scheduled reminders (which require the Host session controller).
+
+If you need one of those in the terminal, the practical path is a thin client over the same Host API rather than a
+second implementation — that would be a separate project.

package/index.js

@@ -0,0 +1,13 @@
+// Programmatic entry point. This package is a CLI, so importing it never starts
+// a session — it only exposes the package metadata and the executable path for
+// tooling that discovers CLIs programmatically.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const manifest = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+
+export const name = manifest.name;
+export const version = manifest.version;
+/** Absolute path to the executable that `bin` maps to. */
+export const binPath = fileURLToPath(new URL("./bin/deepseek.js", import.meta.url));
+export default manifest;