Introduction

In DeepSeek Harness (DSH), pure text models cannot receive images through the native attachment channel, and DSH directly rejects messages that contain images. A common engineering approach is to pass a file path, while a separate tool reads and analyzes the file. dsh-codex-media is the “analysis-side” tool in this chain. It only reads the path and includes no upload logic, so it can work with dsh-drop-to-path to allow text models to process images and documents.

Plugin Overview

The plugin provides image and document analysis capabilities, powered by a local OpenAI Codex CLI, and does not depend on third-party runtime libraries (it uses only built-in features from Node.js 22+).

Core features:
- analyze_image: Describes local images or answers questions about images (supports PNG, JPEG, WebP, GIF). Images are mounted natively via codex exec --image.
- analyze_document: Analyzes local documents (PDF, Office, RTF, or text formats) or answers targeted questions. The model only returns answers, avoiding injecting extracted text into the agent’s context.
- generate_image: Generates an image from a text prompt and saves it to a local file. By default, it uses Hermes Agent One-shot mode (no API key required), and also supports the OpenAI Images API.

Installation and Dependencies

Before installing, make sure the following conditions are met:
- Node.js >= 22
- The dependency plugin dsh-drop-to-path (MIT License), which handles file upload and path generation.

Installation steps:

  1. Install the upload dependency first:
    dsh plugin --profile web add github:loudMore/dsh-drop-to-path
  1. Then install the analysis tool:
    dsh plugin --profile web add github:binsarjr/dsh-codex-media
  1. Restart dsh web and refresh the page.

Core Features and Transport Methods

The plugin invokes the underlying Codex engine through multiple transport methods.

Supported transport methods:
- cli (default for analysis): Starts codex exec --json and parses the JSONL stream. It depends on Codex CLI authentication (ChatGPT sign-in or OPENAI_API_KEY).
- hermes (default for generation): Starts hermes -z. It depends on Hermes Agent authentication and can use ChatGPT sign-in without an API key.
- api-compatible: Directly calls the HTTP chat/completions endpoint and sends files as base64-encoded data. Requires CODEX_ANALYSIS_API_KEY and CODEX_ANALYSIS_BASE_URL to be configured.
- api-responses: Calls the official OpenAI Responses API and supports input_file and input_image. Requires the corresponding API key and Base URL to be configured.

Configuration and Usage Examples

The plugin controls its behavior at runtime through environment variables.

Key environment variables:
- CODEX_ANALYSIS_TRANSPORT: Transport method, default cli.
- CODEX_ANALYSIS_API_KEY / CODEX_ANALYSIS_BASE_URL: Key and URL required for HTTP transport.
- CODEX_ANALYSIS_IMAGE_MODELS / CODEX_ANALYSIS_DOCUMENT_MODELS: Fallback order for the vision model and document model.

Local testing examples:
Run the following commands in the project directory to verify functionality:

npm run smoke:image      # 测试图片分析
npm run smoke:document   # 测试文档分析
npm run smoke:generate   # 测试图片生成

Notes

  • Permissions and Security: The plugin runs with the same permissions as the current DSH process. Strict validation is performed before each call, including checking that the path is not empty, extension allowlist, file size limits, and PDF magic number signature.
  • Dependencies: The plugin does not include upload code and must be used together with dsh-drop-to-path.
  • Code Review: As an open-source plugin, it is recommended to review the source code and license (MIT) before installation.

Summary

dsh-codex-media wraps local Codex capabilities as DSH tools, solving the problem that text models cannot directly process multimedia. By configuring different transport methods, developers can use CLI/Hermes without an API key, or connect directly to OpenAI-compatible endpoints for independent deployment.

View the plugin directory
Access the GitHub repository