opencode-matrixx 2.5.0 → 2.6.1

package/README.md

@@ -61,12 +61,34 @@ That's it. Parallel agents, background tasks, deep exploration, relentless execu
 
 ## Quick Start
 
-### Install
+### Prerequisites
+
+- **Bun** 1.4.0 — `curl -fsSL https://bun.sh/install | bash`
+- **OpenCode** ≥ 1.0.150 — https://opencode.ai/docs
+- Verify: `bun --version && opencode --version`
+
+### Install (Recommended)
+
+```bash
+bunx opencode-matrixx install
+```
+
+Or for non-interactive setup (CI/agents):
+
+```bash
+bunx opencode-matrixx install --no-tui --claude=yes --openai=yes --gemini=no --copilot=no
+```
+
+### Verify Installation
 
 ```bash
-npm install -g opencode-matrixx
+bunx opencode-matrixx doctor
+# No "fail" = good. "warn" for missing optional providers is expected.
+# If doctor reports auth failures after login, update to latest: bunx opencode-matrixx@latest doctor
 ```
 
+Troubleshooting installation issues? See [Installation guide →](docs/guide/installation.md#troubleshooting).
+
 ### Configure
 
 Create `matrixx.jsonc` in your project root:
@@ -78,6 +100,16 @@ Create `matrixx.jsonc` in your project root:
 }
 ```
 
+> **Full example:** See [`matrixx.example.jsonc`](./matrixx.example.jsonc) — a fully annotated reference covering every configuration parameter (agents, categories, **headroom**, **context-mode** (external), DCP, RTK, security, tmux, assembly, evolution, and more) with inline comments and defaults. Copy the sections you need into your project `.opencode/matrixx.jsonc` or user `~/.config/opencode/matrixx.jsonc` (both support JSONC comments).
+> Full guide: [Configuration →](docs/configurations.md) · [Context Management (5 layers) →](docs/context-management.md)
+
+### Authenticate
+
+```bash
+opencode auth login   # follow prompts for each provider you have
+bunx opencode-matrixx doctor --category authentication  # verify
+```
+
 ### Use
 
 Open OpenCode and start coding. Matrixx activates automatically.
@@ -89,12 +121,33 @@ Install and configure matrixx by following the instructions here:
 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)
+[Installation guide →](docs/guide/installation.md) . [Uninstall →](docs/guide/uninstallation.md) . [CLI reference →](docs/cli-guide.md)
 
 ---
 
----
+## CLI Reference
+
+Matrixx includes a built-in CLI accessible via `bunx opencode-matrixx <command>`:
+
+| Command | Description |
+|---------|-------------|
+| `install` | Interactive setup wizard (or `--no-tui` for CI/CD) |
+| `doctor` | Environment diagnostics and health checks |
+| `version` | Display version information |
 
+### Doctor Checks
+
+| Category | What It Checks |
+|----------|----------------|
+| installation | Plugin registration, OpenCode version |
+| configuration | Config file validity (matrixx.jsonc) |
+| authentication | Provider API key status (Anthropic, OpenAI, Google) |
+| dependencies | Runtime deps: Bun, Node.js, Git, Python3 |
+| tools | Optional: ast-grep, Gitleaks, PyMuPDF, Playwright |
+
+Use `--json` for machine-readable output or `--category <name>` for a specific check.
+
+---
 ## The Agent Team
 
 ### 01. Morpheus — *The Orchestrator*
@@ -302,7 +355,7 @@ Every agent, model, temperature, and permission is fully customizable. [**Meet t
 
 | | |
 |---|---|
-|| **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 |
+| **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 |
@@ -311,7 +364,8 @@ Every agent, model, temperature, and permission is fully customizable. [**Meet t
 | **Software Dev Pipeline** | 6-phase TDD workflow (PLAN→BUILD→VERIFY→REVIEW→SECURE→SHIP), 5 team roles, adaptive phases |
 ||| **Assembly Tool** | Multi-model debate that spawns 3-5 parallel voters from different providers, collects independent reasoning, and synthesizes unified decisions with confidence scoring |
 || **Saturation Research** | Multi-round (/research) spawning parallel explore/librarian swarms across code, docs, web, and OSS with adaptive novelty-based convergence (max 5 rounds) |
-|| **AI Slop Detection** | remove-ai-slops skill detects and removes 7 categories of AI-generated code smells — verbose comments, redundant error handling, over-engineered patterns, generic AI phrasing, cargo-cult boilerplate |
+| **AI Slop Detection** | remove-ai-slops skill detects and removes 7 categories of AI-generated code smells — verbose comments, redundant error handling, over-engineered patterns, generic AI phrasing, cargo-cult boilerplate |
+| **Context Management (L0-L4)** | 5-layer stack: Native + [RTK](https://github.com/rtk-ai/rtk) + [context-mode](https://github.com/tarquinen/context-mode) + [DCP](https://github.com/tarquinen/opencode-dcp) + [Headroom](https://github.com/headroomlabs-ai/headroom) — zero overlap, <10ms Matrixx bridge, 60-95% JSON via `CacheAligner→CCR` |
 
 [**Full feature list →**](docs/features.md) · [**Configuration guide →**](docs/configurations.md) · [**Architecture diagram →**](docs/agent-architecture.md)
 
@@ -476,6 +530,128 @@ The 10-20ms subprocess overhead is negligible compared to command execution time
 
 ---
 
+## Headroom Integration — Network-Proxy Compression
+
+> **Deep dive:** [Context Management → 2.4 Headroom](docs/context-management.md#24-headroom--network-proxy-compression) — full 5-layer guide with config reference, verification and troubleshooting.
+
+Matrixx integrates [Headroom](https://github.com/headroomlabs-ai/headroom) for network-proxy-level token compression, reducing context by **60-95%** on JSON, **15-20%** on coding agents via `CacheAligner→ContentRouter→CCR` pipeline.
+
+### What is Headroom?
+
+Headroom is a proxy + MCP provider that compresses history before it reaches the LLM. It intercepts the OpenAI-compatible provider `headroom` via `@ai-sdk/openai-compatible` and serves retrieval via `headroom_retrieve`.
+
+```
+# Without headroom: 50k tokens history
+# Every turn ships full JSON + tool outputs
+
+# With headroom wrap: 8k tokens (CCR + retrieval)
+$ headroom wrap opencode
+# CCR compresses; agents retrieve via headroom_retrieve on demand
+```
+
+Headroom is ideal for JSON-heavy sessions, long histories, and multi-project reuse where the same compressed context (CCR) can be shared.
+
+### How It Works
+
+1. User runs `headroom wrap opencode` (starts proxy at `http://127.0.0.1:8787`)
+2. Headroom MCP registers `headroom_retrieve` / `headroom_stats`
+3. Matrixx detects `hasHeadroom = availableTools.some(t => t.name.startsWith("headroom_"))` and injects Headroom discipline into agent prompts
+4. Proxy's `CacheAligner→ContentRouter→CCR` compresses; agents retrieve via `headroom_retrieve` on demand
+
+Matrixx does not vendor Headroom. It provides a thin config bridge in `src/config/schema/headroom.ts` plus runtime detection. Native transport `headroom-opencode` is deferred to Phase 2.
+
+### Configuration
+
+Headroom is **disabled by default** (opt-in). Enable it in `matrixx.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://raw.githubusercontent.com/klpanagi/opencode-matrixx/refs/heads/dev/dist/matrixx.schema.json",
+  "headroom": {
+    "enabled": true,                        // default: false — opt-in
+    "proxyUrl": "http://127.0.0.1:8787",     // optional — defaults to proxy default
+    "project": "my-project",                // optional — CCR scoping
+    "backend": "openai"                     // optional — HEADROOM_BACKEND
+  }
+}
+```
+
+| Option | Type | Default | Notes |
+|--------|------|---------|-------|
+| `enabled` | boolean | `false` | Opt-in — no proxy/discipline unless `true` |
+| `proxyUrl` | string (url) | `http://127.0.0.1:8787` | Proxy URL (`HEADROOM_PROXY_URL` override) |
+| `project` | string | `undefined` | CCR scoping per project |
+| `backend` | string | `undefined` | Maps to `HEADROOM_BACKEND` |
+
+### Installation
+
+Install Headroom from [headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom):
+
+```bash
+# Install (pick one)
+uv tool install headroom-ai[all]
+# or
+pipx install headroom-ai[all]
+
+# Verify
+headroom --version
+headroom doctor
+
+# Run via proxy (recommended)
+headroom wrap opencode
+# alternative — env wrapping
+# HEADROOM_WRAP=1 headroom wrap -- opencode
+
+# Dashboard
+headroom dashboard
+```
+
+Package versions: `npm: headroom-ai@0.37.0`, `PyPI: headroom-ai[all]`. Docs at [headroom-docs.vercel.app](https://headroom-docs.vercel.app).
+
+> **Note:** Native TypeScript plugin `headroom-opencode` is deferred to **Phase 2** due to [#2798](https://github.com/sst/opencode/issues/2798) global `fetch` patch collision and [#76](https://github.com/headroomlabs-ai/headroom/issues/76) compaction not yet stable. Prefer `wrap` for now.
+
+### Verification
+
+After install, confirm Matrixx sees Headroom:
+
+```bash
+headroom doctor          # proxy health
+headroom wrap opencode # should show: proxy http://127.0.0.1:8787
+```
+
+- In OpenCode TUI, run `headroom_stats` (or `headroom dashboard`) — if the tool is listed, Matrixx injected Headroom discipline into Morpheus/Keymaker prompts.
+- Agents will use `headroom_retrieve` / `headroom_search` automatically — you don't call them manually. If `headroom_*` tools are absent, check `matrixx.jsonc` has `headroom.enabled: true` and restart OpenCode.
+
+### Usage
+
+No code changes needed. Once `headroom wrap opencode` is running and `headroom.enabled: true`:
+
+- **You** keep using OpenCode normally (`ultrawork`, etc.).
+- **Proxy** compresses history out-of-process via `CacheAligner→ContentRouter→CCR` before it reaches the LLM.
+- **Agents** retrieve compressed slices on demand via `headroom_retrieve` (never re-read full history) and check stats via `headroom_stats`.
+- **CCR** is shared across projects — ideal for repeated JSON-heavy sessions.
+
+To disable, set `headroom.enabled: false` or run OpenCode without `headroom wrap`.
+
+### Performance Impact
+
+| Metric | Value |
+|--------|-------|
+| **Matrixx bridge overhead** | ~0ms (prompt-only; proxy out-of-process) |
+| **Proxy token savings** | 60-95% JSON, 15-20% coding agents |
+| **Complementarity** | L4 orthogonal to L1 RTK + L2 context-mode + L3 DCP + L0 native (zero overlap) |
+| **Net benefit** | Retrieval-on-demand reduces per-turn context; CCR shared across projects |
+
+### 5-Layer Complementarity
+
+| Layer | Owner | Mechanism | Reduction |
+|-------|-------|-----------|-----------|
+| L0 Native | Matrixx | 70% warn, preemptive-compaction, anthropic-recovery | Prevents OOM |
+| L1 RTK | RTK hook | Bash output compression | 60-90% bash |
+| L2 context-mode | context-mode plugin | FTS5 sandbox `ctx_*` | 98% sandbox |
+| L3 DCP | `@tarquinen/opencode-dcp` | Pruning tiers `economy→ultimate` | Tiered pruning |
+| L4 Headroom | headroom proxy | `CacheAligner→ContentRouter→CCR` | 60-95% JSON |
+---
 
 ## Documentation
 
@@ -488,11 +664,11 @@ The 10-20ms subprocess overhead is negligible compared to command execution time
 | [Configuration](docs/configurations.md) | All config options, agent overrides, hooks, categories |
 | [Orchestration](docs/orchestration-guide.md) | How agents coordinate, delegate, and recover |
 | [Categories & Skills](docs/category-skill-guide.md) | Task categories, skill injection, delegation patterns |
+| [Context Management](docs/context-management.md) | 5-layer context stack (Native, RTK, context-mode, DCP, Headroom) — setup, config, verification |
 
 ---
 
-If this saves you time, a ⭐ goes a long way.
 
-**Curious about the philosophy?** Read the [Ultrawork Manifesto](docs/ultrawork-manifesto.md) — originally authored by [code-yeongyu](https://github.com/code-yeongyu), the creator of oh-my-opencode.
+If this saves you time, a ⭐ goes a long way.
 
 <sub>Productivity might spike too hard. Don't let your coworker notice. Actually — let's see who wins.</sub>

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

@@ -34,4 +34,7 @@ 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 buildHeadroomSection(hasHeadroom?: boolean): string;
+export declare function buildCompactContextDisciplineSection(hasContextMode?: boolean): string;
+export declare function buildExploreDisciplineSection(hasContextMode?: boolean, hasHeadroom?: boolean): string;
 export declare function buildUltraworkSection(agents: AvailableAgent[], categories: AvailableCategory[], skills: AvailableSkill[]): string;

package/dist/cli/doctor/checks/auth.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const authCheck: DoctorCheck;

package/dist/cli/doctor/checks/config.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const configValidationCheck: DoctorCheck;

package/dist/cli/doctor/checks/context-mode.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const contextModeCheck: DoctorCheck;

package/dist/cli/doctor/checks/dcp.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const dcpCheck: DoctorCheck;

package/dist/cli/doctor/checks/docker.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const dockerCheck: DoctorCheck;

package/dist/cli/doctor/checks/headroom.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const headroomCheck: DoctorCheck;

package/dist/cli/doctor/checks/helpers.d.ts

@@ -0,0 +1,2 @@
+export declare function readMatrixxConfig(): Record<string, unknown> | null;
+export declare function getNested<T>(obj: Record<string, unknown> | null, path: string): T | undefined;

package/dist/cli/doctor/checks/index.d.ts

@@ -0,0 +1,16 @@
+import type { DoctorCheck } from "../types";
+export declare const ALL_CHECKS: DoctorCheck[];
+export declare function getChecksByCategory(category: string): DoctorCheck[];
+export declare function getCategories(): string[];
+export { authCheck } from "./auth";
+export { configValidationCheck } from "./config";
+export { contextModeCheck } from "./context-mode";
+export { dcpCheck } from "./dcp";
+export { dockerCheck } from "./docker";
+export { headroomCheck } from "./headroom";
+export { mcpPrerequisitesCheck } from "./mcp";
+export { optionalToolsCheck } from "./optional";
+export { pluginInstallationCheck } from "./plugin";
+export { rtkCheck } from "./rtk";
+export { runtimeDepsCheck } from "./runtime";
+export { tmuxCheck } from "./tmux";

package/dist/cli/doctor/checks/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const mcpPrerequisitesCheck: DoctorCheck;

package/dist/cli/doctor/checks/optional.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const optionalToolsCheck: DoctorCheck;

package/dist/cli/doctor/checks/plugin.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const pluginInstallationCheck: DoctorCheck;

package/dist/cli/doctor/checks/rtk.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const rtkCheck: DoctorCheck;

package/dist/cli/doctor/checks/runtime.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const runtimeDepsCheck: DoctorCheck;

package/dist/cli/doctor/checks/tmux.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheck } from "../types";
+export declare const tmuxCheck: DoctorCheck;

package/dist/cli/doctor/format.d.ts

@@ -0,0 +1,3 @@
+import type { DoctorReport } from "./types";
+export declare function formatDoctorReport(report: DoctorReport): string;
+export declare function formatDoctorJson(report: DoctorReport): string;

package/dist/cli/doctor/index.d.ts

@@ -0,0 +1,9 @@
+import type { DoctorReport } from "./types";
+export type { CheckCategory, CheckResult, CheckStatus, DoctorCheck, DoctorReport } from "./types";
+export interface DoctorOptions {
+    category?: string;
+    json?: boolean;
+}
+export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+export declare function executeDoctor(options?: DoctorOptions): Promise<string>;
+export { ALL_CHECKS, getCategories, getChecksByCategory } from "./checks";

package/dist/cli/doctor/types.d.ts

@@ -0,0 +1,24 @@
+export type CheckStatus = "pass" | "warn" | "fail";
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    message: string;
+    category?: string;
+    detail?: string;
+}
+export type CheckCategory = "installation" | "configuration" | "authentication" | "dependencies" | "tools" | "integrations" | "updates";
+export interface DoctorCheck {
+    name: string;
+    category: CheckCategory;
+    check: () => Promise<CheckResult> | CheckResult;
+}
+export interface DoctorReport {
+    timestamp: string;
+    checks: CheckResult[];
+    summary: {
+        total: number;
+        passed: number;
+        warnings: number;
+        failed: number;
+    };
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+/**
+ * Matrixx CLI — `bunx opencode-matrixx <command>`
+ *
+ * Commands:
+ *   doctor    - Environment diagnostics and health checks
+ *   install   - Interactive setup wizard (--no-tui for CI)
+ *   setup     - Standalone setup wizard for deps + matrixx.jsonc generation
+ *   version   - Display version information
+ *   help      - Display help information
+ */
+declare function main(): Promise<void>;
+export { main };
+export default main;

package/dist/cli/install/index.d.ts

@@ -0,0 +1,12 @@
+export interface InstallOptions {
+    noTui?: boolean;
+    claude?: "yes" | "no" | "max20";
+    openai?: "yes" | "no";
+    gemini?: "yes" | "no";
+    copilot?: "yes" | "no";
+    opencodeZen?: "yes" | "no";
+    zaiCodingPlan?: "yes" | "no";
+    verbose?: boolean;
+    local?: boolean;
+}
+export declare function executeInstall(options: InstallOptions): Promise<string>;

package/dist/cli/setup/config-writer.d.ts

@@ -0,0 +1,12 @@
+import { type MatrixxConfig } from "../../config/schema/matrixx-config";
+import type { SetupState } from "./types";
+export declare function resolveMatrixxConfigPath(): {
+    format: "json" | "jsonc" | "none";
+    path: string;
+};
+export declare function buildMatrixxConfig(state: SetupState, existing: MatrixxConfig | null): MatrixxConfig;
+export declare function previewDiff(existing: string, next: string): string;
+export declare function writeMatrixxConfig(targetPath: string, config: MatrixxConfig, opts: {
+    dryRun: boolean;
+    backup: boolean;
+}): Promise<void>;

package/dist/cli/setup/config-writer.test.d.ts

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

package/dist/cli/setup/constants.d.ts

@@ -0,0 +1,8 @@
+import type { Platform } from "./types";
+export declare const REQUIRED_DEPS: readonly ["bun", "opencode", "git"];
+export declare const OPTIONAL_DEPS: readonly ["headroom", "rtk", "dcp", "gitleaks", "ast-grep", "playwright"];
+export type InstallCommandMap = Record<string, Record<Platform | "all", string> | Record<string, string>>;
+export declare const PLATFORM_INSTALL_COMMANDS: Record<string, Partial<Record<Platform | "all", string>>>;
+export declare function getDcpInstallHint(): string;
+export declare function configDirHint(): string;
+export declare function dcpPluginDirHint(): string;

package/dist/cli/setup/deps.d.ts

@@ -0,0 +1,8 @@
+import { type DepStatus, type Platform } from "./types";
+export declare function isBunVersionOk(found: string): boolean;
+export declare function isOpenCodeVersionOk(found: string): boolean;
+export declare function getPlatform(): Platform;
+export declare function getInstallCommand(dep: string, platform: Platform): string;
+export declare function checkRequiredDeps(): DepStatus[];
+export declare function checkOptionalDeps(): DepStatus[];
+export declare function formatDepReport(statuses: DepStatus[]): string;

package/dist/cli/setup/deps.test.d.ts

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

package/dist/cli/setup/index.d.ts

@@ -0,0 +1,8 @@
+export { PLATFORM_INSTALL_COMMANDS } from "./constants";
+export { checkOptionalDeps, checkRequiredDeps, formatDepReport, getInstallCommand, getPlatform, isBunVersionOk, isOpenCodeVersionOk } from "./deps";
+export { runSetupPrompts } from "./prompts";
+export type { DepStatus, Platform, SetupState } from "./types";
+export declare function executeSetup(opts: {
+    dryRun: boolean;
+    yes: boolean;
+}): Promise<string>;

package/dist/cli/setup/index.test.d.ts

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

package/dist/cli/setup/opencode-sync.d.ts

@@ -0,0 +1,9 @@
+import type { SetupState } from "./types";
+export declare function resolveOpencodeConfigPath(): {
+    format: "json" | "jsonc" | "none";
+    path: string;
+};
+export declare function syncOpencodePlugins(state: SetupState, opts: {
+    dryRun: boolean;
+}): Promise<void>;
+export declare function hasContextModePlugin(plugins: string[]): boolean;

package/dist/cli/setup/opencode-sync.test.d.ts

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

package/dist/cli/setup/prompts.d.ts

@@ -0,0 +1,4 @@
+import type { DepStatus, SetupState } from "./types";
+export declare function runSetupPrompts(deps: DepStatus[], opts: {
+    yes: boolean;
+}): Promise<SetupState>;

package/dist/cli/setup/prompts.test.d.ts

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

package/dist/cli/setup/types.d.ts

@@ -0,0 +1,26 @@
+export type Platform = "darwin" | "linux" | "win32";
+export type DepStatus = {
+    name: string;
+    required: boolean;
+    found: boolean;
+    version?: string;
+    installHint: string;
+};
+export type SetupState = {
+    taskSystem: boolean;
+    headroom: {
+        enabled: boolean;
+        proxyUrl?: string;
+        project?: string;
+    };
+    rtk: {
+        enabled: boolean;
+        binaryPath?: string;
+    };
+    dcp: {
+        enabled: boolean;
+    };
+    contextMode: boolean;
+};
+export declare const BUN_REQUIRED = "1.4.0";
+export declare const OPENCODE_MIN = "1.0.150";