opencode-matrixx 2.2.0 → 2.4.0

package/README.md

@@ -1,5 +1,5 @@
 >
-> [![Matrixx](./.github/assets/orchestrator-architect.png?v=3)](https://github.com/klpanagi/matrixx)
+> [![Matrixx](./.github/assets/orchestrator-architect.png?v=3)](https://github.com/klpanagi/opencode-matrixx)
 >
 > Matrixx is **highly inspired by** [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) — the project that pioneered the "oh-my-zsh for OpenCode" concept.
 > Full credit to [code-yeongyu](https://github.com/code-yeongyu) for the original vision.
@@ -10,7 +10,7 @@
 <h1>Matrixx</h1>
 
 [![npm](https://img.shields.io/npm/v/opencode-matrixx.svg)](https://www.npmjs.com/package/opencode-matrixx)
-[![License: SUL-1.0](https://img.shields.io/badge/license-SUL--1.0-blue.svg)](https://github.com/klpanagi/matrixx/blob/master/LICENSE)
+[![License: SUL-1.0](https://img.shields.io/badge/license-SUL--1.0-blue.svg)](https://github.com/klpanagi/opencode-matrixx/blob/master/LICENSE)
 
 **Multi-model agent orchestration for [OpenCode](https://github.com/sst/opencode).**<br/>
 **14 specialized agents. ~52 lifecycle hooks. 28 tools. One plugin.**
@@ -73,8 +73,8 @@ Create `matrixx.jsonc` in your project root:
 
 ```jsonc
 {
-  "$schema": "https://raw.githubusercontent.com/klpanagi/matrixx/refs/heads/dev/dist/matrixx.schema.json",
-  "profile": "balanced"
+  "$schema": "https://raw.githubusercontent.com/klpanagi/opencode-matrixx/refs/heads/dev/dist/matrixx.schema.json",
+  "agents": {}
 }
 ```
 
@@ -86,32 +86,13 @@ Open OpenCode and start coding. Matrixx activates automatically.
 
 ```
 Install and configure matrixx by following the instructions here:
-https://raw.githubusercontent.com/klpanagi/matrixx/refs/heads/dev/docs/guide/installation.md
+https://raw.githubusercontent.com/klpanagi/opencode-matrixx/refs/heads/dev/docs/guide/installation.md
 ```
 
 [Manual installation guide →](docs/guide/installation.md) · [Uninstall →](docs/guide/uninstallation.md)
 
 ---
 
-## Profiles
-
-Profiles assign models to every agent — one setting, full model lineup.
-
-| Profile | Best For | Daily Cost |
-|---------|----------|------------|
-| **free** | Experimentation, prototyping | $0 |
-| **budget** | Personal projects, light use | ~$1–3 |
-| **economy** | Active development with cost control | ~$3–8 |
-| **balanced** | Professional development | ~$8–20 |
-| **performance** | Maximum capability | ~$20–50 |
-| **go** | OpenCode Go subscription | Go quota |
-| **go-duo** | Duo subscription, two users | Go Duo quota |
-| **go-trio** | Trio subscription, three users | Go Trio quota |
-| **go-ultimate** | Unlimited Go access | Go Ultimate quota |
-| **xiaomi-ultimate** | Xiaomi-optimized ultimate | Xiaomi quota |
-
-Profile defaults merge first; any `agents` or `categories` override takes precedence.
-
 ---
 
 ## The Agent Team
@@ -298,6 +279,21 @@ Analyzes media files that require interpretation beyond raw text. Extracts speci
 
 ---
 
+### 14. Mouse — *The Task Executor*
+
+*Small, fast, and disposable — the hands that do the work.*
+
+**Role:** Category-spawned delegated executor
+
+**Model:** Claude Sonnet 4.6 · `temperature: 0.1`
+
+Mouse is the worker layer in Matrixx's 3-tier architecture. Spawned automatically when you
+use `task(category="...")`, Mouse executes the task directly without delegating further.
+It cannot spawn sub-agents (`task` tool blocked) — implementation is always done in-house.
+Model-specific prompt variants optimize behavior for Claude, GPT, DeepSeek, Mimo, and Qwen.
+
+---
+
 Every agent, model, temperature, and permission is fully customizable. [**Meet the full team →**](docs/agents.md)
 
 ---
@@ -306,7 +302,7 @@ Every agent, model, temperature, and permission is fully customizable. [**Meet t
 
 | | |
 |---|---|
-| **Agent Orchestration** | 14 agents (incl. **Sati** frontend specialist, **Sentinel** security auditor, **Cipher** DSL expert), parallel background execution, category-based routing, session continuity |
+|| **Agent Orchestration** | 15 agents (incl. **Mouse** dedicated executor, **Sati** frontend specialist, **Sentinel** security auditor, **Cipher** DSL expert), parallel background execution, category-based routing, session continuity |
 | **Developer Tools** | LSP (goto def, rename, diagnostics), AST-Grep (search & replace), Tmux terminal |
 | **~52 Lifecycle Hooks** | Context injection, think mode, comment checking, todo enforcement, error recovery, quality gate |
 || **33 Built-in Skills** | DSL engineering (11), security (9), browser, git, frontend (7 via **Sati**), saturation research, AI slop detection, software dev pipeline |
@@ -405,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/agents/bdd-contract.d.ts

@@ -0,0 +1,7 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AgentPromptMetadata } from "./types";
+export declare const BDD_CONTRACT_PROMPT_METADATA: AgentPromptMetadata;
+export declare function createBddContractAgent(model: string): AgentConfig;
+export declare namespace createBddContractAgent {
+    var mode: "all";
+}

package/dist/agents/builtin-agents/architect-agent.d.ts

@@ -5,6 +5,7 @@ import type { AgentOverrides } from "../types";
 export declare function maybeCreateArchitectConfig(input: {
     disabledAgents: string[];
     agentOverrides: AgentOverrides;
+    globalOverrideModel?: string;
     uiSelectedModel?: string;
     availableModels: Set<string>;
     systemDefaultModel?: string;

package/dist/agents/builtin-agents/general-agents.d.ts

@@ -7,6 +7,7 @@ export declare function collectPendingBuiltinAgents(input: {
     agentMetadata: Partial<Record<BuiltinAgentName, AgentPromptMetadata>>;
     disabledAgents: string[];
     agentOverrides: AgentOverrides;
+    globalOverrideModel?: string;
     directory?: string;
     systemDefaultModel?: string;
     mergedCategories: Record<string, CategoryConfig>;

package/dist/agents/builtin-agents/{hephaestus-agent.d.ts → keymaker-agent.d.ts}

@@ -5,6 +5,7 @@ import type { AgentOverrides } from "../types";
 export declare function maybeCreateKeymakerConfig(input: {
     disabledAgents: string[];
     agentOverrides: AgentOverrides;
+    globalOverrideModel?: string;
     availableModels: Set<string>;
     systemDefaultModel?: string;
     isFirstRunNoCache: boolean;
@@ -14,4 +15,5 @@ export declare function maybeCreateKeymakerConfig(input: {
     mergedCategories: Record<string, CategoryConfig>;
     directory?: string;
     useTaskSystem: boolean;
+    availableToolNames: string[];
 }): AgentConfig | undefined;

package/dist/agents/builtin-agents/model-resolution.d.ts

@@ -1,4 +1,5 @@
 export declare function applyModelResolution(input: {
+    globalOverrideModel?: string;
     uiSelectedModel?: string;
     userModel?: string;
     requirement?: {

package/dist/agents/builtin-agents/morpheus-agent.d.ts

@@ -5,6 +5,7 @@ import type { AgentOverrides } from "../types";
 export declare function maybeCreateMorpheusConfig(input: {
     disabledAgents: string[];
     agentOverrides: AgentOverrides;
+    globalOverrideModel?: string;
     uiSelectedModel?: string;
     availableModels: Set<string>;
     systemDefaultModel?: string;
@@ -16,4 +17,5 @@ export declare function maybeCreateMorpheusConfig(input: {
     directory?: string;
     userCategories?: CategoriesConfig;
     useTaskSystem: boolean;
+    availableToolNames: string[];
 }): AgentConfig | undefined;

package/dist/agents/builtin-agents.d.ts

@@ -2,4 +2,4 @@ import type { AgentConfig } from "@opencode-ai/sdk";
 import type { BrowserAutomationProvider, CategoriesConfig } from "../config/schema";
 import type { LoadedSkill } from "../features/opencode-skill-loader/types";
 import type { AgentOverrides } from "./types";
-export declare function createBuiltinAgents(disabledAgents?: string[], agentOverrides?: AgentOverrides, directory?: string, systemDefaultModel?: string, categories?: CategoriesConfig, discoveredSkills?: LoadedSkill[], customAgentSummaries?: unknown, browserProvider?: BrowserAutomationProvider, uiSelectedModel?: string, disabledSkills?: Set<string>, useTaskSystem?: boolean): Promise<Record<string, AgentConfig>>;
+export declare function createBuiltinAgents(disabledAgents?: string[], agentOverrides?: AgentOverrides, directory?: string, systemDefaultModel?: string, categories?: CategoriesConfig, discoveredSkills?: LoadedSkill[], customAgentSummaries?: unknown, browserProvider?: BrowserAutomationProvider, uiSelectedModel?: string, disabledSkills?: Set<string>, useTaskSystem?: boolean, globalModel?: string, availableToolNames?: string[]): Promise<Record<string, AgentConfig>>;

package/dist/agents/dynamic-agent-prompt-builder.d.ts

@@ -6,7 +6,7 @@ export interface AvailableAgent {
 }
 export interface AvailableTool {
     name: string;
-    category: "lsp" | "ast" | "search" | "session" | "command" | "other";
+    category: "lsp" | "ast" | "search" | "session" | "command" | "sandbox" | "other";
 }
 export interface AvailableSkill {
     name: string;
@@ -33,4 +33,5 @@ export declare function buildCategorySkillsDelegationGuide(categories: Available
 export declare function buildOracleSection(agents: AvailableAgent[]): string;
 export declare function buildHardBlocksSection(): string;
 export declare function buildAntiPatternsSection(): string;
+export declare function buildContextDisciplineSection(hasContextMode?: boolean): string;
 export declare function buildUltraworkSection(agents: AvailableAgent[], categories: AvailableCategory[], skills: AvailableSkill[]): string;

package/dist/agents/env-context.d.ts

@@ -2,6 +2,6 @@
  * Creates Matrixx-specific environment context (time, timezone, locale).
  * Note: Working directory, platform, and date are already provided by OpenCode's system.ts,
  * so we only include fields that OpenCode doesn't provide to avoid duplication.
- * See: https://github.com/klpanagi/matrixx/issues/379
+ * See: https://github.com/klpanagi/opencode-matrixx/issues/379
  */
 export declare function createEnvContext(): string;

package/dist/agents/mouse/agent.d.ts

@@ -6,7 +6,10 @@
  *
  * Routing:
  * 1. GPT models (openai/*, github-copilot/gpt-*) -> gpt.ts (GPT-5.2 optimized)
- * 2. Default (Claude, etc.) -> default.ts (Claude-optimized)
+ * 2. DeepSeek models (opencode-go/deepseek-*) -> deepseek.ts (DeepSeek-optimized)
+ * 3. Mimo models (opencode-go/mimo-*) -> mimo.ts (Mimo-optimized)
+ * 4. Qwen models (opencode-go/qwen-*) -> qwen.ts (Qwen-optimized)
+ * 5. Default (Anthropic/Claude, etc.) -> default.ts (Claude-optimized)
  */
 import type { AgentConfig } from "@opencode-ai/sdk";
 import type { AgentOverrideConfig } from "../../config/schema";
@@ -14,7 +17,7 @@ export declare const MOUSE_DEFAULTS: {
     readonly model: "anthropic/claude-sonnet-4-6";
     readonly temperature: 0.1;
 };
-export type MousePromptSource = "default" | "gpt";
+export type MousePromptSource = "default" | "gpt" | "deepseek" | "mimo" | "qwen";
 /**
  * Determines which Mouse prompt to use based on model.
  */

package/dist/agents/mouse/deepseek.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DeepSeek-Optimized Mouse System Prompt
+ *
+ * Optimized for DeepSeek model characteristics:
+ * - Strong instruction following — explicit constraints work well
+ * - Efficient at code generation — prefers clear, direct instructions
+ * - Not overly verbose by default — moderate verbosity controls suffice
+ * - Responds well to XML-style structure
+ *
+ * Key differences from default (Claude) prompt:
+ * - No "you're too helpful" framing (not needed for DeepSeek)
+ * - More structured, table-based sections (DeepSeek handles tables well)
+ * - Moderate verbosity guidance
+ * - Verification table for clarity
+ */
+export declare function buildDeepSeekMousePrompt(useTaskSystem: boolean, promptAppend?: string): string;

package/dist/agents/mouse/index.d.ts

@@ -1,4 +1,7 @@
 export type { MousePromptSource } from "./agent";
 export { buildMousePrompt, createMouseAgentWithOverrides, getMousePromptSource, MOUSE_DEFAULTS, } from "./agent";
+export { buildDeepSeekMousePrompt } from "./deepseek";
 export { buildDefaultMousePrompt } from "./default";
 export { buildGptMousePrompt } from "./gpt";
+export { buildMimoMousePrompt } from "./mimo";
+export { buildQwenMousePrompt } from "./qwen";

package/dist/agents/mouse/mimo.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mimo-Optimized Mouse System Prompt
+ *
+ * Optimized for Mimo model characteristics:
+ * - Lightweight, cost-efficient model — concise prompts reduce token waste
+ * - Fast inference — direct instructions maximize throughput
+ * - Good at following explicit, compact instructions
+ *
+ * Key differences from other prompts:
+ * - Extra concise — minimal prose, maximum signal
+ * - No extended reasoning sections (Mimo does not deep-reason)
+ * - Strong emphasis on tool-first approach
+ * - Simple, direct structure
+ */
+export declare function buildMimoMousePrompt(useTaskSystem: boolean, promptAppend?: string): string;

package/dist/agents/mouse/qwen.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Qwen-Optimized Mouse System Prompt
+ *
+ * Optimized for Qwen model characteristics:
+ * - Strong reasoning capabilities — benefits from structured, detailed prompts
+ * - Good instruction following with explicit XML-style structure
+ * - Works well with specification tables and clear formatting
+ * - Benefits from explicit output formatting guidance
+ *
+ * Key differences from other prompts:
+ * - More structured specification sections (Qwen handles detailed specs well)
+ * - Explicit output format guidance
+ * - Reasoning-first approach: think → verify → act
+ * - Balanced verbosity controls
+ */
+export declare function buildQwenMousePrompt(useTaskSystem: boolean, promptAppend?: string): string;

package/dist/agents/mouse/shared.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared utility functions for Mouse prompt variants.
+ * Extracted to avoid duplication across model-specific prompt files.
+ */
+export declare function buildConstraintsSection(useTaskSystem: boolean): string;
+export declare function buildTodoDisciplineSection(useTaskSystem: boolean): string;
+export declare function buildVerificationTable(useTaskSystem: boolean): string;

package/dist/agents/types.d.ts

@@ -58,7 +58,10 @@ export declare function isGptModel(model: string): boolean;
  * Matches: "anthropic/claude-*", "google-vertex-anthropic/claude-*", etc.
  */
 export declare function isAnthropicModel(model: string): boolean;
-export type BuiltinAgentName = "morpheus" | "keymaker" | "oracle" | "merovingian" | "operator" | "trinity" | "construct" | "seraph" | "smith" | "architect" | "cipher" | "sentinel" | "sati";
+export declare function isQwenModel(model: string): boolean;
+export declare function isMimoModel(model: string): boolean;
+export declare function isDeepSeekModel(model: string): boolean;
+export type BuiltinAgentName = "morpheus" | "keymaker" | "oracle" | "merovingian" | "operator" | "trinity" | "construct" | "seraph" | "smith" | "architect" | "cipher" | "sentinel" | "sati" | "bdd-contract";
 type OverridableAgentName = "build" | BuiltinAgentName;
 export type AgentName = BuiltinAgentName;
 export type AgentOverrideConfig = Partial<AgentConfig> & {

package/dist/config/index.d.ts

@@ -1,4 +1,3 @@
-export type { ProfileName } from "./profiles";
-export { expandProfile, PROFILE_NAMES } from "./profiles";
+export { expandPreset, PRESET_NAMES, type PresetName } from "./presets";
 export type { AgentDefinitions, AgentName, AgentOverrideConfig, AgentOverrides, BuiltinCommandName, EnvFileGuardConfig, ExperimentalConfig, HookName, MatrixLoopConfig, MatrixxConfig, McpName, ModelCapabilitiesConfig, MorpheusAgentConfig, MorpheusConfig, MorpheusTasksConfig, RuntimeFallbackConfig, SecretScanningConfig, SecurityConfig, TmuxConfig, TmuxLayout, } from "./schema";
 export { AgentOverrideConfigSchema, AgentOverridesSchema, BuiltinCommandNameSchema, ExperimentalConfigSchema, HookNameSchema, MatrixLoopConfigSchema, MatrixxConfigSchema, McpNameSchema, MorpheusAgentConfigSchema, RuntimeFallbackConfigSchema, SecurityConfigSchema, TmuxConfigSchema, TmuxLayoutSchema, } from "./schema";

package/dist/config/presets.d.ts

@@ -0,0 +1,4 @@
+import type { MatrixxConfig } from "./schema/matrixx-config";
+export declare const PRESET_NAMES: readonly ["minimal", "balanced", "performance", "frontier"];
+export type PresetName = (typeof PRESET_NAMES)[number];
+export declare function expandPreset(preset: PresetName): MatrixxConfig;

package/dist/config/resolve-tiers.d.ts

@@ -0,0 +1,32 @@
+import { type TierResolverContext } from "../shared/tier-resolver";
+import type { MatrixxConfig } from "./schema/matrixx-config";
+interface WithTier {
+    model?: string;
+    tier?: string;
+}
+/**
+ * Walk a merged MatrixxConfig and resolve any `tier: "..."` fields to concrete
+ * `model: "..."` strings. The result is a new config object with the `tier`
+ * fields cleared (so downstream code never re-resolves them).
+ *
+ * Precedence (per agent/category):
+ *   1. Explicit `model` — kept as-is.
+ *   2. Explicit `tier` — resolved against the live provider list.
+ *   3. `default_tier` (top-level) — applied to any agent/category without
+ *      a `model` or `tier` override, then resolved.
+ *
+ * If a tier cannot be resolved, the entry is left with `tier` set and `model`
+ * undefined. The downstream `resolveModelPipeline` will fall through to
+ * category defaults and the system default as a last resort.
+ */
+export declare function resolveTiersInConfig(config: MatrixxConfig, ctx: TierResolverContext): MatrixxConfig;
+/**
+ * Resolve tier fields in a category registry (e.g. `DEFAULT_CATEGORIES`) and
+ * return a new object with `tier` cleared and `model` set where the tier
+ * resolved. Entries that already have a concrete `model` are passed through.
+ * Used at config load time to pre-resolve the built-in defaults so that
+ * downstream code (createBuiltinAgents, buildAgent) only ever sees model
+ * strings.
+ */
+export declare function resolveTiersInCategoryRegistry(registry: Record<string, WithTier | undefined>, ctx: TierResolverContext): Record<string, WithTier>;
+export {};

package/dist/config/schema/agent-names.d.ts

@@ -13,13 +13,16 @@ export declare const BuiltinAgentNameSchema: z.ZodEnum<{
     cipher: "cipher";
     sentinel: "sentinel";
     sati: "sati";
+    "bdd-contract": "bdd-contract";
 }>;
 export declare const BuiltinSkillNameSchema: z.ZodEnum<{
+    "bdd-contract": "bdd-contract";
     playwright: "playwright";
     "agent-browser": "agent-browser";
     "dev-browser": "dev-browser";
     "frontend-ui-ux": "frontend-ui-ux";
     "git-master": "git-master";
+    "docker-master": "docker-master";
     "dsl-core": "dsl-core";
     "dsl-grammar": "dsl-grammar";
     "dsl-codegen": "dsl-codegen";
@@ -47,5 +50,8 @@ export declare const BuiltinSkillNameSchema: z.ZodEnum<{
     "matrixx-self-config": "matrixx-self-config";
     "ulw-research": "ulw-research";
     "remove-ai-slops": "remove-ai-slops";
+    "bdd-backend": "bdd-backend";
+    "bdd-frontend": "bdd-frontend";
+    "bdd-tests": "bdd-tests";
 }>;
 export type AgentName = z.infer<typeof BuiltinAgentNameSchema>;