deepseekcode

English · 简体中文

deepseekcode is a terminal coding agent for DeepSeek models and OpenAI-compatible chat-completions endpoints. It ships as a single Go binary named dsc, with an interactive TUI, one-shot CLI mode, repository tools, SQLite-backed sessions, and a conservative permission model.

Why dsc (DeepSeek specialization)

• Provable prefix-cache stability -- a single canonical serializer feeds both the wire bytes and the cache fingerprint; they cannot diverge by construction, and dsc trace inspect shows prefixes==1 to prove a stable run (docs/prefix-cache.md).
• Real, signal-driven Flash→Pro routing -- opt-in via --auto-route (escalates on ambiguity / repeated repair), not just a prompt instruction; always-on Duet pro-validator fires on destructive tool calls (docs/duet.md).
• Real OS sandbox -- sandbox-exec (macOS) / Landlock (Linux) with a real PTY, not just path containment (docs/SANDBOX.md).
• Auto reasoning-effort -- per-turn thinking on/off via multi-language keyword detection plus low/medium/high/max effort, dialed down automatically on simple tasks.

DeepSeek V4 Agent Story

DeepSeekCode is purpose-built for DeepSeek V4 models with verifiable advantages over generic coding agents:

Measured, not claimed. In a reproducible 12-turn session on deepseek-v4-flash, deepseekcode holds a 94.7% prefix cache-hit rate vs 0% for a cache-naive agent — 4.5× cheaper, every figure read from DeepSeek's own prompt_cache_hit_tokens. Run it yourself: make demo-cache (live) or make demo-cache-offline (no API key). Methodology: bench/cache-demo.

• Provable prefix-cache stability — a single canonical serializer guarantees the wire bytes and cache fingerprint cannot diverge; verify with dsc trace inspect (docs/prefix-cache.md).
• Selective Pro validation — destructive tool calls get a second deepseek-v4-pro judgment, not every turn; keep costs low with a safety net where it matters (docs/duet.md).
• 1M context workflows — large-repo reading and long-history sessions without aggressive compaction; 1M context is an enabler, not a replacement for tools and retrieval.
• Tool-call repair pipeline — automatic recovery from truncated JSON, scavenged calls in reasoning text, and storm-guard suppression of repeated failed calls.

Full story with local verification commands: docs/deepseek-v4-agent-story.md

Benchmark evidence: bench/README.md

Tool-use benchmark (tau-bench-lite, 8 tasks): dsc is at parity on cost-per-solved (~$0.00038) with a strong DeepSeek-native flash baseline — we report parity and do not claim a capability win on easy tool-use tasks (a routing advantage needs a harder task set to surface). See bench/taubench.

Features

• Interactive Bubble Tea TUI and scriptable dsc -p "prompt" mode.
• DeepSeek-first runtime with thinking, reasoning_effort control, long context, prefix-cache metrics, and deepseek-v4-flash / deepseek-v4-pro support.
• OpenAI-compatible provider configuration for alternate chat-completions endpoints.
• Repository tools for file reads/edits, patches, shell commands, git, grep, LSP queries, web fetch/search, and user questions.
• Persistent project sessions with resume, branching, scrollback export, and /undo for recent edit steps.
• Extensibility through custom slash commands, SKILL.md discovery, MCP tools, subagents, and isolated git worktrees.
• Safety controls for read-only mode, ask-before-tool mode, auto-approve mode, secret path checks, bash allowlists, optional sandboxing, and Pro validation for destructive operations.

Installation

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/amemiya02/deepseekcode/main/install.sh | sh

Homebrew:

brew install amemiya02/deepseekcode/deepseekcode

Scoop:

scoop bucket add deepseekcode https://github.com/amemiya02/deepseekcode-scoop
scoop install deepseekcode

Go:

go install github.com/amemiya02/deepseekcode/cmd/dsc@latest

From source:

git clone https://github.com/amemiya02/deepseekcode
cd deepseekcode
make build
./bin/dsc -version

Requirements:

• Go version matching go.mod or newer when building from source.
• DEEPSEEK_API_KEY, or another provider key configured in .deepseek/config.toml.
• Git and language servers are optional, but enable richer repository context.

Quick Start

export DEEPSEEK_API_KEY=sk-...

dsc                              # open the TUI
dsc -p "summarize this repo"     # run one prompt and exit
dsc --read-only                  # inspect without write/edit/bash tools
dsc init                         # create starter project config
dsc doctor                       # check local setup

Session shortcuts:

dsc -c                 # continue the latest session in this project
dsc -r <session-id>    # resume a specific session
dsc -new               # force a new session

Configuration

Configuration is layered from built-in defaults, user config, project config, and CLI flags. Project config lives at ./.deepseek/config.toml; user config lives at ~/.deepseek/config.toml.

Minimal DeepSeek config:

[active]
provider = "deepseek"

[providers.deepseek]
type = "deepseek"
base_url = "https://api.deepseek.com"
env_var = "DEEPSEEK_API_KEY"
first_token_timeout_ms = 45000
chunk_stall_timeout_ms = 20000

[defaults]
model = "deepseek-v4-flash"
thinking = true

OpenAI-compatible endpoint:

[active]
provider = "openai"

[providers.openai]
type = "openai-compat"
base_url = "https://api.openai.com"
env_var = "OPENAI_API_KEY"
default_model = "gpt-4o"

See docs/config.md and docs/PROVIDERS.md for the full reference.

Documentation

• Configuration
• Providers
• Tools
• Permissions
• Sandboxing
• Custom commands
• Skills
• MCP
• LSP
• Reasoning tape
• Model compatibility
• DeepSeek V4 Agent Story

Development

make build       # build ./bin/dsc
make test        # go test ./...
make test-race   # go test -race ./...
make lint        # go vet ./...
make fmt         # gofmt -s -w .
make run         # build and launch the TUI

Before opening a pull request:

make fmt
make lint
make test

Contributing

Issues and pull requests are welcome. Keep README changes synchronized between README.md and README.zh-CN.md with matching ## structure. Document only features that are implemented and testable in this repository.

Star History

License

MIT