Preface¶

DeepSeek Harness (referred to as DSH) packages models, tools, conversations, and interfaces all as plugins, with the philosophy of “everything is a plugin”. In actual work, many people do not stay exclusively within DSH: some have their main workspace in Codex, hoping to continue their main tasks via OpenAI while delegating retrieval, logging, and large-scale text organization to the more affordable DeepSeek; others already use deepseek-v4-pro in Pi, hoping that their first request will follow the engineering trajectory of DSH Minimal, while still using Pi’s read/edit/write and existing plugins for subsequent steps.

mixagents is designed for these two scenarios. It is maintained by Utopia-V, licensed under MIT, with its GitHub repository at https://github.com/Utopia-V/mixagents. The community plugin directory categorizes it under “Models and Providers”, and it currently has 169 GitHub stars. It should be made clear upfront: this community directory is an independent site and has no official affiliation with DeepSeek / Fangxin; the repository itself also states that the project has no affiliation with or official endorsement from OpenAI, DeepSeek, Pi, or OpenCode.

What is mixagents?¶

mixagents is not a single Cordis runtime plugin, but two independent components in the same repository:

The repository was formerly named Utopia-V/codex-deepseek-subagent before being renamed to mixagents. The old name will remain empty to allow existing web pages, Git remotes, and raw prompt links to continue redirecting.

The universal installation command given on the directory page is:

dsh plugin add github:Utopia-V/mixagents

For reproducible installations, the directory page recommends pinning a commit. The latest commit on the current main branch (2026-08-17) is:

dsh plugin add github:Utopia-V/mixagents#925ba7d5e7a07c4bb34a8d03784016283bff8acf

This command is taken verbatim from the directory page. After cross-referencing the repository source code, note that there is no package.json or dsh.bundle declaration in the repository root. The installation paths clearly documented in the README are the Codex installation prompt, and Pi’s pi install npm:pi-dsh-mimic. If your goal is to “connect DeepSeek Flash to Codex” or “replicate the DSH Minimal first request in Pi”, follow the official steps in the two sections below, and do not assume that dsh plugin add will automatically turn into a usable DSH runtime layer.

Plugins (and Pi extensions) run with the current process’s permissions, and may execute code during installation. Inspect the source repository and license before installing.

Codex DeepSeek Subagent: Keep the Main Agent, Let Flash Handle Subtasks¶

This component has a narrow scope: the main tasks continue to use existing GPT/OpenAI models and ChatGPT login, and DeepSeek only appears in the standalone v4_flash_worker child. It is not an MCP Server, another Codex CLI, nor does it require CC Switch to switch global providers. Codex remains responsible for child creation, permissions, cancellation, and callbacks; the repository only adds a trusted SubagentStart Hook to resolve the task delivery issue from the current OpenAI parent to a non-OpenAI child.

The reason is explained in the advanced documentation: when Multi-agent V2 crosses providers, children may only see unexplainable encrypted_content and fail to pass the actual task. The repository uses a one-time plaintext handoff: the parent Agent writes the full assignment temporarily to the local user state, and the Hook picks it up and injects it when the v4_flash_worker starts. This is a transport compatibility layer, not an encrypted channel.

Tested baselines (from the component’s advanced documentation):
- Windows Codex Desktop: 26.727.6591.0
- Codex CLI: 0.146.0
- DeepSeek model alias: deepseek-v4-flash (documented version DeepSeek-V4-Flash-0731)
- Python/POSIX paths for macOS have passed native callback smoke and 27 protocol tests on Codex 0.146.0; Linux uses the same POSIX implementation

3-Step Installation¶

1. Set DEEPSEEK_API_KEY

Create an API key on DeepSeek and save it as the environment variable DEEPSEEK_API_KEY. Do not share the key in Codex chats, Issues, screenshots, or repositories.
- Windows: Create a new user environment variable DEEPSEEK_API_KEY, then fully exit and restart Codex Desktop.
- macOS / Linux: Set this variable in the shell that launches Codex or a secret manager, then launch Codex.

macOS also has a Keychain authentication template, which will only be used if explicitly selected; existing configurations will not be automatically migrated.

2. Submit the following prompt to Codex

Please read and strictly follow the instructions at https://raw.githubusercontent.com/Utopia-V/mixagents/main/packages/codex-deepseek-subagent/prompts/install-with-codex.md to install the DeepSeek V4 Flash subagent for me. Keep the current main model, provider, and ChatGPT login, do not ask for or output an API key; stop after completing local verification without paid calls, do not run the smoke test for now.

The installation process will download and merge Agents, skills, Hooks, and two AGENTS.md indexes. It will not call DeepSeek or change the main model.

3. Trust the Hook, then open a new task to run the smoke test

Enter /hooks in Codex, confirm that it only matches v4_flash_worker, and that the command points to the newly installed plaintext-handoff script, then select Trust. Existing running tasks may not reload the Hook, so you need to open a new task. Copy and paste the following prompt:

Please read and strictly follow the instructions at https://raw.githubusercontent.com/Utopia-V/mixagents/main/packages/codex-deepseek-subagent/prompts/quick-smoke-test.md to test the newly installed v4_flash_worker. Do not use an alternative provider, direct API, or another Codex CLI.

The quick smoke test does not require cloning the repository, but will trigger one small DeepSeek API call. On success, you should see: a standalone child appears with agent type v4_flash_worker; the child returns the randomly generated marker from the parent Agent and gets arithmetic=323; the one-time pending handoff has been consumed; the main task still uses the original OpenAI model.

