codsh
A terminal coding agent for DeepSeek

codsh▍

/ship takes one sentence to verified code, with a built-in live task flow panorama. DeepSeek, or any compatible endpoint.

codsh-cli on npm zero-dependency launcher MIT
install
$ npm install -g @deepseek-ai/dsh codsh-cli
  # have dsh already? npm i -g codsh-cli
$ codsh
› /ship <your one-sentence idea>
/ship, end to end animated demo
┃ › /ship let long diffs open in a pager ✻ reading the repo — pager.ts, screen.ts, three call sites ? frontier: full screen, or split under the box? · recommended: full screen ┃ › full screen — q returns to the transcript │ ● Write docs/specs/pager.md │ + 6 acceptance criteria · each names its proving command ? confirm the spec — gate 1 ┃ › confirmed │ ● tickets: 3 tracer bullets → checkboxes in the spec ? approve the tickets — gate 2 ┃ › approved ⠿ baseline: proof commands run once — two red, as expected ✔ 1/3 pager opens on long output · tests green · committed ✔ 2/3 q returns to the transcript · tests green · committed ✔ 3/3 state survives a resize · tests green · committed ✔ every criterion re-run and read — all green criterion → command → what it printed ╭─────────────────────────────────────────────────────────────────────────────────╮ │ › Ask anything · / $ ! @ · ⇧Tab plan mode │ ╰─────────────────────────────────────────────────────────────────────────────────╯ todos 0/3 · ▶ pager opens on long output · Ctrl+T openstodos 1/3 · ▶ q returns to the transcripttodos 2/3 · ▶ state survives a resizetodos 3/3 · all done ✔ deepseek-chat · ~/my-project (main) · ? shortcuts

The arc loops. /ship below.

01 — /ship

One sentence to shipped.

Two approvals. Then autonomous — with a built-in live task flow panorama.

  1. Wayfinder

    Clarify the destination and resolve open decisions before grill. Larger efforts keep a resumable decision map.

  2. Grill

    Design-tree interview. Facts are inspected; each round asks the open frontier with a recommended answer.

  3. Spec — gate 1

    Synthesized automatically. You confirm. Each criterion names its proving command.

  4. Tickets — gate 2

    Tracer-bullet slices, written automatically. You approve. Baseline runs before any code.

  5. Landing

    TDD at the spec's seams. Each green ticket is a commit.

  6. Done

    Every criterion re-run and reported.

Panorama

Built-in live task flow panorama across every phase: a single-line teaser with live ticket counts (待认领 / 已认领 / 已关闭) and in-flight worktrees sits above the plan row; Ctrl+G (or clicking the teaser) opens a fullscreen two-ring ASCII overlay of the whole DAG right in your terminal; and a local loopback React Flow diagram at 127.0.0.1 visualizes decision context, recorded Q&As, and live landing progress without forcing a browser window open.

in the box
› /ship let long diffs open in a pager instead of scrolling past

Bare /ship resumes unfinished wayfinding or the spec's current phase.

01 — See it

Every terminal below is a real one.

Captured from the packed binary. Not a mockup.

A session that is its own space real capture
╭───────────────────────────────────────────────────────────────────────────────╮ │ › Ask anything · / for commands · $ for skills · ! shell · @ for files · ⇧Ta… │ ╰───────────────────────────────────────────────────────────────────────────────╯ cli-mock · ~/.cache/codsh/showcase · ? shortcuts

The alternate screen, the input box pinned to the bottom, and the status row that is always current.

The question you just asked holds the top real capture
╭───────────────────────────────────────────────────────────────────────────────╮ │ › Ask anything · / for commands · $ for skills · ! shell · @ for files · ⇧Ta… │ ╰───────────────────────────────────────────────────────────────────────────────╯ ⠋ working 0.0s · Ctrl-C to interrupt cli-mock · context 59/? · ~/.cache/codsh/showcase · ? shortcuts

A submitted prompt takes the viewport top and the reply fills the space beneath it. Read back into history and the way home is the same frame: the wheel and PgDn land on it again.

