Preface

After using DSH for a long time, session logs pile up. “How was that error solved last time?” “Where was that configuration version written?” — The answer mostly lies in historical sessions, but the agent itself cannot see them. Manually browsing session files requires dealing with format and compression details; writing a script to scan files yourself means you can’t touch the currently ongoing session.

dsh-session-search-pro takes a different path: instead of directly reading session files, it uses the sessionQuery service built into the harness, encapsulating “search, list, and read sessions” into three agent tools. Below is an introduction to its capabilities, installation methods, and actual performance under the default (stock) configuration.

What is this

dsh-session-search-pro is maintained by LeslieWylie, licensed under MIT, and is currently version 0.2.0. In one sentence: it provides cross-session indexed search for DeepSeek Harness, capable of searching past and current DSH sessions.

A few design points:

  • Zero runtime dependencies: No need for ripgrep, no zstd parsing, no local database.
  • Read-only: Never writes to sessions; does not maintain a database or cache itself.
  • Fails closed: If sessionQuery is completely unavailable, it only logs a warning and does not register any tools — avoiding the situation of mounting a bunch of tools that throw errors the moment they are used.
  • Single Runtime: Only covers a single DSH runtime; does not search codex / claude / pi / opencode or other external sources. If cross-runtime session search is needed, the README compares a direct session file scanning alternative (Tieboyh’s dsh-session-search), which can be chosen as needed.

Three Agent Tools

agent_session_search: Cross-Session Full-Text Search

Performs full-text search across all DSH sessions, with each hit accompanied by the best matching snippet. Parameters:

  • query (required): Text to find. Literal match — regex metacharacters have no special meaning; case-insensitive; whitespace flexible.
  • limit: Maximum number of sessions to return, 1–50. Defaults to the plugin’s maxResults (default 10).
  • maxScan: Maximum number of sessions to open when falling back to scan, 1–500. Defaults to maxScan (default 200), ignored when using the index.

The return value includes an engine: "index" | "scan" field indicating which path this query took; the scan path also includes scanned and truncated. Currently active sessions are also within the search scope.

agent_session_list: List Sessions

Lists past and current sessions. Parameters:

  • limit: Maximum number to return, 1–100, default 20.
  • cwd: Substring filter on session working directories, e.g., to only view sessions under a specific project directory.
  • sort: "newest" or "oldest", default newest.

agent_session_read: Read Session by ID

Reads a single session’s title, metadata, and sequentially ordered events by sessionId. Parameters:

  • sessionId (required): Session ID, e.g., "a4d75296-fc89-44b1".
  • maxEvents: Maximum number of events to return, 1–200, default 50, with the newest first.

Long text in a single event is truncated to 4,000 characters.

Two Search Paths Under Stock Configuration

agent_session_search has two engine paths, automatically selected during invocation.

Index Path: In the stock dsh-base bundle, the specific backend for sessionQuery is @deepseek-ai/dsh-session-query-sqlite, based on SQLite FTS5. If the index is available, the plugin uses it and returns engine: "index".

However, under stock configuration, this backend defaults to openAt: never. In this case, the engine throws SESSION_QUERY_SEARCH_DISABLED. The behavior of this plugin is: accurately catch this error, fall back to scanning sessions one by one prioritizing the newest, and return engine: "scan". If a different error is thrown — the backend is truly broken — report the error directly instead of using a slower scan to try and read from a broken storage.

In terms of performance, the author has tested: index path 17ms, fallback scan 3,042ms. The index is worth enabling, it just cannot be the only path. Versions 0.1.0 and earlier assumed the index always exists; under stock default installation, all queries would return {"error": "session search is disabled…"} — because it didn’t throw an error, it looked like it was working normally. The current version 0.2.0 uses the fallback logic described above. To enable the index, you need to adjust the openAt configuration of session-query-sqlite at the deployment layer; see the plugin README for details.

Installation and Activation

The plugin has not been published to npm and must be installed directly from GitHub. Environment requirements: Node ^22.19.0 || >=24.0.0; peerDependencies are @deepseek-ai/cordis ^4.0.1 and @deepseek-ai/dsh-tools ^0.1.0-rc.6.

Standard installation involves three steps: First, edit the profile’s package.json, add the plugin to dependencies and register it in dsh.profile.bundles; then reinstall dependencies; finally, restart the profile.

// ~/.dsh/profiles/<profile>/package.json
{
  "dependencies": {
    "dsh-session-search-pro": "github:LeslieWylie/dsh-session-search-pro"
  },
  "dsh": {
    "profile": {
      "bundles": ["dsh-session-search-pro"]
    }
  }
}

cd ~/.dsh/profiles/<profile> && pnpm install
dsh --profile <profile>

If you don’t want to track the default branch, you can pin a tag, e.g., github:LeslieWylie/dsh-session-search-pro#v0.1.0. Note: do not pin to 0.1.0 — as mentioned earlier, that version and earlier would cause all queries to return errors under stock configuration.

If you want to try it out without touching the profile configuration: the plugin comes with a cordis.patch.yml. After adding it to node_modules, use the launcher’s --patch to mount and run it once.

cd ~/.dsh/profiles/<profile> && pnpm add github:LeslieWylie/dsh-session-search-pro
dsh --profile <profile> --patch ./node_modules/dsh-session-search-pro/cordis.patch.yml

The plugin configuration is written in the bundle line of cordis.patch.yml, containing only two keys:

  • maxResults: Default 10, the default value when agent_session_search is called without passing limit.
  • maxScan: Default 200, the maximum number of sessions to open during fallback scanning.

After the steps above, restart the profile and the tools are ready to use.

Typical Usage

After the plugin is added to the bundle, the three tools are automatically visible to the agent and do not require manual invocation. Just use natural language:

“Search my past sessions for anything about session search” → agent_session_search
“List my recent sessions in ~/Desktop” → agent_session_list
“Read session a4d75296-fc89-44b1 for me” → agent_session_read

The model will choose the corresponding tool itself.

Use Cases and Notes

Suitable for:

  • Developers who have used DSH for a long time and want the agent to be able to reference past session context.
  • Works even with stock configurations that haven’t enabled the index — fallback scanning ensures search availability, just changing from milliseconds to seconds.
  • Need to search currently active sessions.

Notes:

  • Only covers a single DSH runtime; sessions from external sources like codex / claude / pi / opencode are not within the scope of this plugin.
  • The plugin runs with the permissions of the current dsh process, and the installation source is a GitHub repository rather than npm. Before installing, it is recommended to review the source code and license (MIT) to confirm it is trustworthy before mounting it into the profile.

Summary

dsh-session-search-pro turns “flipping through historical sessions” into an agent tool invocation: if the index is there, use SQLite FTS5; if not, fall back to bounded scanning; stock configuration works out of the box, and if the service is completely unavailable, it prefers not to register the tool rather than giving a broken one.

  • Community Directory Page (independent site, no official affiliation with DeepSeek / Fangfang): https://www.skillhub.cn/plugins/LeslieWylie/dsh-session-search-pro
  • Source Code Repository: https://github.com/LeslieWylie/dsh-session-search-pro