PsChina/deepseek-as-subagent

**English** · 简体中文
> Run DeepSeek — or your own OpenAI-compatible local model — as a **real sub-agent** inside Claude Code / Codex CLI.
> The host agent keeps the main conversation, planning, judgment, and verification.
> The selected model gets its own agent loop for execution-heavy work.
> Coding APIs use workspace-scoped writes and bounded trusted-host Bash; separate read-only APIs provide pure file analysis without command execution.
Full coding delegation
Coding Bash runs on the trusted host with cwd=workspace; it is bounded and
credential-isolated, but it is not an OS sandbox.
Read-only analysis delegation
Quick start
Python 3.10–3.12 must already be installed. The installer never pipes a remote
bootstrap script into a shell. It installs the exact, hash-verified dependency
set in requirements.lock, registers the MCP server with Claude Code, deploys
protected generation copies of the skill + /ds slash command. It does not
modify shell startup files. Helper deployment is best-effort after the core MCP
registration commits; a foreign destination is preserved and reported.
For DeepSeek's hosted API, configure a key in ~/.deepseek-mcp/config.json on
POSIX or set DEEPSEEK_API_KEY on Windows (get one at
platform.deepseek.com). A local loopback
OpenAI-compatible server does not need a DeepSeek key. Then run claude and
try /ds inspect this workspace and summarize its structure.
To upgrade, fetch and inspect an explicit tag or commit, then re-run the local
installer. Coding always uses trusted_host; read-only APIs need neither Bash
nor Docker/Podman. For
Codex or other MCP clients, see Install below.
How is this different from existing DeepSeek MCP servers?
Most deepseek-mcp-server projects expose DeepSeek as a **single LLM call** (create_chat_completion, create_anthropic_message). The host has to read every file itself and feed content into the prompt — DeepSeek only saves the "thinking" cost, not the "reading/writing" cost.
This project gives the configured model **its own agent loop**: tool dispatch,
file I/O, optional command execution for coding, and multi-turn reasoning
against the configured workspace. The host hands off a complete logical unit
and gets a result back. Token savings are end-to-end.
What's in the box
- **MCP server** (Python, stdio transport)
- **Coding and read-only delegation**: delegate_to_deepseek / delegate_to_deepseek_readonly
- **Steerable background jobs**: start_deepseek / start_deepseek_readonly plus shared controls
- **Flash / Pro model routing**: host chooses a stable profile; users control the actual provider model IDs in config
- **Local coding agent loop** (agent_loop.py) with OpenAI-compatible tool calling
- **Fixed capability APIs**: coding gets Read / Write / Edit / Bash / Glob / Grep / NotebookEdit; read-only gets Read / Glob / Grep
- **Bash execution**: bounded credential-isolated trusted-host commands through the tool-child boundary
- **Workspace path boundary** for file tools, with outbound symlinks rejected
- **Cross-process execution lease** so two MCP servers cannot run DeepSeek concurrently against the same workspace
- **Crash-safe mutation journal for Write / Edit / NotebookEdit** with recovery query, file verification, and exact acknowledgement before another delegation; trusted-host Bash changes are not journaled
- **Explicit network retry policy** with OpenAI SDK internal retries disabled to avoid nested retry amplification in proxy/TLS-timeout environments
- **Claude Code skill + /ds command** for delegation policy and forced delegation
Compatibility
The four delegation entry points accept one additive optional argument,
model="flash" | "pro". Existing calls that omit it remain valid and now default
to the Flash profile. Background-job and recovery tools remain additive.
Mutation-capable legacy hosts must adopt the recovery query/verify/ack handshake
before starting another delegation; read-only use needs no change.
Clients should not parse health/error text byte-for-byte because diagnostics are now more specific. Provider calls use an OpenAI-compatible Chat Completions API, including DeepSeek's compatible endpoint.