Preface¶

As DSH runs for a long time, the biggest consumer of tokens is often tool results: git status prints dozens of lines, compilation output is drowned in progress noise, and repeated filenames and line numbers from grep appear constantly. Most of this content is not needed by the model, but it consumes context and must be read again on every call.

dsh-rtk is the plugin targeting this layer. It is maintained by wings1848, with package name @wingsbutterfly/dsh-rtk, current version 0.1.2, and an MIT license. It does two things: rewrite the command into a semantic equivalent rtk command before command dispatch; and run a compression pipeline before tool output enters the model context. It is an implementation of the upstream pi-rtk-optimizer ported to the DSH plugin model.

A point to clarify first: dsh-rtk is a plugin wrapped around rtk, not a replacement for rtk. If rtk is not in the PATH, the plugin will stop silently; commands execute as-is, and output is not compressed. Therefore, the installation section below installs rtk first, and then the plugin.

How It Works¶

The README provides a shortest example:

Model emits:  git status
Actually executes:  rtk git status
Model sees:  Branch: main
            Modified: 2 files
              src/a.ts

Rewriting and compression are performed in two separate paths, with slightly different coverage: command rewriting covers three types of shell tools: bash, pwsh, and ops_bash; output compression covers the results of five types of tools: bash, read, grep, ops_bash, and ops_grep.

Core Features¶

Command Rewriting¶

Several key implementation choices, from the README:

• The plugin itself does not carry a rewrite table; during rewriting, it calls rtk rewrite to query the installed binary. The supported scope therefore follows your installed rtk version rather than another list that is prone to becoming outdated.
• Three modes: off (fully off), rewrite (directly replaces the command), and suggest (executes as-is and only reports the equivalent command that could be used).
• Runtime guard: if rtk cannot be confirmed as available, it executes the original command; the absence of the optimizer will not block the workflow.
• Subprocess environment desensitization: variables named *_KEY, *_PASSWORD, *_SECRET, *_TOKEN and DSH_* are not passed to the rtk external call process, while PATH, locale, and proxy settings are retained.
• The rewritten command does not inject RTK_DB_PATH by default; rtk writes to its own user-level library. You can use historyDbPath to pin it to a specific location; relative paths and directories will be rejected.

Output Compression¶

Compression is a multi-stage pipeline:

There are two hard constraints. First, the DSH result contract must survive: tail status markers like [exit code: N], [stderr], [timed out after …], and [sandbox: …] are stripped out first; after the body is rewritten, they are reattached in their original form and guaranteed to be on the last line, and the Web UI also parses this same line to draw the exit status. Second, compression never increases the size of the result: if a technique cannot truly shorten the text, the original text is retained and no savings are reported.

Also, when mounting dsh-spill-policy, the plugin turns off its own hard truncation. The reason is that the plugin’s default 12,000 character threshold is far lower than the spill’s 50,000 byte threshold; since self-truncation runs before spill, the recoverable disk file never gets a chance to be generated. Whether to yield depends solely on whether the service is running; there is no switch.

Configuration Page and Gain Panel¶

On the Web host’s plugin page, the rtk row has its own configuration controls. The page displays daily fields, allows local staged edits, and submits via the host’s settings service; fields that are overridden can be restored item by item. Below the form is the gain panel: 20-grid efficiency bars, raw output / rtk processed / saved and percentage, command count and average duration. You can switch between daily and per-command views and slice by workspace and time window. The data is obtained by the host executing rtk gain -d -f json and sent to the browser via the authenticated precise Fetch route POST /api/dsh-rtk/gain. Deployments without a Web connection will clearly indicate that the ledger is unavailable rather than rendering a broken page.

Installation and Enablement¶

0. Prerequisite: Install rtk binary first¶

When rtk is not found in the PATH, the plugin stops silently; the entire session only adds one line [rtk] rtk not found; rewriting is off, which is easily missed sandwiched in tool output. So, install rtk first:

brew install rtk                        # macOS / Linux (Homebrew, recommended)
winget install rtk-ai.rtk               # Windows
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
cargo install --git https://github.com/rtk-ai/rtk

