opencode-matrixx 2.3.0 → 2.4.0

package/README.md

@@ -401,6 +401,82 @@ Sentinel never modifies code — it reports findings with CWE IDs, exact locatio
 
 ---
 
+## RTK Integration — Token Compression
+
+Matrixx integrates [RTK](https://github.com/rtk-ai/rtk) for automatic bash command compression, reducing LLM token consumption by **60-90%** on tool outputs.
+
+### What is RTK?
+
+RTK is a Rust CLI binary that intelligently rewrites bash commands to compress their output before it reaches the LLM. It recognizes 70+ command patterns (git, npm, cargo, test runners, linters, build tools) and applies smart filtering, grouping, and deduplication strategies.
+
+```
+# Without RTK: 2000 tokens
+$ git status
+On branch main
+Changes not staged for commit:
+  modified:   src/config.ts
+  modified:   src/hooks/index.ts
+  ... (50 more lines)
+
+# With RTK: 200 tokens
+$ rtk git status
+2 files changed: src/config.ts, src/hooks/index.ts
+```
+
+### How It Works
+
+The RTK hook intercepts bash commands **before execution** and rewrites them to use RTK's compression:
+
+1. LLM requests: `git status`
+2. RTK hook rewrites to: `rtk git status`
+3. RTK binary executes and compresses output
+4. Compressed output (60-90% smaller) reaches the LLM
+
+The hook runs **silently** — no configuration needed beyond enabling it. RTK's pattern matching handles the rest.
+
+### Configuration
+
+RTK is **disabled by default** (opt-in). Enable it in `matrixx.jsonc`:
+
+```jsonc
+{
+  "rtk": {
+    "enabled": true,
+    "binary_path": "/usr/local/bin/rtk",  // optional — defaults to "rtk" in PATH
+    "timeout_ms": 5000                     // optional — subprocess timeout
+  }
+}
+```
+
+### Installation
+
+Install RTK from [rtk-ai/rtk](https://github.com/rtk-ai/rtk):
+
+```bash
+# macOS
+brew install rtk-ai/tap/rtk
+
+# Linux (curl)
+curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/main/install.sh | bash
+
+# Verify installation
+rtk --version
+```
+
+### Performance Impact
+
+| Metric | Value |
+|--------|-------|
+| **Overhead** | ~10-20ms per bash command |
+| **Token savings** | 60-90% reduction on compressed commands |
+| **Net benefit** | Significant for projects with frequent bash commands |
+
+The 10-20ms subprocess overhead is negligible compared to command execution time and LLM context savings.
+
+
+---
+
+
 ## Documentation
 
 | | |

package/dist/config/schema/hooks.d.ts

@@ -56,5 +56,6 @@ export declare const HookNameSchema: z.ZodEnum<{
     "tool-pair-validator": "tool-pair-validator";
     "task-notepad": "task-notepad";
     "design-intent-preserver": "design-intent-preserver";
+    "rtk-bash-rewriter": "rtk-bash-rewriter";
 }>;
 export type HookName = z.infer<typeof HookNameSchema>;

package/dist/config/schema/matrixx-config.d.ts

@@ -124,6 +124,7 @@ export declare const MatrixxConfigSchema: z.ZodObject<{
         "tool-pair-validator": "tool-pair-validator";
         "task-notepad": "task-notepad";
         "design-intent-preserver": "design-intent-preserver";
+        "rtk-bash-rewriter": "rtk-bash-rewriter";
     }>>>;
     disabled_commands: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         "bdd-contract": "bdd-contract";
@@ -1824,6 +1825,11 @@ export declare const MatrixxConfigSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         proactive: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
+    rtk: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        binary_path: z.ZodOptional<z.ZodString>;
+        timeout_ms: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     _migrations: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type MatrixxConfig = z.infer<typeof MatrixxConfigSchema>;

package/dist/config/schema/rtk.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export declare const RtkConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    binary_path: z.ZodOptional<z.ZodString>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type RtkConfig = z.infer<typeof RtkConfigSchema>;

package/dist/config/schema.d.ts

@@ -20,6 +20,7 @@ export * from "./schema/model-capabilities";
 export * from "./schema/morpheus";
 export * from "./schema/morpheus-agent";
 export * from "./schema/notification";
+export * from "./schema/rtk";
 export * from "./schema/runtime-fallback";
 export * from "./schema/security";
 export * from "./schema/skills";

package/dist/create-hooks.d.ts

@@ -68,4 +68,5 @@ export declare function createHooks(args: {
     taskResumeInfo: ReturnType<typeof import("./hooks").createTaskResumeInfoHook>;
     anthropicEffort: ReturnType<typeof import("./hooks/anthropic-effort").createAnthropicEffortHook> | null;
     runtimeFallback: ReturnType<typeof import("./hooks").createRuntimeFallbackHook> | null;
+    rtkBashRewriter: ReturnType<typeof import("./hooks").createRtkBashRewriterHook> | null;
 };

package/dist/hooks/index.d.ts

@@ -32,6 +32,7 @@ export { createOracleMdOnlyHook } from "./prometheus-md-only";
 export { createQualityGateHook } from "./quality-gate/hook";
 export { createQuestionLabelTruncatorHook } from "./question-label-truncator";
 export { createReadImageResizerHook } from "./read-image-resizer";
+export { createRtkBashRewriterHook } from "./rtk-bash-rewriter";
 export { createRulesInjectorHook } from "./rules-injector";
 export { createRuntimeFallbackHook, type RuntimeFallbackHook, type RuntimeFallbackOptions, SessionCategoryRegistry } from "./runtime-fallback";
 export { createSecretLeakGuardHook } from "./secret-leak-guard";

package/dist/hooks/rtk-bash-rewriter/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const RTK_BINARY_NAME = "rtk";
+export declare const DEFAULT_TIMEOUT_MS = 5000;
+export declare const RTK_REWRITE_COMMAND = "rewrite";

package/dist/hooks/rtk-bash-rewriter/hook.d.ts

@@ -0,0 +1,12 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { MatrixxConfig } from "../../config";
+export declare function createRtkBashRewriterHook(_ctx: PluginInput, config: MatrixxConfig): {
+    "tool.execute.before": (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        args: Record<string, unknown>;
+        message?: string;
+    }) => Promise<void>;
+};

package/dist/hooks/rtk-bash-rewriter/hook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/rtk-bash-rewriter/index.d.ts

@@ -0,0 +1 @@
+export { createRtkBashRewriterHook } from "./hook";

package/dist/hooks/rtk-bash-rewriter/types.d.ts

@@ -0,0 +1,11 @@
+export interface RtkRewriteResult {
+    success: boolean;
+    rewrittenCommand?: string;
+    exitCode: number;
+    error?: string;
+}
+export interface RtkBinaryStatus {
+    available: boolean;
+    path: string | null;
+    checkedAt: number;
+}

package/dist/index.js

@@ -67770,6 +67770,53 @@ function createReadImageResizerHook(_ctx) {
     }
   };
 }
