Introduction

The built-in headless mode of DeepSeek Harness (dsh) defaults to printing only the final reply text and returning a 0/1 exit code. This is suitable for quick validation, but it is too limited for CI (continuous integration) pipelines. CI systems often require machine-readable detailed reports (such as JSON or JUnit XML) and more granular semantic exit codes.

headless- is a plugin designed for dsh. It turns ordinary session conversations into first-class CI artifacts: it provides JSON/NDJSON session reports, JUnit XML test reports, semantic exit codes, file asset collection, and privacy redaction features. It functions both as a dsh profile bundle and as a standalone CLI tool.

Core Features

This plugin subscribes to dsh session event streams and generates structured data either when a session ends or during runtime.

  • Session event streams: Subscribes to events such as session/created, session/event, and session/disposed, converting each round of interaction and tool invocation into structured events (including type, model, latency, token statistics, error information, and more).
  • JSON output: Generates a complete transaction-level report containing session metadata, event lists, results, and statistics.
  • JUnit XML output: Maps tool invocations and steps to test cases, allowing CI systems to display dsh execution the same way they display normal test runs.
  • Semantic exit codes: Differentiates success, failure, timeout, blocking, interruption, and other states, while providing overridable default codes.
  • Asset collection: Scans file paths referenced in conversations and generates a manifest including existence and size information.
  • Privacy toggles: Supports text truncation, parameter hiding, secret masking, and path relativization. These options can be configured at mount time or at runtime via set_options.
  • Toolchain: Provides three dsh tools (output_status, output_events, and set_options) as well as standalone CLI entry points (dsh-headless- render and dsh-headless- exit).

Installation and Enablement

Before use, ensure that Node.js >= 18 is installed and that the dsh installation includes the sessions service (any base or headless profile satisfies this requirement).

  1. Add the plugin: Add the plugin as a profile bundle to the headless profile via the CLI.
    dsh plugin --profile headless add github:JohnXu22786/headless-
  1. Run a test: Execute a command with the profile enabled.
    dsh --profile headless "run the test suite"

After execution completes, report files are generated in the `dsh-output/` directory.
  1. CI integration examples:
    • Get semantic exit codes:
        dsh-headless- exit dsh-output/report.

*   Render JUnit XML:

        dsh-headless- render dsh-output/report. --format junit --out junit.xml

Use Cases and Notes

  • Deterministic output: The same session log and the same options produce byte-identical output, making version control and debugging easier.
  • No stdout interference: The plugin does not write content to standard output, so it can be used alongside the official headless runner without output conflicts.
  • Ecosystem context: The DSH philosophy is “everything is a plugin.” headless- is a community project and has no official affiliation with DeepSeek or High-Flyer.

Summary

headless- addresses insufficient output granularity in DSH under CI environments through a plugin-based approach. It converts session events into structured reports, supports multiple formats from JSON to JUnit, and provides semantic exit codes plus privacy protection mechanisms. It is well suited for agent development scenarios that require strict automated evaluation.

  • Catalog page: https://www.skillhub.cn/plugins/JohnXu22786/headless-
  • Source repository: https://github.com/JohnXu22786/headless-