Preface

In intelligent agent runtime frameworks like DeepSeek Harness (DSH) that follow an “everything-is-a-plugin” philosophy, the bash tool often generates verbose outputs such as build logs, test results, or repository status. dsh-bash-rtk is a DSH bash executor plugin maintained by DeepTrial. It routes eligible shell commands to rtk (Rust Token Killer) for processing, thereby compressing tool output and reducing token consumption. Execution semantics—including working directory, timeout, environment variables, exit codes, and sandbox constraints—remain unchanged.

This document introduces its positioning, capabilities, installation and enabling procedures, typical usage, as well as version and security boundaries.

What It Is

DeepTrial/dsh-bash-rtk is a DSH bash executor plugin.

Its core objective is very specific:

  • Identify eligible shell commands within DSH’s bash executor.
  • Route simple, whitelisted commands to rtk for execution.
  • Pass through unsuitable commands unchanged.
  • Degrade to a no-op passthrough when rtk is unavailable.

Verified basic information is as follows:

  • Maintainer: DeepTrial
  • License: MIT
  • package.json version: 0.1.1
  • Repository URL: https://github.com/DeepTrial/dsh-bash-rtk

Core Features

1. Only Rewrites Eligible Commands

The plugin wraps simple, whitelisted shell commands with rtk. Examples provided include:

  • git status is rewritten to rtk git status
  • cargo build --release is rewritten to rtk cargo build --release

This means the plugin only processes commands it deems safe to wrap, not forcibly rewriting all bash commands.

2. Complex Commands Passed Through Unchanged

When a command contains shell metacharacters, the plugin leaves it unchanged without altering the actual command executed. The example provided is:

git status | grep x

This command remains as:

git status | grep x

The reason is that it is a complex shell command unsuitable for silent rewriting by the plugin.

3. Non-Whitelisted Commands Also Remain Unchanged

The example provided is:

ls -la

This command remains as:

ls -la

The reason is that it is not within the set of commands the plugin considers routable. The complete whitelist is not included in the verified material, so only examples from the README are listed here.

4. Automatic Degradation to Passthrough When rtk Is Unavailable

If rtk is not in PATH, the plugin leaves the command unchanged. The example provided is:

git status

When rtk is missing, it remains as:

git status

This prevents altering the command execution method due to a missing external dependency.

5. Provides Two Executor Variants

The plugin offers:

  • RtkBashExecutor
  • RtkSandboxBashExecutor

It also includes an optional overlay to replace the default sandbox executor, allowing selection of an executor closer to the original execution semantics in different deployment scenarios.

6. Supports Forced Toggling of rtk Wrapping

Configuration option:

rtkAvailable: boolean

This field is used to forcibly enable or disable rtk wrapping. It is suitable for use in testing, non-standard binary path deployments, or scenarios where you explicitly want to bypass/enable rtk.

7. All Peer Dependencies Are Optional

The plugin declares the following optional peer dependencies:

"@deepseek-ai/dsh-bash-local"
"@deepseek-ai/dsh-bash-sandbox"
"@deepseek-ai/dsh-shell"

These dependencies are all marked as optional. If they do not exist, the plugin still runs in passthrough mode without altering the underlying bash execution behavior.

Installation and Enabling

Prerequisites

Before use, the following are required:

  • Node.js >= 20.0.0
  • rtk present in PATH
  • Exit code 0 when running rtk --version

A special note here: The plugin does not bundle, install, pin, or manage rtk. Users must install and update rtk separately. The versions of rtk and the plugin are independent and do not need to correspond one-to-one.

Installing the Plugin

The following command installs the plugin from the latest GitHub release tarball:

dsh plugin --profile web add \
  "https://github.com/DeepTrial/dsh-bash-rtk/releases/latest/download/dsh-bash-rtk-latest.tgz"

After execution, the plugin will be added to the web profile, but it will not take effect immediately.

Enabling the Plugin

The plugin is disabled by default. After installation, it must be enabled in the corresponding profile’s cordis.patch.yml:

- id: bash-rtk
  disabled: false

After enabling, restart or start DSH to apply the configuration:

dsh web

Only after these steps will the plugin enter DSH’s bash execution pipeline.

Typical Usage

The following examples are derived from verified material and can be directly used to understand the plugin’s decision boundaries.

Input Command Parsed Command Reason
git status rtk git status Simple and whitelisted
cargo build --release rtk cargo build --release Simple and whitelisted
git status \| grep x git status \| grep x Complex shell command, passthrough
ls -la ls -la Not in whitelist, passthrough
git status with rtk unavailable git status rtk missing, identity fallback

Think of it as a pre-execution command parsing layer:

  1. First, determine if the command is simple.
  2. Then, determine if the command is within the routable scope.
  3. Finally, determine if rtk is available.
  4. Only when all conditions are met is the command rewritten to rtk <command>.
  5. If any condition is not met, the command executes unchanged.

Configuration and Version Boundaries

rtkAvailable

rtkAvailable is an additional configuration option provided by the plugin to forcibly control rtk wrapping.

Its value type is:

boolean

If you do not rely on auto-detection or need a fixed behavior, you can explicitly set this field.

dsh Version Range

The dsh version range declared in the plugin’s dsh.plugin.json is:

"engines": { "dsh": ">=0.1.0-rc.6 <0.2.0 || >=0.1.1-rc.1 <0.2.0-0" }

This range deliberately excludes 0.2.0+. This means the plugin currently targets the 0.1.x pre-release/build line and is not intended for a potential future 0.2.0+ main line.

Use Cases and Caveats

Suitable For

This plugin is well-suited for the following usage patterns:

  • Using DSH’s bash tool to execute common development commands.
  • Aiming to reduce token consumption from tool output.
  • Preferring a conservative plugin that only affects commands explicitly meeting eligibility criteria.
  • Accepting the need to install and update rtk separately.
  • Reviewing the plugin’s source code, dependencies, and license before enabling.

Points to Note Before Use

  1. The plugin is disabled by default; installing it without enabling it will not change the execution pipeline.
  2. The plugin does not install, pin, or manage rtk.
  3. The versions of rtk and the plugin are independent.
  4. All @deepseek-ai/dsh-* peer dependencies are optional; the plugin will still run in passthrough mode if they are missing.
  5. The dsh version range explicitly excludes 0.2.0+.
  6. The plugin executes commands with the permissions of the current dsh process, so you should review the source code and license before installation.
  7. This document only describes the command whitelist based on verified material; the complete whitelist is not included in the verified material, and it should not be inferred that all commands will or will not pass through rtk.

Conclusion

The value of DeepTrial/dsh-bash-rtk lies in adding a conservative, disableable, passthrough rtk output compression entry point to DSH’s bash execution pipeline. It only processes eligible simple commands, leaving complex commands, non-whitelisted commands, and scenarios with rtk missing unchanged. It is suitable for DSH users who are willing to maintain rtk separately and wish to reduce bash tool output.

Relevant links:

  • GitHub: https://github.com/DeepTrial/dsh-bash-rtk
  • Directory: Can be searched by dsh-bash-rtk in the DSH community directory; the community directory is an independent site with no official affiliation to DeepSeek or High-Flyer, nor is it an official app store.