DeepSeek Harness (DSH) is a plugin-based platform that allows developers to call external services through tools. Local Codex sessions usually run in the Codex desktop app, and interfacing with its protocol presents technical barriers. This plugin uses the Codex app-server protocol to enable real-time observation of these sessions and command delivery within Harness.

Plugin Information

  • Project Name: juyanjy/dsh-codex-bridge
  • Project Description: Connects to and steers local Codex (OpenAI) sessions from DeepSeek Harness via the Codex app-server protocol.
  • Maintainer: JUYANJY
  • Category: Workflow
  • Open Source License: MIT
  • Install Command:
  node scripts/install.mjs

Core Features

This plugin provides a toolset for monitoring and controlling local Codex processes:

  • Protocol Connection: Connects to the Codex app-server protocol, supporting observation and steering of sessions.
  • Status Monitoring Tools:
  • codex_status: Checks account information, plan, rate-limit budget, and local process status.
  • codex_threads: Lists recent threads, with filtering by search string.
  • codex_transcript: Retrieves the detailed transcript for a specified thread.
  • codex_watch: Monitors the real-time stream of a thread and returns events as they pass through.
  • codex_queue: Views queued messages in a thread, with support for cancellation.
  • Interaction and Control:
  • codex_send: Sends a message to Codex, supporting the queue (enqueue), turn, and steer (guide) parameters.
  • codex_approvals: Lists pending approval requests and replies to them.
  • codex_budget: Reads rate-limit buckets and determines whether the quota has been exceeded.
  • codex_ask: Asks a question in an ephemeral thread and backfills the answer into the development thread.
  • codex_handoff: Builds a handoff briefing, supporting the prepare (prepare handoff) and claim (claim handoff) actions.
  • Visualization Panel: Provides a Codex sidebar panel in Harness, displaying four states: Needs you (red), Blocked (orange), Running (green), and Nothing observed (gray).
  • Automation Assistance: Supports the automatic continuation message feature “Keep Codex moving for 30m”.

Typical Usage

  1. Monitor Thread Stream:
    Use codex_watch to monitor the real-time stream of a thread, merging the real-time notification stream and polled records.
  2. Send Instructions:
    Use codex_send to send a message. If the desktop app holds the write lock for the thread, it automatically falls back to queue mode.
  3. Take Over a Session:
    Use codex_handoff to prepare a handoff briefing. If you need to formally claim the handoff, you must explicitly call codex_handoff action=claim.
  4. Check Status:
    Use codex_status to check the local process and the rate-limit budget of the Codex account.

Notes

  • Runtime Environment: Requires Node.js version >= 22.
  • Dependencies: @deepseek-ai/dsh-tools and @deepseek-ai/schemastery are optional peerDependencies.
  • Handoff Flow: Preparing a handoff briefing does not count as a handoff; you must explicitly call codex_handoff action=claim to claim the handoff.
  • Sampling Mechanism: Checks of queues, items, turns, and targets are sampled rather than full reads.
  • Quota Logic: Rate-limit buckets use usedPercent. 100% is not reported as “out of quota” unless the server marks it as exceeded.