After installation, the parent Agent will load $use-v4-flash-worker on demand for appropriate tasks, and will not force every task to use Flash. The README recommends delegating search, logging, enumeration, and reading tasks that have clear boundaries, are text-heavy, and produce large amounts of raw material with only a small number of conclusions to Flash; tightly coupled reasoning, decision-making, verification, and final integration should remain with the parent Agent.

Pi DSH Mimic: Borrow DSH’s First Request Only¶

pi-dsh-mimic addresses a different scenario. Pi already supports calling deepseek-v4-pro or opencode-go/deepseek-v4-pro, but the default first request carries the full Pi prompt and a full set of tools. This component only replicates DSH Minimal in the first model request of a new session: the persona uses You are a helpful software engineer assistant., and only exposes bash and str_replace_editor externally. After the first valid assistant response or durable tool call, request #2 immediately reverts to Pi’s native payload and current full tool directory, and other plugin tools will appear naturally. The Minimal persona persists for the entire session, and Pi’s long automatic system prompt will not be replayed as an additional user message.

Users do not need to install or run the full DSH harness. Pi still handles actual task execution, session management, and plugin composition. The extension does not add identity warm-up, replicate the original task, inject We need, or proxy APIs.

Installation and Usage¶

Requirements: Node.js 22.19 or newer, Pi 0.84.2 or newer, and DeepSeek official API or OpenCode Go configured. Pi 0.84.2 has built-in support for these two provider paths.

User-level installation:

pi install npm:pi-dsh-mimic

Project-level installation:

pi install -l npm:pi-dsh-mimic

Try the current checkout directly:

pi -e ./packages/pi-dsh-mimic \
  --provider deepseek \
  --model deepseek-v4-pro

When using OpenCode Go, place the key in Pi’s expected OPENCODE_API_KEY environment variable, and change the provider to opencode-go. First select V4 Pro, then create a new session. Switching to V4 Pro in the middle of an existing conversation will not fake a new bootstrap.

How to Interpret Project2 Scores¶

The benchmark cited in the README comes from the maintainer’s personal, self-hosted long-range code maintenance evaluation Project2 V4.1b: the model takes over a multi-module Python backend and ESP32-S3 firmware repository with intentionally retained defects. It is not a cross-project general benchmark, and the scores only describe this frozen task.

The default Pi baseline is 92. Four final results from the same one-shot request flow are 98, 96, 96, 98, all maintaining F3 16/16. The maintainer concludes that the DSH Minimal first request can stably establish a high-capability trajectory in Pi, and restoring the full tool directory will not automatically break it. The experimental documentation also records several rejected designs, such as extra identity rounds, only reducing the number of tools, simulating the DSH wire throughout the session, and replaying the full Pi system context after recovery; all these paths scored lower than the “first request Minimal, then revert to Pi” approach.

On the offline side, TypeScript typecheck has passed, and all 13 automated tests have passed. Package behavior tests cover first request field order, request #2 restoring the full directory, images, API error retries, session resume, and crash-stale recovery. Provider errors or aborted responses do not consume the bootstrap.

How to Choose¶

• If you want to keep Codex’s OpenAI main Agent while using the cheaper DeepSeek child for clearly bounded text work, install Codex DeepSeek Subagent.
• If you already use deepseek-v4-pro or opencode-go/deepseek-v4-pro in Pi and want to start from the verified DSH Minimal trajectory while continuing to use Pi’s read/write tools and other plugins, install Pi DSH Mimic.
• The two components do not depend on each other; choose one based on your runtime environment.

Applicable Scenarios and Notes¶

This is suitable for users who are already using Codex or Pi and accept sending task content to DeepSeek / OpenCode. It is not suitable for those who understand mixagents as a Cordis plugin that “swaps models by loading it into the DSH Web UI”; the repository’s public documentation does not include this path.

Security and cost boundaries are governed by the repository’s SECURITY.md, only the documented points are listed here:
1. Both components will send task content to the third-party provider configured by the user. The local sandbox restricts file system modifications, not confidentiality boundaries.
2. The Codex component temporarily stores plaintext assignments in the local user state. Default locations: Windows is %LOCALAPPDATA%\Codex\plaintext-subagent-handoff; macOS/Linux is $XDG_STATE_HOME/codex/plaintext-subagent-handoff or ~/.local/state/codex/plaintext-subagent-handoff. After installation, you must review and trust the Hook in /hooks, do not forge a trust hash for non-interactive installations.
3. The Pi component runs with the file system permissions of the Pi process, and the provided str_replace_editor can create and modify files. It does not read, save, or transmit API keys, and does not add extra model rounds.
4. DeepSeek and OpenCode fees are independent of ChatGPT / OpenAI subscriptions. Installation and offline tests should not call models; quick smoke tests and full model runs will be billed to the corresponding account.
5. The repository explicitly requires: do not share API keys, full request headers, or unredacted configurations in Issues or chats.

Windows users who have just modified environment variables need to fully restart Codex, otherwise the child may fail to read DEEPSEEK_API_KEY. The advanced documentation also mentions: User/HKCU command auth may run under the sandbox identity, which is not the default env_key path. The PowerShell hardening implementation has passed local protocol, concurrency, and recovery tests, and the repository notes that it is awaiting a live smoke test after an update.

Summary¶

mixagents packages two already documented and tested features into the same repository: Codex continues to use the OpenAI main model while making Flash a native subagent; Pi only borrows DSH Minimal for the first request before reverting to its own tools and plugins. The community directory can be used to discover it, while the actual steps to get it running are in the GitHub README.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/mixagents/

GitHub: https://github.com/Utopia-V/mixagents