+// src/hooks/rtk-bash-rewriter/constants.ts
+var RTK_BINARY_NAME = "rtk";
+var DEFAULT_TIMEOUT_MS = 5000;
+var RTK_REWRITE_COMMAND = "rewrite";
+
+// src/hooks/rtk-bash-rewriter/hook.ts
+function createRtkBashRewriterHook(_ctx, config2) {
+  const rtkConfig = config2.rtk;
+  const _timeoutMs = rtkConfig?.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+  const binaryPath = rtkConfig?.binary_path ?? RTK_BINARY_NAME;
+  const hasRtk = Bun.which(binaryPath) !== null;
+  if (!hasRtk) {
+    log(`[rtk-bash-rewriter] rtk binary not found at '${binaryPath}'. Hook will pass through all commands.`);
+  }
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool.toLowerCase() !== "bash") {
+        return;
+      }
+      if (!hasRtk) {
+        return;
+      }
+      const command = output.args.command;
+      if (!command) {
+        return;
+      }
+      try {
+        const proc = Bun.spawn([binaryPath, RTK_REWRITE_COMMAND, command], {
+          stdout: "pipe",
+          stderr: "pipe"
+        });
+        const exitCode = await proc.exited;
+        if (exitCode !== 0 && exitCode !== 3) {
+          return;
+        }
+        const rewritten = await new Response(proc.stdout).text();
+        const trimmed = rewritten.trim();
+        if (trimmed && trimmed !== command) {
+          output.args.command = trimmed;
+          log(`[rtk-bash-rewriter] Rewrote command: '${command}' \u2192 '${trimmed}'`);
+        }
+      } catch (error51) {
+        log(`[rtk-bash-rewriter] Rewrite failed: ${error51}`);
+      }
+    }
+  };
+}
 // src/hooks/rules-injector/project-root-finder.ts
 import { existsSync as existsSync38, statSync as statSync4 } from "fs";
 import { dirname as dirname13, join as join50 } from "path";
