In the debugging workflow of DeepSeek Harness (DSH), users often need to manually switch between the browser console and server logs to locate faults. Existing logs frequently contain a lot of noise, making it difficult to filter out the relevant execution branches. In addition, having agents infer problems from static snapshots typically leads to guessing rather than verification. The DSH Debug Mode plugin addresses this issue by injecting probes at runtime and capturing structured JSONL events, enabling agents to prove failing branches, execute targeted fixes, and clean up diagnostics.

What Is This

dsh-debug-mode is a plugin for DeepSeek Harness that provides runtime evidence for AI debugging. It is maintained by a554878526 and aims to replace manual log collection with structured data capture, making the debugging loop more efficient.

Core Features

  • Structured JSONL event capture: Records evidence as a JSONL stream for easy streaming and grep.
  • Unified evidence: Captures events from browser, Electron, and Node.js environments without manually merging logs.
  • Hypothesis-focused probes: Records 1-3 probes related to a specific hypothesis instead of large amounts of irrelevant data.
  • Integration with the /debug command: Works alongside DSH’s native debug command.
  • Automated cleanup: Provides a Fixed operation to trigger cleanup of probes and logs.
  • Helper scripts: Provides scripts for session generation, event ingestion, log summarization, and lookup utilities.

Installation and Activation

Before installing, ensure that Node.js ^22.19.0 || >=24.0.0, pnpm, and DSH 0.1.0-rc.7 or higher are installed.

Run the following command to add the plugin:

dsh plugin --profile web add "github:a554878526/dsh-debug-mode#main"

After installation, restart dsh web and open a new task to load the plugin.

Typical Usage

  1. Run /debug in DSH and describe the bug you encountered.
  2. Follow the reproduction steps and click Continue. This starts the evidence loop.
  3. After verifying the fix, click Fixed to clean up diagnostic probes and logs.
  4. To manually generate a session and inject events, use the Python helper script:
    python3 scripts/new_debug_session.py --root .
  1. In code, use the __codexDebug function to inject events:
    __codexDebug({
      hypothesisId: "H1",
      location: "SessionStore.ts:restore",
      message: "cache lookup",
      data: { hit: true, entryCount: 3 },
    });

Applicable Scenarios and Notes

This plugin is suitable for scenarios requiring structured debugging across browser, Electron, and Node.js runtimes, especially for UI state, Worker boundaries, asynchronous race conditions, and bugs that cannot be proven from static code.

Notes:
* Dependencies: Requires Node.js ^22.19.0 || >=24.0.0, pnpm, and DSH 0.1.0-rc.7 or higher.
* Process-local state: The current debugging state is process-local. Restarting the DSH Host ends active loops.
* Data privacy: Never log secrets, credentials, or personally identifiable information (PII) in event logs. Count, sample, or truncate instead.
* Version compatibility: debug-mode/state events written by versions 0.1.1 and earlier are incompatible with official DSH builds. If you encounter this issue, inspect and repair the logs.

The tool transforms the debugging process from human log searching to agent-driven remediation by providing a verifiable closed loop of runtime evidence. For more information or to view the source code, visit the GitHub repository.