opencode-rtk-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nabheet S. Sandhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# opencode-rtk-plugin
+
+> An [OpenCode](https://opencode.ai) **v2** plugin that routes every shell
+> command through [`rtk`](https://github.com/rtk-ai/rtk), cutting LLM token
+> usage by **60-90%** on common dev commands.
+
+OpenCode sends tool output back to the model. `rtk` compresses that output
+(git, grep, ls, test runners, build logs, and more) into a token-efficient
+form before the model ever sees it. This plugin wires the two together.
+
+## Why
+
+- **Smaller context, lower cost.** Command output is the biggest hidden token
+  sink in an agent loop.
+- **No prompt changes.** Rewriting happens in the shell hook, transparently.
+- **Single source of truth.** All rewrite rules live in `rtk rewrite`; this
+  plugin is a thin delegating adapter, so rules never drift.
+
+## Requirements
+
+- OpenCode **v2** (`opencode --version` reports 2.x).
+- `rtk` >= 0.23.0 on `PATH` — see [rtk-ai/rtk](https://github.com/rtk-ai/rtk):
+  `brew install rtk`
+
+## Install
+
+### From npm
+
+```bash
+opencode plugin add opencode-rtk-plugin
+```
+
+### From GitHub
+
+```bash
+opencode plugin add github:nabheet/opencode-rtk-plugin
+```
+
+Or add it to `opencode.json(c)` directly:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-rtk-plugin"]
+}
+```
+
+### Manual
+
+Copy this directory to `.opencode/plugins/opencode-rtk-plugin/` (project) or
+`~/.config/opencode/plugins/opencode-rtk-plugin/` (global), then list it:
+
+```jsonc
+{
+  "plugins": [{ "package": "./.opencode/plugins/opencode-rtk-plugin" }]
+}
+```
+
+## Options
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-rtk-plugin",
+      "options": {
+        "binary": "rtk",
+        "timeoutMs": 5000,
+        "enabled": true
+      }
+    }
+  ]
+}
+```
+
+| Option      | Default | Description                          |
+| ----------- | ------- | ------------------------------------ |
+| `binary`    | `"rtk"` | Path or name of the rtk executable.  |
+| `timeoutMs` | `5000`  | Per-rewrite timeout in milliseconds. |
+| `enabled`   | `true`  | Set `false` to disable the plugin.   |
+
+## How it works
+
+The plugin registers one OpenCode v2 shell hook:
+
+```js
+ctx.shell.hook("create.before", (event) => {
+  // event.command is the command about to run; mutate it to rewrite
+})
+```
+
+For each shell command it runs `rtk rewrite <command>` and replaces the command
+with rtk's output when it differs. If `rtk` is missing, times out, or errors,
+the original command runs unchanged.
+
+## Compatibility
+
+- Targets **OpenCode v2** (`plugins` config + `id`/`setup` plugin definition).
+  OpenCode v1 used a different plugin API and is not supported.
+- `rtk` ships hooks for Claude Code, Codex, Cursor, Gemini CLI, Copilot and
+  others. OpenCode is not among them, so this plugin fills that gap.
+
+## Prereleases
+
+Every push to a PR publishes an installable beta to the npm `beta` dist-tag:
+
+```bash
+opencode plugin add opencode-rtk-plugin@beta
+```
+
+## Releases (maintainers)
+
+All publishing happens in GitHub Actions via npm **trusted publishing** (OIDC
+provenance). Never publish from a local shell.
+
+`.github/workflows/ci.yml` is the single workflow file (npm allows one trusted
+publisher per package; the workflow filename must stay `ci.yml`):
+
+- `test` — lint + plugin-export smoke check on `main` and PRs (Node 24).
+- push to `main` → `publish` job publishes the next patch to `latest`, pushes a
+  `vX.Y.Z` tag, and opens a GitHub release. The version is derived from the
+  last published `latest`, so repeated merges never collide; an intentional
+  minor/major bump in `package.json` is honored.
+- tag `v*-beta*` → `publish` job publishes `beta` + a prerelease GitHub release.
+- every PR push → `prerelease` job publishes `<version>-beta.<run_number>` to
+  `beta` (same-repo, non-draft, non-dependabot PRs; re-runs deduped).
+- manual dispatch → next `-beta.X` staging publish from `main`, no git change.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). `rtk` itself is Apache-2.0 and is **not**
+bundled or vendored here.

package/index.js

@@ -0,0 +1,45 @@
+// opencode-rtk — OpenCode v2 plugin
+//
+// Rewrites shell commands through `rtk rewrite` so command output reaches the
+// model in a token-efficient form. All rewrite logic lives in rtk itself; this
+// plugin is a thin delegating adapter for OpenCode's shell hook.
+//
+// Requires: rtk >= 0.23.0 on PATH (https://github.com/rtk-ai/rtk)
+
+import { execFile } from "node:child_process";
+
+/** Run `rtk rewrite <command>`; resolve to the rewritten command or null. */
+function rewriteCommand(binary, command, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = execFile(
+      binary,
+      ["rewrite", command],
+      { timeout: timeoutMs },
+      (err, stdout) => {
+        if (err) return resolve(null);
+        const rewritten = String(stdout).trim();
+        resolve(rewritten && rewritten !== command ? rewritten : null);
+      }
+    );
+    // execFile can emit before the callback; never let it surface.
+    child.on("error", () => resolve(null));
+  });
+}
+
+export default {
+  id: "rtk",
+
+  async setup(ctx) {
+    const options = ctx.options ?? {};
+    if (options.enabled === false) return;
+
+    const binary = typeof options.binary === "string" ? options.binary : "rtk";
+    const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 5000;
+
+    await ctx.shell.hook("create.before", async (event) => {
+      if (!event || typeof event.command !== "string" || !event.command) return;
+      const rewritten = await rewriteCommand(binary, event.command, timeoutMs);
+      if (rewritten) event.command = rewritten;
+    });
+  },
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "opencode-rtk-plugin",
+  "version": "0.1.0",
+  "description": "OpenCode v2 plugin that rewrites shell commands through rtk to cut LLM token usage by 60-90%.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "opencode-v2",
+    "rtk",
+    "token-optimization",
+    "token-savings",
+    "llm",
+    "ai-coding-agent",
+    "context-window",
+    "shell"
+  ],
+  "license": "MIT",
+  "author": "Nabheet S. Sandhu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nabheet/opencode-rtk-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nabheet/opencode-rtk-plugin/issues"
+  },
+  "homepage": "https://github.com/nabheet/opencode-rtk-plugin#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "markdownlint-cli2 \"**/*.md\"",
+    "test": "node --check index.js && node -e \"import('./index.js').then(m => { if (!m.default?.id || typeof m.default.setup !== 'function') { console.error('invalid plugin export'); process.exit(1) } console.log('plugin id:', m.default.id) })\"",
+    "check": "npm run lint && npm test"
+  },
+  "devDependencies": {
+    "markdownlint-cli2": "^0.23.0"
+  }
+}