Do not execute cargo install rtk without --git; the other crate with the same name on crates.io is not this tool.

After installing, verify that it can print the version number:

rtk --version

1. Install Plugin Package¶

dsh plugin --profile web add @wingsbutterfly/dsh-rtk

The plugin declares dsh.bundle, so this command both installs and mounts, and the plugin manager appends the package name to dsh.profile.bundles. After installation, the host must be restarted; profile rows are only mounted at startup.

Version requirements: supports dsh 0.1.5, 0.1.7, 0.2.0, 0.2.1 (tested individually; see docs/verification.md in the repository for evidence); Node ≥ 22.18.

2. Check Configuration¶

All fields are optional; the defaults are as follows:

- id: rtk
  name: '@wingsbutterfly/dsh-rtk'
  config:
    mode: rewrite                    # off | rewrite | suggest
    compact: true                    # whether to compress tool output
    maxChars: 12000                  # character budget (1000–200000)
    readCompaction: none             # none | budget | minimal | aggressive
    rtkExecutable: rtk               # name or absolute path, empty string for auto-detect
    historyDbPath: ''                # '' = rtk's own library; or absolute/~ path, or `isolated`

rtkExecutable is automatically detected: it checks PATH first during loading, and on Windows also checks common installation directories for WinGet, cargo, and Scoop, verifying each candidate with --version. Manually entered values will not be overwritten.

You can also modify settings in real-time in the DSH settings documentation without restarting: dsh 0.1.7 and above have independent setting entries, taking the ID of the combined row; 0.1.5 uses the dsh-rtk namespace. /rtk path will report which layer of configuration the plugin actually sees.

Note the constraint regarding which layer lines are placed in: lines placed in the home directory patch (~/.dsh/cordis.patch.yml) are read-only; online writes will be rejected, and /rtk reset will report accurately. To retain online editing, place the lines inside a combined row of a profile.

Typical Usage¶

Commands inside a session:

• /rtk verify: Checks if rtk is available; if it fails, it prints the installation method directly.
• /rtk stats: Reports how many characters were saved by compression in this session, broken down by tool and by technique.
• /rtk gain [flags]: Shows how many commands rtk actually reclaimed after being rewritten for the plugin.
• /rtk path: Reports the configuration and ledger layer that the plugin actually reads.

A phenomenon verified at runtime (host 0.2.1-rc.2; see docs/verification.md for the record): the model emits ls, which is actually executed as rtk ls; cat is actually executed as rtk read, and the ledger location follows rtk’s own library.

Applicable Scenarios and Precautions¶

Suitable for developers who run a large number of shell tool calls on DSH but are repeatedly blocked by long outputs occupying context. Command rewriting and compression take effect on host plane rows, covering every agent, preset, and sub-agent under that profile, not just a single session. To narrow the scope, use the row’s own switch: mode: off to turn everything off, or mode: suggest to only report without rewriting. If you do not want to override the entire profile, the README also provides a method to wrap it as a normal dependency and manually add the rows to the target preset’s plugin list; in this case, do not mount it duplicate in the bundle.

You should check the source code and license before installing. The plugin runs with the permissions of the current DSH process; it reads environment variables and spawns subprocesses. As mentioned earlier, external calls are desensitized, but this means it can see the commands you execute in this host. Evaluate it with the same standard you use for other third-party plugins in a production environment.

Also, readCompaction is none by default. The reason given in the README is that filtering or truncating read results would make the copy in the model’s hands inconsistent with the disk file, and editing is done against that copy. If you need compression for readability, use minimal, and accept this premise.

Summary¶

The role of dsh-rtk is to integrate rtk’s rewriting and compression into DSH’s tool call path, shortening long output before it enters the model while keeping DSH’s result markers unchanged. It is a thin layer on top of rtk, and its benefits depend on the capabilities of rtk itself.

Directory: https://www.skillhub.cn/plugins/wings1848/dsh-rtk
GitHub: https://github.com/wings1848/dsh-rtk