The prompt that owns what you are reading real capture
↑ │ now the input path · ● ─────────────────────────────────────────────────────────────────────────────────↓ │ • third bullet keeps the answer long │ • fourth bullet keeps the answer long │ • fifth bullet keeps the answer long │ • sixth bullet keeps the answer long │ • seventh bullet keeps the answer long │ • eighth bullet: past the fold threshold at any test width │ │ ╭────────┬───────────────────────────────────────────────────────────────────── │ ─╮ │ │ 维度 │ 内容 │ │ │ ├────────┼───────────────────────────────────────────────────────────────────── │ ─┤ │ │ 一句话 │ 一个很长的中文单元格内容,用来强制表格在任何终端宽度下都必须在单元格 │ │ │ │ │ 内部换行。一个很长的中文单元格内容,用来强制表格在任何终端宽度下都必 │ │ │ │ │ 须在单元格内部换行。一个很长的中文单元格内容,用来强制表格在任何终端 │ │ │ │ │ 宽度下都必须在单元格内部换行。 │ │ │ ├────────┼───────────────────────────────────────────────────────────────────── │ ─┤ │ │ 命令 │ codsh │ │ ↑ 12 rows above · click or PgDn returns to the latest ╭───────────────────────────────────────────────────────────────────────────────╮ │ › Ask anything · / for commands · $ for skills · ! shell · @ for files · ⇧Ta… │ ╰───────────────────────────────────────────────────────────────────────────────╯ cli-mock · context 207/? · ~/.cache/codsh/showcase · ? shortcuts

Scroll back over a turn boundary and the prompt that asked for those rows pins itself at the top; the rail on the right marks the turn you are in, and the foot of the screen says how far back you are — click it to come home. Shift+←/→ jumps between turns.

Tool calls as one-row cards real capture
│ │ create the note │ │ │ ● Write note.txt +1 -0 ✔ │ │ CODE_CLI_CALL_OK via cli-mock │ ╭───────────────────────────────────────────────────────────────────────────────╮ │ › Ask anything · / for commands · $ for skills · ! shell · @ for files · ⇧Ta… │ ╰───────────────────────────────────────────────────────────────────────────────╯ ⠋ working 0.1s · 14 tokens · Ctrl-C to interrupt cli-mock · context 23/? · ~/.cache/codsh/showcase · ? shortcuts

Every call renders through its presenter as one row — a title, +n -m, a status — under a rule down the block’s left edge; the diff itself is a click or Ctrl+O away.

Thinking, folded until you open it real capture
│ │ think it over │ │ thought for 0.0s │ CODE_CLI_ANSWER after thinking (turn 2) │ ╭───────────────────────────────────────────────────────────────────────────────╮ │ › Ask anything · / for commands · $ for skills · ! shell · @ for files · ⇧Ta… │ ╰───────────────────────────────────────────────────────────────────────────────╯ ⠋ working 0.0s · Ctrl-C to interrupt cli-mock · context 45/? · ~/.cache/codsh/showcase · ? shortcuts

A thought streams as a ticking `thinking…` head that becomes its clock, folded, with the deliberation behind a click or Ctrl+O. A click on the clock opens it, a click inside folds it, and Ctrl+O swaps every block at once.

Todos that stay in view real capture
│ │ plan the work │ │ │ ● Update todo list · 1 line ✔ │ │ todos 1/3 · 1 in progress · 1 open │ ✔ read the code │ ▶ write the fix │ ○ run the tests │ │ CODE_CLI_CALL_OK via cli-mock │ │ 0.1s · 26 tokens │ ╭───────────────────────────────────────────────────────────────────────────────╮ │ › Ask anything · / for commands · $ for skills · ! shell · @ for files · ⇧Ta… │ ╰───────────────────────────────────────────────────────────────────────────────╯ todos 1/3 · Ctrl+T closes ✔ read the code ▶ write the fix ○ run the tests cli-mock · context 23/? · ~/.cache/codsh/showcase · ? shortcuts

A pinned row holds the agent’s list over the status row instead of scrolling away with the write; Ctrl+T opens it whole.

Markdown, rendered rather than echoed real capture
│ explain it ───────────────────────────────────────────────────────────────────────────────── │ │ 维度 │ 内容 │ │ │ ├────────┼───────────────────────────────────────────────────────────────────── │ ─┤ │ │ 一句话 │ 一个很长的中文单元格内容,用来强制表格在任何终端宽度下都必须在单元格 │ │ │ │ │ 内部换行。一个很长的中文单元格内容,用来强制表格在任何终端宽度下都必 │ │ │ │ │ 须在单元格内部换行。一个很长的中文单元格内容,用来强制表格在任何终端 │ │ │ │ │ 宽度下都必须在单元格内部换行。 │ │ │ ├────────┼───────────────────────────────────────────────────────────────────── │ ─┤ │ │ 命令 │ codsh │ │ │ ╰────────┴───────────────────────────────────────────────────────────────────── │ ─╯ │ │ │ a quoted line │ │ ts │ const answer = "text" // a comment │ CODE_CLI_CALL_STREAM_DONE ╭───────────────────────────────────────────────────────────────────────────────╮ │ › Ask anything · / for commands · $ for skills · ! shell · @ for files · ⇧Ta… │ ╰───────────────────────────────────────────────────────────────────────────────╯ ⠋ working 0.0s · Ctrl-C to interrupt cli-mock · ~/.cache/codsh/showcase · ? shortcuts

