DSH Subagent MCP

Give Codex a DeepSeek coding agent that can read your repo, edit files, and run tests. Ask it another question when it finishes. Check in while it works. Stop it when the plan changes.

Your Codex conversation becomes the place you direct the work. DSH handles the delegated task in its own session.

Built for ongoing collaboration

Related MCP server: dsh-crew

Get started

You'll need Linux with systemd, Node.js satisfying the package requirement, Codex CLI, and a working DSH installation with provider credentials.

npx -y dsh-subagent-mcp@latest setup --skill

No clone needed. Setup installs the runtime in a persistent user directory, so the service and skill do not depend on the npx cache. Add --web during setup to connect an already initialized DSH Web profile in the same command.

If your DeepSeek key is only in the current shell's DEEPSEEK_API_KEY, add --capture-key to the setup command. See installation and credentials for details.

If you also use DSH Web, initialize its Web profile and install the adapter:

npx -y dsh-subagent-mcp@latest web

Profiles with patchReload: live load it automatically; otherwise restart the Web profile after its work finishes. See Web integration and upgrades.

Open a new Codex session and try:

Use $dsh-subagent to review this repository's error handling in read-only mode.
Keep the agent available for follow-up questions.

The skill handles the delegation workflow; the MCP server supplies the execution tools. DSH appears in Codex as MCP activity.

From “look into this” to “make the change”

Completion returns through a pending tool call. The parent must keep its turn active; this does not automatically wake an ended conversation. See completion handoff.

An example workflow with the bundled skill:

You → Codex
Use $dsh-subagent to investigate why cancelled requests leave workers running.
Have it trace the code and report what it finds. Don't change files yet.

You → Codex
What has DSH found so far?

You → Codex
Ask that same agent whether the timeout path has the same problem.

For an agent given permission to edit:

You → Codex
Have DSH implement the agreed fix and run the relevant tests.

You → Codex
Stop it. We've changed the approach. Wait until it stops, then give it this plan: …

Standard by default, visible in DSH Web

New subagents use DSH's standard preset by default, including automatic context compaction and tool-result pruning. It is mounted before the first task. Follow-ups retain the original preset, including across restarts.

Pass preset: "minimal" explicitly for the fixed-prompt, single-shell preset without automatic compaction. Existing sessions keep their original configuration.

Sessions are registered under their working directory in DSH. With the Web adapter installed, the DSH Web conversation receives tool activity and streamed replies without a manual refresh. You can watch a task delegated from Codex in the browser; when following the latest output, long replies scroll into view as they arrive.

Go further

The MCP bridge returns compact receipts for dsh_start and dsh_followup. dsh_status and dsh_list are compact lifecycle views, while dsh_wait returns the final answer once after settlement. Omit seconds for persistent work. dsh_events defaults to new assistant-visible text; request tool summaries explicitly and use an event_id for one full tool record. Large events return a continuation cursor. Use legacy: true only for compatibility with older full state payloads.

Follow-ups, progress and cancellation · Permissions and architecture · Service management · Validation

If this makes DSH useful in your workflow, a star helps others find it. Share what you build—or what gets in the way—in Issues.

Built on

DeepSeek Harness and the MCP SDK. Thanks to dsh-mcp and dsh-cursor-codex for exploring DSH delegation, and DSH-Code for the terminal UI that sparked this project.

MIT. Independent community project.