@@ -72374,7 +72421,7 @@ This is a reminder only. No automatic action was taken.`;
 // src/hooks/unstable-agent-babysitter/unstable-agent-babysitter-hook.ts
 init_logger();
 var HOOK_NAME15 = "unstable-agent-babysitter";
-var DEFAULT_TIMEOUT_MS = 120000;
+var DEFAULT_TIMEOUT_MS2 = 120000;
 var COOLDOWN_MS = 5 * 60 * 1000;
 async function resolveMainSessionTarget(ctx, sessionID) {
   let agent = getSessionAgent(sessionID);
@@ -72445,7 +72492,7 @@ function createUnstableAgentBabysitterHook(ctx, options) {
     const tasks = options.backgroundManager.getTasksByParentSession(mainSessionID);
     if (tasks.length === 0)
       return;
-    const timeoutMs = options.config?.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+    const timeoutMs = options.config?.timeout_ms ?? DEFAULT_TIMEOUT_MS2;
     const now = Date.now();
     for (const task of tasks) {
       if (task.status !== "running")
@@ -86836,7 +86883,7 @@ var CLI_LANGUAGES = [
   "tsx",
   "yaml"
 ];
-var DEFAULT_TIMEOUT_MS2 = 300000;
+var DEFAULT_TIMEOUT_MS3 = 300000;
 var DEFAULT_MAX_OUTPUT_BYTES = 1 * 1024 * 1024;
 var DEFAULT_MAX_MATCHES = 500;
 
@@ -87131,7 +87178,7 @@ async function runSg(options) {
       };
     }
   }
-  const timeout = DEFAULT_TIMEOUT_MS2;
+  const timeout = DEFAULT_TIMEOUT_MS3;
   const proc = spawn9([cliPath, ...args], {
     stdout: "pipe",
     stderr: "pipe"
@@ -89582,7 +89629,7 @@ var DEFAULT_MAX_DEPTH = 20;
 var DEFAULT_MAX_FILESIZE = "10M";
 var DEFAULT_MAX_COUNT = 500;
 var DEFAULT_MAX_COLUMNS = 1000;
-var DEFAULT_TIMEOUT_MS3 = 300000;
+var DEFAULT_TIMEOUT_MS4 = 300000;
 var DEFAULT_MAX_OUTPUT_BYTES2 = 10 * 1024 * 1024;
 var RG_SAFETY_FLAGS = [
   "--no-follow",
@@ -89594,7 +89641,7 @@ var RG_SAFETY_FLAGS = [
 var GREP_SAFETY_FLAGS = ["-n", "-H", "--color=never"];
 
 // src/tools/glob/constants.ts
-var DEFAULT_TIMEOUT_MS4 = 60000;
+var DEFAULT_TIMEOUT_MS5 = 60000;
 var DEFAULT_LIMIT = 100;
 var DEFAULT_MAX_DEPTH2 = 20;
 var DEFAULT_MAX_OUTPUT_BYTES3 = 10 * 1024 * 1024;
@@ -89657,7 +89704,7 @@ async function getFileMtime(filePath) {
 }
 async function runRgFiles(options, resolvedCli) {
   const cli = resolvedCli ?? resolveGrepCli();
-  const timeout = Math.min(options.timeout ?? DEFAULT_TIMEOUT_MS4, DEFAULT_TIMEOUT_MS4);
+  const timeout = Math.min(options.timeout ?? DEFAULT_TIMEOUT_MS5, DEFAULT_TIMEOUT_MS5);
   const limit = Math.min(options.limit ?? DEFAULT_LIMIT, DEFAULT_LIMIT);
   const isRg = cli.backend === "rg";
   const isWindows = process.platform === "win32";
@@ -89879,7 +89926,7 @@ function parseOutput(output) {
 async function runRg(options) {
   const cli = resolveGrepCli();
   const args = buildArgs(options, cli.backend);
-  const timeout = Math.min(options.timeout ?? DEFAULT_TIMEOUT_MS3, DEFAULT_TIMEOUT_MS3);
+  const timeout = Math.min(options.timeout ?? DEFAULT_TIMEOUT_MS4, DEFAULT_TIMEOUT_MS4);
   if (cli.backend === "rg") {
     args.push("--", options.pattern);
   } else {
@@ -90354,7 +90401,7 @@ function createHandoffTools(ctx) {
 init_logger();
 
 // src/tools/interactive-bash/constants.ts
-var DEFAULT_TIMEOUT_MS5 = 60000;
+var DEFAULT_TIMEOUT_MS6 = 60000;
 var BLOCKED_TMUX_SUBCOMMANDS = [
   "capture-pane",
   "capturep",
@@ -90451,7 +90498,7 @@ The Bash tool can execute these commands directly. Do NOT retry with interactive
       });
       const timeoutPromise = new Promise((_, reject) => {
         const id = setTimeout(() => {
-          const timeoutError = new Error(`Timeout after ${DEFAULT_TIMEOUT_MS5}ms`);
+          const timeoutError = new Error(`Timeout after ${DEFAULT_TIMEOUT_MS6}ms`);
           try {
             proc.kill();
             proc.exited.catch((err) => {
@@ -90459,7 +90506,7 @@ The Bash tool can execute these commands directly. Do NOT retry with interactive
             });
           } catch {}
           reject(timeoutError);
-        }, DEFAULT_TIMEOUT_MS5);
+        }, DEFAULT_TIMEOUT_MS6);
         proc.exited.then(() => clearTimeout(id)).catch(() => clearTimeout(id));
       });
       const [stdout, stderr, exitCode] = await Promise.race([
@@ -97030,6 +97077,7 @@ function createSessionHooks(args) {
     config: pluginConfig.runtime_fallback,
     pluginConfig
   })) : null;
+  const rtkBashRewriter = isHookEnabled("rtk-bash-rewriter") && pluginConfig.rtk?.enabled ? safeHook("rtk-bash-rewriter", () => createRtkBashRewriterHook(ctx, pluginConfig)) : null;
   return {
     contextWindowMonitor,
     preemptiveCompaction,
@@ -97050,7 +97098,8 @@ function createSessionHooks(args) {
     questionLabelTruncator,
     taskResumeInfo,
     anthropicEffort,
-    runtimeFallback
+    runtimeFallback,
+    rtkBashRewriter
   };
 }
 
@@ -112899,7 +112948,8 @@ var HookNameSchema = exports_external.enum([
   "tool-pair-validator",
   "quality-gate",
   "task-notepad",
-  "design-intent-preserver"
+  "design-intent-preserver",
+  "rtk-bash-rewriter"
 ]);
 // src/config/schema/matrix-loop.ts
 var MatrixLoopConfigSchema = exports_external.object({
@@ -112944,6 +112994,13 @@ var NotificationConfigSchema = exports_external.object({
   force_enable: exports_external.boolean().optional()
 });
 
+// src/config/schema/rtk.ts
+var RtkConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().default(false),
+  binary_path: exports_external.string().optional(),
+  timeout_ms: exports_external.number().int().min(1000).max(30000).default(5000)
+});
+
 // src/config/schema/runtime-fallback.ts
 var RuntimeFallbackConfigSchema = exports_external.object({
   enabled: exports_external.boolean().optional().default(false),
@@ -113088,6 +113145,7 @@ var MatrixxConfigSchema = exports_external.object({
   agent_definitions: AgentDefinitionsConfigSchema.optional(),
   model_capabilities: ModelCapabilitiesConfigSchema.optional(),
   matrixx_self_config: MatrixxSelfConfigSkillConfigSchema.optional(),
+  rtk: RtkConfigSchema.optional(),
   _migrations: exports_external.array(exports_external.string()).optional()
 });
 // src/plugin-config.ts
@@ -113713,6 +113771,7 @@ function createToolExecuteBeforeHandler2(args) {
   const questionLabelTruncatorHook = hooks2.questionLabelTruncator?.["tool.execute.before"];
   const mouseNotepadHook = hooks2.mouseNotepad?.["tool.execute.before"];
   const architectHookHook = hooks2.architectHook?.["tool.execute.before"];
+  const rtkBashRewriterHook = hooks2.rtkBashRewriter?.["tool.execute.before"];
   return async (input, output) => {
     await Promise.all([
       qualityGateHook?.(input, output),
@@ -113740,6 +113799,7 @@ function createToolExecuteBeforeHandler2(args) {
         resolvePromise = resolveSessionAgent(ctx.client, sessionId);
       }
     }
+    await rtkBashRewriterHook?.(input, output);
     await nonInteractiveEnvHook?.(input, output);
     await bashFileReadGuardHook?.(input, output);
     await questionLabelTruncatorHook?.(input, output);

package/dist/plugin/hooks/create-core-hooks.d.ts

@@ -51,4 +51,5 @@ export declare function createCoreHooks(args: {
     taskResumeInfo: ReturnType<typeof import("../../hooks").createTaskResumeInfoHook>;
     anthropicEffort: ReturnType<typeof import("../../hooks/anthropic-effort").createAnthropicEffortHook> | null;
     runtimeFallback: ReturnType<typeof import("../../hooks").createRuntimeFallbackHook> | null;
+    rtkBashRewriter: ReturnType<typeof import("../../hooks").createRtkBashRewriterHook> | null;
 };

package/dist/plugin/hooks/create-session-hooks.d.ts

@@ -1,5 +1,5 @@
 import type { HookName, MatrixxConfig } from "../../config";
-import { createAgentUsageReminderHook, createAnthropicContextWindowLimitRecoveryHook, createAutoUpdateCheckerHook, createContextWindowMonitorHook, createDelegateTaskRetryHook, createEditErrorRecoveryHook, createInteractiveBashSessionHook, createMatrixLoopHook, createMouseNotepadHook, createNonInteractiveEnvHook, createOracleMdOnlyHook, createPreemptiveCompactionHook, createQuestionLabelTruncatorHook, createRuntimeFallbackHook, createSessionNotification, createSessionRecoveryHook, createStartWorkHook, createTaskResumeInfoHook, createThinkModeHook } from "../../hooks";
+import { createAgentUsageReminderHook, createAnthropicContextWindowLimitRecoveryHook, createAutoUpdateCheckerHook, createContextWindowMonitorHook, createDelegateTaskRetryHook, createEditErrorRecoveryHook, createInteractiveBashSessionHook, createMatrixLoopHook, createMouseNotepadHook, createNonInteractiveEnvHook, createOracleMdOnlyHook, createPreemptiveCompactionHook, createQuestionLabelTruncatorHook, createRtkBashRewriterHook, createRuntimeFallbackHook, createSessionNotification, createSessionRecoveryHook, createStartWorkHook, createTaskResumeInfoHook, createThinkModeHook } from "../../hooks";
 import { createAnthropicEffortHook } from "../../hooks/anthropic-effort";
 import type { PluginContext } from "../types";
 export type SessionHooks = {
@@ -23,6 +23,7 @@ export type SessionHooks = {
     taskResumeInfo: ReturnType<typeof createTaskResumeInfoHook>;
     anthropicEffort: ReturnType<typeof createAnthropicEffortHook> | null;
     runtimeFallback: ReturnType<typeof createRuntimeFallbackHook> | null;
+    rtkBashRewriter: ReturnType<typeof createRtkBashRewriterHook> | null;
 };
 export declare function createSessionHooks(args: {
     ctx: PluginContext;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-matrixx",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",