deepseek-as-subagent

English · 简体中文

Run DeepSeek as a real sub-agent inside Claude Code / Codex CLI — not just an LLM endpoint. The host agent keeps the main conversation, planning, judgment, and verification. DeepSeek 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

       Claude / Codex (main agent)
         ├─ ordinary coding → delegate_to_deepseek
         └─ coding task whose direction may change
                            → start_deepseek → job_id
                                               ├─ send_deepseek_message(job_id, ...)
                                               ├─ get_deepseek_status(job_id)
                                               ├─ cancel_deepseek(job_id)
                                               └─ get_deepseek_result(job_id)
         ▼
       DeepSeek coding sub-agent
         │  Read / Write / Edit / Bash / Glob / Grep / NotebookEdit
         │  autonomously reads, modifies, runs, and tests in the workspace
         ▼
       Result returns to the host
       Host verifies representative changes / tests

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

       Claude / Codex (main agent)
         ├─ ordinary read-only analysis → delegate_to_deepseek_readonly
         └─ read-only analysis whose direction may change
                            → start_deepseek_readonly → job_id
                                                        ├─ send_deepseek_message(job_id, ...)
                                                        ├─ get_deepseek_status(job_id)
                                                        ├─ cancel_deepseek(job_id)
                                                        └─ get_deepseek_result(job_id)
         ▼
       DeepSeek read-only sub-agent
         │  Read / Glob / Grep
         │  autonomously reads, searches, reviews, and performs static analysis
         ▼
       Analysis returns to the host
       Host verifies the conclusion

Quick start

git clone https://github.com/PsChina/deepseek-as-subagent.git
cd deepseek-as-subagent
# Inspect install.sh and requirements.lock, then:
./install.sh

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.

After install, edit ~/.deepseek-mcp/config.json to paste your DeepSeek API key on POSIX, or set DEEPSEEK_API_KEY on Windows (get one at platform.deepseek.com). 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 DeepSeek 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 DeepSeek agent loop (agent_loop.py) with OpenAI-compatible function 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 still use DeepSeek's OpenAI-compatible Chat Completions API. Local Python module signatures are implementation details rather than a stable public API.

Install

Claude Code (default)

git clone https://github.com/PsChina/deepseek-as-subagent
cd deepseek-as-subagent
./install.sh

Then edit ~/.deepseek-mcp/config.json on POSIX, or set DEEPSEEK_API_KEY on Windows.

Codex CLI

git clone https://github.com/PsChina/deepseek-as-subagent
cd deepseek-as-subagent
bash adapters/codex/install.sh

See adapters/codex/README.md for the Codex-specific install, delegation policy, and background-job workflow.

The Claude and Codex installers build a fresh isolated runtime, validate its configuration and MCP protocol, and only then switch the host registration. They keep the active generation plus one previous generation for recovery. Any manual runtime must stay outside a delegated workspace when file-mutation tools are enabled; unsafe layouts are rejected at startup. Both installers serialize install/uninstall transactions. A hard-killed installer intentionally leaves an empty fail-closed lock that must be removed only after confirming no installer is running.

Cursor / Cline / Claude Desktop / other MCP clients

The MCP server itself is client-agnostic. Install requirements.lock with pip --require-hashes, install this project with dependency resolution disabled, then point your client's MCP config at the generated deepseek-mcp entrypoint.

Usage

Choose capability for the task's entire expected lifecycle first. Use read-only only when every expected step is static file analysis with Read, Glob, and Grep—no command execution. If any step might need Bash, tests, builds, lint, Git, program execution, dependency work, workspace mutation, or is not clearly read-only, choose coding.

Simple delegation

Use a synchronous API when the task can run to completion without mid-flight intervention. The MCP request remains open until DeepSeek finishes:

• delegate_to_deepseek(task, context, model="flash") for coding, Bash, tests, or any task that might write the workspace.
• delegate_to_deepseek_readonly(task, context, model="flash") for static file analysis only.

model is optional and accepts only flash or pro. Omit it for normal work; select pro explicitly for difficult debugging, architecture-level reasoning, or when Flash has already proved insufficient. The host never passes a provider model ID directly.

Steerable background delegation

For longer tasks that may need new instructions or cancellation, choose the matching background API, then use the same controls for either job type:

start_deepseek(task, context, model="flash") / start_deepseek_readonly(task, context, model="flash") -> job_id
send_deepseek_message(job_id, message)
get_deepseek_status(job_id)
cancel_deepseek(job_id)
get_deepseek_result(job_id)