Tables get real columns, code gets highlighted, and emphasis markers are consumed instead of printed.

A full-screen reader for one answer real capture
Answer 1 CODE_CLI_HEADING Prose with bold, em, inline_code, and a link (https://x.dev). An identifier like some_helper_name must survive intact. Gain: CODE_CLI_GAIN & held • screen.ts: the viewport module • second bullet • third bullet keeps the answer long • fourth bullet keeps the answer long • fifth bullet keeps the answer long • sixth bullet keeps the answer long • seventh bullet keeps the answer long • eighth bullet: past the fold threshold at any test width ╭────────┬──────────────────────────────────────────────────────────────────────╮ │ 维度 │ 内容 │ ├────────┼──────────────────────────────────────────────────────────────────────┤ │ 一句话 │ 一个很长的中文单元格内容,用来强制表格在任何终端宽度下都必须在单元格 │ │ │ 内部换行。一个很长的中文单元格内容,用来强制表格在任何终端宽度下都必 │ │ │ 须在单元格内部换行。一个很长的中文单元格内容,用来强制表格在任何终端 │ │ │ 宽度下都必须在单元格内部换行。 │ ├────────┼──────────────────────────────────────────────────────────────────────┤ │ 命令 │ codsh │ ╰────────┴──────────────────────────────────────────────────────────────────────╯ │ a quoted line ts const answer = "text" // a comment Esc closes · c copies · ↑↓/wheel · PgUp/PgDn · Home/End · 1-32/33

/view 1 opens an answer, /view 1:1 its first code block, in a reader that survives a resize. Esc puts the conversation back exactly as it was; /copy addresses the same targets.

Ctrl+G

Toggle the TTY two-ring task flow panorama overlay. A live teaser sits above the plan row with real-time ticket counts and the local Web flowchart URL.

Shift+←/→

Jump between real turns; /jump previews one and Esc puts the frame back.

/copy

/copy N takes an answer's raw Markdown, /copy N:C its code without the fence.

Ctrl+V

Pastes an image, and a card centered over the transcript previews it — the picture itself wherever the terminal paints one, a colour mosaic elsewhere, Ctrl+O for the original. Native vision, or a DeepSeek text model borrowing Vision Exp for one description.

/ $ ! @

Commands, skills, shell, files — the menu opens above the box. ⇧Tab is plan mode.

drag

Select to copy, over OSC 52 or the platform clipboard.

a pipe

Off a TTY it degrades rather than breaks: a line reader, no widgets, no drawing.

02 — Install & run

One command.

npm i -g @deepseek-ai/dsh codsh-cli then codsh. The launcher is dsh --profile code.

codsh --resume <id>

Reopen a recorded session, replaying its history as the same folds.

codsh --continue

Pick up the most recent session in this workspace.

codsh -p "task"

One-shot print mode, for scripts and pipes.

codsh --version

The launcher, the runtime registered in the profile, and the dsh it found.

codsh update

Moves the pair from the shell. /update does it from inside a session; a session says so on its own when one is out. A leftover profile node_modules from another pnpm store is dropped and the registration retried.

DEEPSEEK_API_KEY

The model key, read from the environment or a .env file.

DSH_HOME

Where profiles live; ~/.dsh by default. DSH_BIN picks the dsh to launch.

CODSH_CLIPBOARD

osc52, system, or off — narrows how a selection reaches your clipboard.

CODSH_UPDATE_CHECK

off silences the automatic check — /update still asks. CODSH_UPDATE_REGISTRY points both at another registry.

CODSH_VISION_*

_BASE_URL, _MODEL, _API_KEY: an OpenAI-compatible sidecar for text-only models. Without one, DeepSeek text routes borrow deepseek-v4-flash-vision-exp by themselves.

Prefer no launcher at all? The two lines it wraps work directly, with any profile name:

without the launcher
$ dsh plugin --profile code add codsh-bundle
$ dsh --profile code
Working on it? pnpm install && pnpm run dev keeps a repo-local dsh home in .dev-home, so edits reach the running surface in seconds; MOCK=markdown pnpm run dev needs no key. pnpm run test:e2e packs the tree into a real profile and drives the published binary — the same harness that captured every screen above. codsh never forks the harness: upstream work goes to deepseek-harness, and pnpm run sync:dsh tracks its releases. Details in the README.