deepseek-as-subagent

Purpose

deepseek-as-subagent is an MCP server project for embedding DeepSeek or a user-provided OpenAI-compatible local model as a true subagent into Claude Code or Codex CLI. The host agent retains the main conversation, planning, judgment, and verification responsibilities; the selected model has an independent agent loop for executing intensive work. Unlike most deepseek-mcp-servers that only expose DeepSeek as a single LLM call, this project lets the configured model itself perform tool scheduling, file reads and writes, optional command execution, and multi-turn reasoning against the workspace, so the host only has to hand over a complete logical unit and get back the result, thereby also saving tokens in the read/write steps.

Main capabilities

• MCP server (Python, stdio transport).
• Coding and read-only delegation: delegate_to_deepseek / delegate_to_deepseek_readonly.
• Steerable background tasks: start_deepseek / start_deepseek_readonly and shared control.
• Flash / Pro model routing: the host selects a stable tier, and the user controls the actual provider model ID in the configuration.
• Local coding agent loop (agent_loop.py), supporting OpenAI-compatible tool calls.
• Fixed capability interface: coding gets Read / Write / Edit / Bash / Glob / Grep / NotebookEdit; read-only gets Read / Glob / Grep.
• Bash execution: runs restricted, credential-isolated trusted host commands through a tool-subprocess boundary.
• Workspace path boundaries for file tools, rejecting outgoing symlinks.
• Cross-process execution leases, preventing two MCP servers from concurrently running DeepSeek against the same workspace.
• Crash-safe change log for Write / Edit / NotebookEdit, supporting recovery queries, file verification, and precise confirmation before re-delegation; changes from trusted host Bash are not logged.
• Explicit network retry policy, disabling the OpenAI SDK's internal retries to avoid nested retry amplification.
• Claude Code skill and /ds command, used for delegation policy and forced delegation.

Usage

Installation and configuration

Python 3.10-3.12 must be installed beforehand. The installer does not pipe a remote bootstrap script into a shell; instead it installs the exact dependency set verified by hash in requirements.lock, registers the MCP server with Claude Code, deploys a protected skill and a generated copy of the /ds slash command, and does not modify shell startup files. For the DeepSeek hosted API, configure the key on POSIX at ~/.deepseek-mcp/config.json, and set DEEPSEEK_API_KEY on Windows. A local loopback OpenAI-compatible server does not require a DeepSeek key.

Basic invocation

After installation, run claude and try /ds inspect this workspace and summarize its structure.

delegate_to_deepseek(task, context, model="flash") is used for coding, Bash, testing, or any task that may write to the workspace; delegate_to_deepseek_readonly(task, context, model="flash") is only for static file analysis. model is optional and accepts only flash or pro; if omitted, Flash is the default; explicitly choose pro for difficult debugging, architecture-level reasoning, or when Flash is insufficient. The host never passes the provider model ID directly.

Background delegation

For longer tasks that may need new instructions or cancellation, use the corresponding start_* background API, then use the same control methods. Steering only changes the task instructions; it cannot change the task's fixed tools, Bash availability, or the selected model tier. Cancellation wakes up retry backoff and quickly terminates the in-progress provider or local tool subprocess.

Change recovery

Changes submitted via Write, Edit, NotebookEdit are logged before commit. Trusted host Bash runs are outside this transaction log and may directly modify workspace files; these changes will not be represented by get_deepseek_recovery. After an interrupted coding run, if Bash may have executed, it should be independentlyCheck the workspace. After result reports of log changes, cancellation, disconnection, or MCP restart, the recovery process must be run; new delegations fail closed until a new delegation is confirmed by an exactly reviewed ID. Recovery does not require valid DeepSeek API credentials and never deletes or rolls back workspace files.

Claude Code assistance

• delegate_to_deepseek / delegate_to_deepseek_readonly: Claude selects the matching fixed capability and Flash/Pro tier.
• /ds <task>: forces synchronous coding delegation.
• DEEPSEEK_MODE=off claude: starts a session with DeepSeek disabled.

Local / OpenAI-compatible models

Set base_url and the model ID in the existing configuration. The exposed flash and pro selections are still host-facing tiers and may point to the same model. Supports servers that implement the OpenAI-compatible /v1/chat/completions interface, such as llama.cpp server, LM Studio, vLLM, SGLang, Ollama-compatible endpoints, etc. HTTP is limited to localhost, 127.0.0.1, and [::1]; remote endpoints must use HTTPS. The server is required to support OpenAI-compatible tool calling, sufficient context, and well-formed tool calls. The token budget per run is 1,000,000 cumulative input and output, and conversation history has an additional 12 MiB encoded JSON limit.

Applicable scenarios

• Multi-file implementation, mechanical refactoring, test generation.
• Large data volume plus simple processing (log scanning, file conversion, ETL).
• Tasks that may benefit from an independent cheap execution loop.
• Not suitable for: tiny edits where orchestration overhead dominates, cross-domain architecture, ambiguous root cause analysis, security-sensitive judgment.

Limitations

• Coded Bash runs on the trusted host, not an OS sandbox, though restricted and credential-isolated.
• Only one DeepSeek execution is allowed at a time for the same canonical workspace; the lease only coordinates DeepSeek MCP execution and cannot prevent the host, IDE, user, or other local processes from changing the workspace.
• Background task IDs and results are session-scoped and results must be collected before closing the host session.
• Turning to cannot upgrade read-only tasksif a read-only task subsequently needs commands or workspace changes, it must be canceled or completed before creating a new coding task.
• Trusted-host Bash changes are not logged, and the workspace must be independently checked after an interruption.
• Delegation prompts and the tool/file output selected by the agent are sent to the configured OpenAI-compatible API, and only data that the endpoint is allowed to receive should be delegated.
• Local Python module signatures are implementation details, not a stable public API.
• The project does not claim to have tested all server versions or models.

Pricing

Not yet provided.