opencode-rtk-plugin 0.1.0-beta.7

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,95 @@
+// 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 (https://github.com/rtk-ai/rtk)
+
+import { execFile } from "node:child_process";
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const MAX_TIMEOUT_MS = 600_000;
+
+/**
+ * Run `rtk rewrite <command>` and resolve to the rewritten command, or null.
+ *
+ * rtk signals the result on STDOUT, not via exit status: since v0.34.0
+ * `rtk rewrite` exits 3 with the rewritten command on stdout (its
+ * permission-verdict protocol). So the exit code must be ignored and the
+ * decision made on stdout alone.
+ *
+ * Never rejects and never hangs: a spawn failure, timeout, or empty/unchanged
+ * output resolves to null so the original command runs.
+ */
+function rewriteCommand(binary, command, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer;
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(value);
+    };
+
+    let child;
+    try {
+      // timeout: 0 disables execFile's own SIGTERM-only timeout; we enforce a
+      // hard SIGKILL deadline below so a SIGTERM-ignoring rtk cannot hang.
+      child = execFile(
+        binary,
+        ["rewrite", command],
+        { timeout: 0, encoding: "utf8" },
+        (_err, stdout) => {
+          const out = String(stdout ?? "").trim();
+          done(out && out !== command ? out : null);
+        }
+      );
+    } catch {
+      return done(null);
+    }
+
+    child.on("error", () => done(null));
+
+    timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+      done(null);
+    }, timeoutMs + 250);
+  });
+}
+
+function resolveBinary(value) {
+  return typeof value === "string" && value.trim() !== "" ? value : "rtk";
+}
+
+function resolveTimeout(value) {
+  if (Number.isInteger(value) && value >= 1 && value <= MAX_TIMEOUT_MS) return value;
+  return DEFAULT_TIMEOUT_MS;
+}
+
+export default {
+  id: "rtk",
+
+  async setup(ctx) {
+    const options = ctx.options ?? {};
+    if (options.enabled === false) return;
+
+    const binary = resolveBinary(options.binary);
+    const timeoutMs = resolveTimeout(options.timeoutMs);
+
+    await ctx.shell.hook("create.before", async (event) => {
+      try {
+        if (!event || typeof event.command !== "string" || !event.command) return;
+        const rewritten = await rewriteCommand(binary, event.command, timeoutMs);
+        if (rewritten) event.command = rewritten;
+      } catch {
+        // Never fail the shell call: any error leaves the command unchanged.
+      }
+    });
+  },
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "opencode-rtk-plugin",
+  "version": "0.1.0-beta.7",
+  "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 --test test/*.test.mjs",
+    "check": "npm run lint && npm test"
+  },
+  "devDependencies": {
+    "markdownlint-cli2": "^0.23.0"
+  }
+}