Preface

The terminal_read tool in DeepSeek Harness (dsh) reads the retained terminal scrollback buffer in pages using offset and count. When backend log output reaches tens of thousands of lines, it is difficult for a model to locate the content of interest through pagination alone, and it can only page backward from the most recent output. The dsh-tool-terminal-search plugin solves this problem with content matching, allowing the model to directly retrieve retained log lines by substring or regular expression.

Introduction

This is a terminal_search tool plugin for DeepSeek Harness (dsh), maintained by ystyle. It belongs to the “online tools” category and is licensed under the MIT license. Instead of modifying the upstream package, this plugin is built on the public ctx.terminals.read interface and aims to help models quickly locate the information they need in large retained logs.

Installation and Enablement

Use the dsh CLI to install the plugin; it forwards the pnpm command to the configuration profile directory. After installation, the dsh profile must be restarted before the model can use the terminal_search tool.

  1. Run the installation command:
dsh plugin --profile web add dsh-tool-terminal-search
  1. Verify the installation:
dsh plugin --profile web ls
  1. Restart your dsh profile. After installation, the model will be able to use the terminal_search tool alongside the official terminal_open, terminal_send, and terminal_read tools.

Prerequisites:
- The official @deepseek-ai/dsh-tool-terminal plugin must be installed.
- You must run the dsh-terminal or dsh-terminal-bash service to support terminal_open, terminal_send, and terminal_read.

Core Functionality

The behavior of terminal_search is as follows:

  • Matching mode: By default, it uses literal substring matching (similar to grep -F), so regular expression metacharacters do not need to be escaped. To use regular expression matching, pass the regex: true parameter.
  • Search scope: The plugin paginates through the entire retained scrollback buffer (from newest to oldest) and matches each line in memory.
  • Return order: Matched lines are returned in reverse chronological order (newest first).
  • Returned data:
    • The content of the matched lines.
    • The offset of each line relative to the newest line, which can be used directly in subsequent terminal_read calls.
    • The exact matchCount (number of matches), totalLines (total retained lines), and truncated (whether truncation occurred) status.
  • Performance mechanism: Compiled regular expressions are stored in a global FIFO cache, so repeated patterns are not recompiled.

Notes

  • Version requirement: This plugin depends on the dsh 0.1.2-alpha.5 release line.
  • Data scope: Search is limited to the retained scrollback buffer of the current process (default retention is 10,000 lines or 4MiB), consistent with the behavior of terminal_read.
  • Truncation handling: If a line read exceeds the backend’s maxReadBytes, the system reduces the page size and retries to ensure accurate line offsets. If a single line exceeds the threshold, that line is truncated and marked as truncated.
  • No context: The plugin returns only the matched lines themselves, not context lines. If context is required, call terminal_read using the offset of a matched line to read adjacent lines.

Ecosystem Context

DeepSeek Harness follows the “everything is a plugin” philosophy. This plugin is maintained by a community developer and is listed in an independent directory; it has no official affiliation with DeepSeek or High-Flyer. The plugin development process includes type checking, unit tests, and packaging builds.