dsh-rtk
Manifest validCompresses shell output before the model sees it via the local `rtk` CLI: the master switch follows rtk readiness unless set, `prefix` shadows `bash` per agent and asks `rtk rewrite` for an equivalent
dsh-rtk
Compresses bash/pwsh output with the local rtk CLI before it reaches the model: a rewritten command prefix, a post-execute pipe fallback, and a settings card that reports what it saved.
A dsh plugin that puts the local rtk binary between a shell tool and the model. rtk itself stays on your machine; the plugin only orchestrates it.
Contents
- What it does
- Install
- Verify it is live
- What it does not provide
- Enabling it in dsh
- The two shapes
- Settings
- Insights
- Support surface
- External dependency
- Data and privacy
- Known boundaries
- Development
- Feedback
- License
What it does
- Two compression shapes; the master switch follows rtk readiness.
prefixshadowsbashper agent and routes the command throughrtk rewritefirst;pipefeeds a finished shell result throughrtk pipe -f <filter>and replaces only the model-facing text. Until you setenabledexplicitly, it is on only when a supported rtk is detected;prefixis the default form andpipeis opt-in. - Nothing is compressed that is not worth it. Outputs under
minBytes(256) and rewrites that save less thanminGainRatio(0.95) pass through unchanged. The plugin never claims a saving it did not make. - Failures keep their text. The guard rejects any compression that loses the failing assertion, the file:line, or the exit marker — a compressed failure that hides why it failed is worse than no compression.
- The failure count is labelled. rtk's
FAILURES (31):counts output lines, not failing tests — a 15-failure run prints 31. Rather than rewrite a number it has not verified, the plugin adds one line under the header: what the count means, how many failing blocks the input really has, and whether any were folded away. - Fail-open everywhere. rtk missing, rtk too old, a rewrite that rewrites destructively, a command that is not safe to rewrite: the original command runs, the original output is delivered, and nothing is lost.
- Compound commands are rewritten segment by segment.
cd <repo> && cargo test— the shape multi-repo work produces constantly — is split into segments and only the one carrying the output is rewritten (cd <repo> && rtk cargo test). Constructs that cannot be split (command substitution, redirection, background&, unbalanced quotes) still run unchanged as a whole. - A settings card and an insights page. The card keeps the configuration and adds one line of today's summary (per shape) plus a two-bar chart; the full readout lives on an rtk page in the left sidebar — browsable by shape, time window, command and working directory. The data plane is the official Typert Remote namespace; no new HTTP route.
Install
dsh plugin --profile web add @jayyuen66/dsh-rtk
Remove with dsh plugin --profile web remove @jayyuen66/dsh-rtk. The package is on the public npm registry; no credentials, no scoped-registry line.
- Node.js
>= 24.9(ESM-only; that floor is what makesrequire()of an ESM entry work, henceengines.node). - Host
dshat0.2.2-rc.2or later on the0.2.xline. The host readsengines.dsh(^0.2.2-rc.2) and it decides alone — with that field present, compatibility is judged beforepeerDependenciesis ever consulted, prereleases included. Any0.2.xat or above0.2.2-rc.2passes the host gate;0.2.2-rc.1and anything older does not. Strict npm peer resolution likewise accepts nothing below0.2.2-rc.2, and on the prerelease side only the0.2.2tuple (0.2.2-rc.2onward) — a later minor's prerelease such as0.2.3-rc.1waits for its stable release.0.3.0and later need the risk grantdsh plugin --profile <p> allow-version <pkg>@<ver> --dsh-version <exact> --accept-risk. The support window rolls: at publish time this package is checked against every released host version inside the window — the judgement is the host's--dump-configlayer line for this package, while the settings card and its namespace calls are verified once in full on the release's development baseline — and re-verified once the window moves, so the version number in this bullet is not a standing promise. - No
@deepseek-ai/*underdependencies, by contract (test/publish-manifest.test.ts). Profiles install withnodeLinker: hoistedandautoInstallPeers: false, so a host package there becomes a real second copy;@deepseek-ai/dsh-toolskeys its scheduler with a plainSymbol, so every native tool call throws in that profile while build, typecheck and coverage stay green. The@deepseek-ai/dsh*peers carry the same support-window range (^0.2.2-rc.2), while the exact pins indevDependenciesare the compile-time discipline against a second host type surface — not a claim the host consults. rtk >= 1.0.0onPATH. This is the one runtime dependency outside npm:brew install rtkon macOS/Linux,winget install rtk-ai.rtkon Windows. Without it the plugin still loads and every compression path fails open.- What ships:
host.js,client.js, the package-local on-demand chunkclient.insights-echarts.js,cordis.patch.yml,icon.svg, both READMEs,CHANGELOG.md,THIRD_PARTY_NOTICES.md,locale/zh.json+locale/en.json, anddocs/(both DETAIL files). Artifacts are rebuilt byprepack, never committed.
Verify it is live
- The layer is mounted.
dsh --profile web --dump-configends with# == @jayyuen66/dsh-rtkplus- id: rtk. That command is the only accepted signal and is not read-only — read layer lines from stdout and check stderr separately; accept both# == <layer>and# == <layer>, patched by <path>. - rtk is found. The card's readiness line names the binary it resolved and its version.
rtk not foundthere means the host process'sPATHdiffers from your shell's. - A command is compressed. With
enabled: trueand the card's counters at zero, ask the model to run a build or a test suite: the next card refresh shows the call and the byte delta. - The card renders. The settings page lists "rtk 输出压缩" (or its English title); toggling a value plus Save round-trips with a 200 and the dirty state clears.
What it does not provide
- No HTTP route of its own. The card's data plane is the official Typert Remote namespace through the host
/apigateway; auth, Host/DNS-rebinding/Origin checks and body limits are all the gateway's. - No CLI subcommand.
dsh rtk …does not exist. - No rtk code bundled. The plugin invokes the
rtkcommand as a subprocess and consumes its stdout. rtk's Apache-2.0 surface is what it uses; nothing from the BUSL engine is linked or redistributed. - No rewriting of input arguments. dsh deliberately forbids
tools/pre-executefrom rewriting a tool call's arguments (they are already logged and rendered). Theprefixshape therefore works by shadowingbashper agent, not by mutating an existing call. - Required surfaces:
settings/tools/subprocess/workingDirectory(all ininject).spillStore,sandboxPolicyandstorageDomainare read throughctx.get()and degrade gracefully when absent —storageDomainis only consulted once to migrate the old accumulator, so its absence merely costs a slice of historical counters.
Enabling it in dsh
dsh.bundle.patchpoints atcordis.patch.yml, whoseinsert:block carries a- id: dsh-plugin-sharedsupplier row (keep it enabled; disabling it removes the cards' shared component supply) plus the- id: rtkentry withname: "@jayyuen66/dsh-rtk"— the bare package name is what makes the host scan the client half. The card components come from the shared client row, externalized as@jayyuen66/dsh-plugin-shared/client; the host module table providesreact,zodand that shared row.- A missing injected surface keeps cordis from activating the entry (startup diagnostic:
pending (waiting for service: …)); a malformed ctx throwsrequired services … missingfrom apply. - Deployment defaults go on the registration line's
config:; precedence is card runtime value > row config > schema.default(). - The master switch follows rtk readiness. Until you set
enabledexplicitly, it stays off when rtk is missing or below the supported floor and turns on once a supported rtk is detected.prefixis the default form. Turn the switch off manually to pin it off, or on to pin it on; both the switch and the form selector take effect on the next tool call.
The two shapes
| prefix | pipe | |
|---|---|---|
| When | before the command runs | after the shell result exists |
| How | shadow bash per agent, ask rtk rewrite, run the rewritten form | feed captured stdout through rtk pipe -f <filter> |
| What the model sees | the compressed output of the rewritten command | the compressed output, original markers and exit code preserved |
| Failure mode | rewrite rejected → original command runs | filter unusable → original text delivered |
| Compound commands | rewritten segment by segment: only the output-bearing segment changes | the whole command's output is compressed together |
| Default | on when enabled is on | off (waiting for rtk to cover more shapes) |
Compound handling under prefix deserves its own paragraph: rtk already rewrites segment by segment (rewrite_compound in discover/registry.rs), and cd /tmp && cargo test measurably becomes cd /tmp && rtk cargo test. The plugin splits both the original command and the product into segments, requires the separator sequence to match one for one, and runs P1–P4 on each segment (a segment that was not touched must be byte-identical; the touched one may only gain a leading rtk ). Anything else is rejected and the original command runs.
Settings
| Key | Default | Meaning |
|---|---|---|
enabled | unset | master switch; until set, on only when a supported rtk is detected |
enabledForms | ['prefix'] | which shapes may act; takes effect on the next tool call |
denyCommands | [] | extra command patterns never rewritten |
enabledFilters | ['git-log','git-diff','git-status','grep','find','vitest'] | pipe filters that may act. git-log/git-diff/git-status/grep/find are the ones command rewriting still hands back in some shapes, so filtering is the only chance left. vitest covers vitest run and the pnpm test/npm test/yarn test forms that rtk cannot rewrite (its rules require an explicit run); that path does not call rtk at all — the plugin drops the passing lines itself (✓), because rtk's vitest parser yields nothing usable on vitest 5. cargo-test/pytest/ctest stay off by default: they get rewritten to rtk <cmd>, so filtering them again would only hit "already rewritten" |
minBytes | 256 | outputs smaller than this are never compressed |
minGainRatio | 0.95 | a compression that keeps ≥95% of the bytes is discarded |
stdoutCapBytes | 64000 | cap on what the filter returns: the compressed body is tail-truncated to this many bytes (the exit marker is kept) |
warnHint | true | append the compile-warning hint after cargo test |
rewriteHostEnv | '' | value for RTK_REWRITE_HOST; empty leaves it unset |
pipeTimeoutMs | 3000 | restart-only |
rewriteTimeoutMs | 2000 | restart-only |
rewriteCacheSize | 256 | restart-only |
vitestMaxMajor | 5 | restart-only; command rewriting skips vitest at or above this major (enabledFilters' vitest path is unaffected — it never calls rtk, so no version gate applies there) |
logFilterMode | 'off' | restart-only |
The config schema has 14 fields; 13 of them carry built-in defaults, while enabled follows rtk readiness until you set it explicitly. 9 of them volatile — the settings card writes those and they take effect on the next tool call, enabledForms included. The remaining non-volatile deployment values, 5 of them, are read once at assembly, so changing them needs a restart.
Insights
The left sidebar gains an rtk page. The two shapes are reported separately and never merged: prefix reports how many commands were rewritten and how many tokens that saved; pipe reports how many outputs were compressed and how many tokens that saved. They are not the same quantity, and one blended savings rate would explain neither.
- Tabs: rewrite (prefix) / compression (pipe).
- Window and granularity: 7 / 30 / 90 days, day / week / month. Empty buckets inside the window are zero-filled, so the x-axis is a stable time axis rather than "the days that happened to have data".
- KPI row: calls, attempts, successes, coverage (pipe) or success rate (prefix), tokens saved, savings rate.
- Combination chart: bars are tokens saved per bucket, the line is the savings or coverage rate on a second axis. Under three days it falls back to bars — a line through two points is not a trend, it is a misreading.
- Why this one was not compressed: the latest event plus the top reasons in the window.
- Detail tables: prefix by the command families of the segments that were actually rewritten, plus working directory; pipe by filter, command family and working directory. A compound command only counts the segments that really got the
rtkprefix — rtk's own ledger is one row per segment, socd x && rtk git diff && rtk cargo testlands as two rows (git diff,cargo test) andcd xhas none. - Suggestions: low-yield filters, enabled-but-never-hit filters, disabled-but-clearly-compressible filters, low-yield command families.
- Data note: the start date, and the concrete reason when a ledger cannot be read (read-only sandbox, missing database, unreadable file, unexpected shape).
Charts use Apache ECharts 6.1, loaded on demand: it is not in the entry bundle at all, and only opening this page downloads the half-megabyte charting code as a package-local chunk (client.insights-echarts.js, pulled by the host through require.async; switching tabs does not download it twice). The two-bar chart on the settings card shares the same chunk. License and copyright notices are in THIRD_PARTY_NOTICES.md.
Support surface
engines.dsh and the @deepseek-ai/dsh* peers are ^0.2.2-rc.2 (one line, no union); @deepseek-ai/schemastery peer is ^3.19.0; engines.node is >=24.9.0.
External dependency
rtk 1.2.0 was the version every claim in this repository was measured against. The plugin requires >= 1.0.0; below that it reports the version it found and does nothing.
Data and privacy
- Command text leaves the host process only as an argv to your own
rtkbinary. No network call is made by this plugin. - One dataset, and only dsh sessions land in it. The ledger lives in dsh's own directory:
$DSH_HOME/rtk/history.db(default~/.dsh/rtk/history.db, with$DSH_HOMEresolved the same way the host resolves it). The plugin prefixes every rewrittenrtksegment withRTK_DB_PATHpointing at that file, so rtk books its rows there and nowhere else — the rtk you run in your own terminal, andrtk gain, are neither affected nor counted here. Pipe compression counters and the per-event detail of both shapes live indsh_*tables in the same database (SQLite vianode:sqlite; if it cannot be opened only the statistics are lost, compression is unaffected). rtk never reads those tables and never drops them; kept for 90 days, no lifetime total. - The plugin's own tables and the page never store full commands, arguments or output. Only the command family (a template-level name like
cargo testorgit status), the working directory, the filter name, the reason and the counters. rtk's tables in that ledger do holdoriginal_cmd; the plugin only reads it, and only ever shows its command family — the raw text never reaches the page or the statistics. - Tokens are estimated by the host's
tokenMeter(falling back tobytes / 4when the service is absent — the same density as rtk's ownestimate_tokens_from_len). The pipe form measures both ends, so its saving is measured; what prefix saves is the book rtk keeps for "original vs rewritten command", which the plugin only reads rather than estimates itself. - The three sandbox modes differ. Under
read-onlythe prefix savings cannot be read (the ledger is not writable, so the page says so plainly while the rewrite counters stay visible) and pipe statistics keep working; underworkspace-writethe plugin registers$DSH_HOME/rtk/as a session-scoped writable root (through its physical path, so a symlinked/tmpstill lands) and both faces work normally;danger-full-accessadds no further restriction. - "Clear" sits behind a confirmation and empties both sides of dsh's ledger: rtk's five tables (
commandsand its siblings, deleted the same wayrtk gain --resetdeletes them) plus the plugin's owndsh_*tables. Only$DSH_HOME/rtk/history.dbis touched — your globalrtk gainhistory stays put, which is exactly what the checkbox in the dialog says. The old single accumulator (thertk_statsstorage domain) is migrated once into a snapshot the first time it is opened, and never accumulates again. - Compressed originals can be spilled into the host's spill area when they exceed the inline budget — the same mechanism every other host tool uses, with the same per-session partition.
Known boundaries
rtk rewritedoes not know whether a flag asks for more detail. It rewritescargo test -- --nocaptureandpytest -vvjust like the quiet form, and the detail is then compressed away. The plugin refuses to rewrite any command carrying a detail flag; when it does compress, the loss is bounded by the guard, not by rtk.npm run <script>is never rewritten. rtk maps a script name to a tool name (npm run lint→rtk lint), which would run ESLint instead of your script. The plugin drops any rewrite that removes a word from the original command.- Listing commands fold.
ls,find,grep/rgcan replace a long listing with a+N moremarker; the guard detects the marker family and rejects the compression, so folded listings never reach the model through this plugin. - Approvals see the command you asked for, not the rewritten one. The shadow rewrites
args.commandinsideexecute, which runs after the pipeline'stools/pre-executestage. General command approval (auto-review, danger-guard, Claude-Code-style hooks) therefore evaluates the frozen original arguments (cargo test) while the rewritten form (rtk cargo test) is what actually runs. Sandbox escalation approval is insideorig.executeand is preserved untouched, because the plugin never spawns the command itself. The plugin's own safety net in front of that gap is three subtractions — the deny table (onlyaws, where rewriting changes the exit code: a missingawsgives 127 natively and 1 through rtk), the P1–P4 rewrite checks (only a prefix may be stripped, no script-runner word may disappear), and the vitest major gate. Danger commands (rm -rf,git push --force) are not in rtk's rewrite surface at all, so they run unchanged and are reviewed unchanged — danger-guard is not bypassed. - A segment that fails the gate is restored, the rest still gets rewritten.
cd x && aws s3 ls && cargo testbecomescd x && aws s3 ls && rtk cargo test: rtk rewrites every segment it recognizes, so the plugin puts the gated ones back verbatim instead of handing the whole line back. The gate is evaluated per segment, becausecd x && git diffstarts withcd— evaluating the whole string would disable the entire table. What the gate no longer does is refuse a command because its output would merely get shorter:git diff/git log/ls/find/grepare rewritten like anything else, and the compression shapes own the "output got shorter" question. rtk pipeon a failing pytest run keeps the failure names but not always the assertion body. The guard checks for a success claim and for the failing line; a filter output that passes both but still loses detail is a known limit of the filter, not of the guard. The vitest path avoids that limit by not calling rtk at all (seeenabledFiltersabove).
Development
pnpm install --ignore-scripts
pnpm run check # typecheck + lint + build + test + fmt:check
pnpm run smoke @jayyuen66/dsh-rtk from the umbrella workspace mounts the package into a sandbox DSH_HOME; the accepted signal is the --dump-config layer line.
Feedback
Issues and pull requests are welcome: https://github.com/JayYuen666/dsh-rtk/issues.
If a plugin fails to boot, include the dsh host version, the profile install shape, and the browser console line. The missed the module table line is especially useful: it tells us whether the shared client row was materialized.
License
MIT for this plugin. rtk is Apache-2.0 for the CLI and command filters this plugin uses; see THIRD_PARTY_NOTICES.md.
Comments
Loading…
Similar plugins
by paranoidPhantom
Simple dsh router for rust token killer.
★ 1
JavaScript
Nov 8, 2026
dsh plugin --profile web add dsh-rtk-minimalRewrites pwsh and bash tool commands through `rtk rewrite` and executes the compact equivalent; falls back to the original command when rtk is missing or has no equivalent, and ships a checksum-verifi
★ 0
dsh plugin --profile web add dsh-rtk-bridgeby better-er
dsh·远程文件系统插件。给模型提供 read_remote、write_remote、edit_remote 三个工具,经 ssh 读写远程主机文件,不用再在 PowerShell 里套 bash 命令;write_remote 只允许新建。纯插件自包含,不改 DSH 源码。
★ 2
↓ 385/wk
MIT
TypeScript
Nov 14, 2026
dsh plugin --profile web add dsh-remote-file-systemby CARVIN94
该仓库暂未提供项目说明。
★ 3
↓ 268/wk
MIT
TypeScript
Oct 28, 2026
dsh plugin --profile web add dsh-router-ext-rtkby Kaiji-Z
An RTS-style orchestration dashboard where commands replace chats: a resident commander agent decomposes each order into task briefs with acceptance criteria, typed subagent troops (recon/engineer/med
★ 3
↓ 534/wk
MIT
TypeScript
Nov 12, 2026
dsh plugin --profile web add dsh-plugin-stardeckTurns a one-line DSH draft into a complete task brief (role / goal / constraints / output format). The engine is a byte-verified port of linshenkx/prompt-optimizer (three modes, 10 templates identical
★ 0
dsh plugin --profile web add @benrong/dsh-prompt-polish