**[English](README.md)** · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md) · [한국어](README.ko-KR.md) DeepSeek logo

DeepSeek Build

DeepSeek-native coding. Grok-class execution.

A full-screen terminal coding agent with safe edits, cache-aware sessions, and parallel execution built around DeepSeek models.

GitHub release npm version Apache 2.0 license

Quick start · Why DeepSeek Build · How it works · DeepSeek Harness · Benchmarks · Documentation · Contributing

DeepSeek Build welcome screen — the full-screen DeepSeek agent TUI opened by dsb

## Quick start Install from npm, add your DeepSeek API key, and open the TUI. npm 12.0.0 and newer block dependency install scripts unless you opt in. Without the flag below, npm reports success and does not install the agent. npm 11 and older install with or without the flag. ```bash npm install -g --allow-scripts=@innocarpe/deepseek-build @innocarpe/deepseek-build deepseek-build setup deepseek-build ``` Allow the package once for later global installs, then the plain command works: ```bash npm config set allow-scripts=@innocarpe/deepseek-build --location=user npm install -g @innocarpe/deepseek-build ``` The registry install requires Node.js 18 or newer and uses a prebuilt binary when a matching release asset is available. It does not require Rust on that path; see the [npm installation guide](docs/user-guide/05-npm.md) for platform and source-fallback details. `deepseek-build` is the primary command. `dsb` is the fully supported short alias with the same behavior and full Semantic Version: ```bash deepseek-build --version dsb --version ``` Keep the install current with the same command on either name: ```bash deepseek-build update ``` It asks the published feeds for the latest version and replaces an npm-global install in place. When the install is already current it says so and changes nothing, and it never replaces an install with an older published version. If the installer reports that the product bin directory is not on `PATH`, add it before launching: ```bash export PATH="$HOME/.deepseek-build/bin:$PATH" ``` ## Why DeepSeek Build | Capability | What it means | | --- | --- | | **DeepSeek-native** | DeepSeek API defaults, Flash/Pro routing, reasoning effort, and a DeepSeek-branded TUI. | | **Safe edits** | Version-bound snippet editing and fail-closed workspace permissions instead of silent whole-file replacement. | | **Long-session economics** | Session changes append after the cached history instead of rewriting it. A cache miss names the assembled document that moved, the session logs its cumulative cache total, and a request that diverges from the session log fails the turn. | | **Wall-clock throughput** | Parallel tools, background shell jobs, subagents, and opt-in worktrees run beneath the safety and cache layers. | | **Durable sessions** | Resume the most recent full-screen session or address a saved session directly. | The result is a coding agent that keeps the speed of a Grok-derived execution engine while making DeepSeek-specific cost, edit, and permission rules part of the product path. ## Everyday use ```bash # Open the full-screen TUI deepseek-build # Resume the most recent TUI session deepseek-build --resume # Continue the most recent TUI session (Claude Code-style -c) deepseek-build -c # Run one non-interactive turn deepseek-build run "Explain the architecture of this repository." # Use the trusted local coding profile deepseek-build --dogfood ``` `--dogfood` allows writes inside the current workspace and enables shell execution under policy. Writes and deletes outside the workspace remain denied. For the short command, replace `deepseek-build` with `dsb` in any example. At or below 60 columns, a submitted prompt folds to at most two rows and drops the decorative `❯` and blank pad rows; wider windows keep the three-line budget. On that phone-width pane the balance, cache hit, model and permission share one row under the input box — cost and cache on the left, model and permission on the right. Wider panes keep the model on the box border and the balance on its own row. The full-screen view has a configurable status line at the bottom. On the official DeepSeek API, DeepSeek V4.1 Flash (`deepseek-flash`) accepts attached images directly, and text-only models keep images off the wire with the on-disk fallback. The default Flash wire ID is `deepseek-flash`, which DeepSeek currently serves as **DeepSeek V4.1 Flash 1017**. OpenRouter setup uses `deepseek/deepseek-v4.1-flash-1017`. Existing product homes retain their local `[model.deepseek-v4-flash]` slot; DSB updates its old wire ID on launch while preserving custom model choices ([ADR 0015](docs/adr/0015-deepseek-v41-flash-1017.md)). ## Authentication and configuration Interactive setup asks how to reach the DeepSeek models — the DeepSeek API or OpenRouter — then stores that provider's API key in `~/.deepseek-build/credentials.json` with mode `0600`: ```bash deepseek-build setup deepseek-build setup --provider openrouter --api-key "$KEY" # non-interactive deepseek-build auth status deepseek-build auth logout ``` OpenRouter keeps prompt caches separate for each upstream provider. DSB sends `{"order":["relace","deepinfra"],"allow_fallbacks":false}` by default, which tries Relace first and limits routing to those two providers. Override it per model with OpenRouter's `provider` object; a configured object replaces the default entirely. Set it to `false` to disable routing: ```toml [model.deepseek-v4-flash] openrouter_provider = { order = ["relace", "deepinfra"], allow_fallbacks = false } # openrouter_provider = { only = ["deepinfra/fp8"] } # openrouter_provider = false ``` For CI or another non-interactive environment, set `DEEPSEEK_API_KEY`; the environment variable takes precedence over a DeepSeek credentials file. Line mode (`run` / `chat`) uses the DeepSeek API only. Product configuration, credentials, sessions, and user skills live under `~/.deepseek-build/` by default. ## Build from source Source installation is intended for contributors and unsupported release platforms. It requires Rust 1.94 or newer plus `protoc` or DotSlash; the first agent build can take several minutes. ```bash git clone https://github.com/innocarpe/deepseek-build.git cd deepseek-build ./scripts/install.sh deepseek-build --version dsb --version ``` `npm install` in this checkout does not install `deepseek-build` or `dsb`. It does not download a prebuilt and it does not compile. Use `./scripts/install.sh` here, or `npm install -g --allow-scripts=@innocarpe/deepseek-build @innocarpe/deepseek-build` for the registry package. npm 12 does not install the agent without that flag. See the [installation guide](docs/user-guide/01-install.md) for Cargo and custom prefix options. ## How it works ```text deepseek-build | dsb │ ▼ product launcher ── auth · config · model routing │ ▼ deepseek-build-agent ── full-screen TUI · tools · sessions │ ▼ DeepSeek API ``` Three layers have explicit ownership. Higher-throughput machinery cannot bypass the edit, permission, or cache contracts beneath it. | Layer | Source | Owns | | --- | --- | --- | | **L1** | [Deep Code CLI](https://github.com/lessweb/deepcode-cli) | Snippet-safe edits, skills as context, and side-effect permissions. | | **L2** | [Reasonix](https://github.com/esengine/DeepSeek-Reasonix) | Stable-prefix economics, Flash/Pro behavior, and tool-call repair. | | **L3** | [Grok Build](https://github.com/xai-org/grok-build) | The base runtime, TUI, parallel tools, subagents, background work, and worktrees. | Reading DeepSeek's official harness added no layer to this map: the append rule and the request-versus-log check came from that evidence, described in the next section. The normative conflict rules live in the [harness philosophy](docs/architecture/HARNESS_PHILOSOPHY.md), with the complete system map in [SYSTEM_ARCHITECTURE.md](docs/architecture/SYSTEM_ARCHITECTURE.md). ## DeepSeek Harness [dsh](https://github.com/deepseek-ai/deepseek-harness) is DeepSeek's official open-source harness. It is not this product's architecture, and it is not a fourth layer: DeepSeek Build stays a Rust full-screen TUI, with edits owned by Deep Code, the cache contract owned by Reasonix, and execution owned by Grok Build. dsh is evidence for how one family behaves — a cached prefix survives a session change, and a request that does not match the session log is not sent. | What changes in a session | What the product does | | --- | --- | | A later change of the stable system body | Earlier system messages stay byte-for-byte; the new body is appended after them. The model treats the most recent system message as the current body. | | tools, skills, environment, or project instructions inside that body | The same append. The wire `tools` array is the full list on every request. There is no tool add/remove history message; Chat Completions has no field for one. | | A cache miss | The turn names which assembled document moved, as `prefix_change=`. When the epoch moved and every document hash matches, it says `unattributed` instead of inventing a cause. | | The session's cache | Once any response carried cache fields, every turn logs one `cache_session=` line. Hits and misses are token sums; a response without cache fields is `unreported` and is not counted as a miss. `deepseek-build run` and the REPL store the totals with the session, so a resume continues them. The full-screen status chip stays the last turn's ratio, the full-screen counter is not written to the session file, and a new process starts it at zero. | | A request that diverges from the log | The turn fails before sampling. An item that cannot be serialized fails closed too. | | deny | A later allow does not replace a deny. | Deliberately not taken: a plugin host, agent teams, sandbox escalation, request-series bookkeeping (`initial` / `resume` / `change`), and the Anthropic Messages transport — this product speaks DeepSeek Chat Completions ([ADR 0005](docs/adr/0005-deepseek-provider-contract.md)). Already present, so not ported again: spill of an oversized tool result (head, tail, and a path to the rest), compaction aligned to the warm prefix, and a snippet staleness guard stricter than dsh's path-scoped token. These are not new features taken from dsh. Read more: [dsh research note](docs/research/dsh-deepseek-harness.md) · [what this work changed](docs/product/CHANGELIST_6_1_0.md) · [design sources](docs/product/SOURCES.md). ## Benchmarks On 2026-10-15, **dsb** itself ran two public agent benchmarks — a Linux x64 source build driving **DeepSeek V4.1 Flash** (`deepseek-v4-flash`) with thinking on, reasoning effort `max`, and one attempt per task (`-k 1`). Both went through their official runners: Harbor for Terminal-Bench 4.0 and Pier for DeepSWE v1.1. | Model · harness | Terminal-Bench 4.0 | DeepSWE v1.1 | | --- | --- | --- | | **dsb + DeepSeek V4.1 Flash (max)** — measured here | **33.3%** (2 of 6 tasks) | **63.6%** (7 of 11 tasks) | | DeepSeek V4.1 Flash (max) — reported | 26.8% (announced 31.2%) | 74.2% | | Claude Haiku 5.5 (max) — reported | 32.8% (announced 39.2%) | not published (83.7% on SWE-bench Multilingual) | | GPT-6 Luna (max) — reported | 12.6% (announced 16.4%) | 66.6% | Reported figures are public numbers from the sources linked below; `announced` marks the model vendor's own figure next to the evaluation number. For scale, the same Terminal-Bench 4.0 board carries Claude Sonnet 5.5 at 63.6% and Claude Opus 5.5 at 59.6%. Harness is part of the score. On Terminal-Bench 4.0, Artificial Analysis ran both lightweight models with the same mini-swe-agent harness (DeepSeek V4.1 Flash 26.8%, GPT-6 Luna 12.6%), and Vals AI measured 19.7% and 13.6% in a shared environment. On DeepSWE v1.1, DeepSeek V4.1 Flash is reported at 65.6% under Codex and 69.8% under Claude Code. List prices per 1M tokens (input/output): Claude Haiku 5.5 $0.10/$0.50 (5× on prompts above 100k tokens), GPT-6 Luna $0.10/$0.50, DeepSeek V4.1 Flash $0.30/$1.20 (half price in off-peak hours). Our row is an early directional signal, not a like-for-like comparison with those boards: it covers a **task subset** (6 of 66 Terminal-Bench 4.0 tasks, with GPU and network-isolated tasks excluded; 11 of 113 DeepSWE v1.1 tasks), **one attempt per task**, and an environment that moved mid-run from Modal to a local Docker Desktop (macOS, amd64 emulation) when Modal's spend limit was reached. Sources: [aievals.app — Terminal-Bench 4](https://aievals.app/benchmarks/terminal-bench-4) · [decode.agency — AI model comparison](https://decode.agency/article/ai-model-comparison-software-development/) · [DeepSeek V4.1 Flash model card](https://huggingface.co/deepseek-ai/DeepSeek-V4.1-Flash) ## Documentation | Start here | Use it for | | --- | --- | | [User guide](docs/user-guide/README.md) | Installation, setup, daily use, and the complete feature index. | | [First-run setup](docs/user-guide/00-setup.md) | API keys, credential precedence, and headless setup. | | [Sessions](docs/user-guide/03-sessions.md) | Full-screen resume and line-mode session storage. | | [Permissions](docs/user-guide/08-permissions.md) | Interactive asks, headless denial, and workspace boundaries. | | [Subagents](docs/user-guide/11-subagents.md) · [background tasks](docs/user-guide/12-background-tasks.md) · [worktrees](docs/user-guide/13-worktrees.md) | L3 execution surfaces. | | [Known limitations](docs/product/KNOWN_LIMITS.md) | Current packaging, live-smoke, and platform boundaries. | | [Product SSOT](docs/product/SSOT.md) | Which artifact wins when product documents disagree. | ## Development ```bash cargo build -p dsb-cli cargo test --workspace ./scripts/check-semver.sh ./scripts/test-owner-bar.sh ``` The root Rust workspace covers the product crates. Avoid vendor-full Cargo runs for everyday checks; the owner-bar scripts use the bounded product path. For the crate map, see [crates/README.md](crates/README.md). For the repository map and documentation ownership, start at [docs/README.md](docs/README.md). ## Contributing Read [CONTRIBUTING.md](CONTRIBUTING.md) before making changes. All meaningful work lands through a focused PR with an atomic Conventional Commit, an existing kind label, honest test evidence, and the review narrative defined in the [PR authoring guide](docs/contributing/pr-body-standard.md). ## License DeepSeek Build is available under the [Apache License 2.0](LICENSE). Vendored and third-party code retains its original licensing; see [NOTICE](NOTICE).