Matrixx is highly inspired by oh-my-opencode — the project that pioneered the "oh-my-zsh for OpenCode" concept. Full credit to code-yeongyu for the original vision.

---

What is Matrixx?

OpenCode is a powerful open-source AI coding agent. Matrixx makes it smarter.

Instead of one model doing everything, Matrixx coordinates a team of specialists — each model doing what it does best, in parallel, with full context awareness. The right model for the right job, automatically.

You: "Add OAuth2 with PKCE to the API"
     ↓
Morpheus (Claude Opus)     → Plans the implementation
  ├─ Keymaker (GPT 5.3)    → Builds auth middleware + routes
  ├─ Oracle (Claude Sonnet 4.6)  → Reviews architecture in parallel
  └─ Sentinel (Sonnet 4.6) → Audits for security vulnerabilities
     ↓
     Done. Tested. Secure.

---

Why Matrixx?

Problem	Matrixx Solution
One model does everything poorly	14 specialists — right model for the right job
Agent forgets what it was doing	Todo Continuation — forces completion, no exceptions
Slow sequential tool calls	Parallel background agents — 5+ running simultaneously
AI-generated code looks like AI	Comment Checker — code indistinguishable from human-written
Context window fills up fast	Aggressive delegation — subagents carry the load
Fragile refactoring	LSP + AST-Grep — deterministic, safe, surgical

---

The Magic Word

Don't want to read docs? Just type ultrawork (or ulw) in your prompt.

That's it. Parallel agents, background tasks, deep exploration, relentless execution until completion. The agent figures out the rest.

---

Quick Start

Install (Recommended)

bunx opencode-matrixx install

Or for non-interactive setup (CI/agents):

bunx opencode-matrixx install --no-tui --claude=yes --openai=yes --gemini=no --copilot=no

Verify Installation

bunx opencode-matrixx doctor

Configure

Create matrixx.jsonc in your project root:

{
  "$schema": "https://raw.githubusercontent.com/klpanagi/opencode-matrixx/refs/heads/dev/dist/matrixx.schema.json",
  "agents": {}
}

Use

Open OpenCode and start coding. Matrixx activates automatically.

For LLM agents — paste this into Claude Code, AmpCode, Cursor, or any LLM agent:

Install and configure matrixx by following the instructions here:
https://raw.githubusercontent.com/klpanagi/opencode-matrixx/refs/heads/dev/docs/guide/installation.md

Installation guide → . Uninstall → . CLI reference →

---

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

The one who sees the code for what it truly is.

Role: Master orchestrator and strategic coordinator

Model: Claude Opus 4.6 · temperature: 0.1

Plans, delegates, and executes. Fires background agents in parallel, leverages LSP and AST-Grep for surgical refactoring, and never stops until the TODO list is empty. Morpheus sees the code for what it truly is — and routes every task to the agent best suited for it.

---

02. Keymaker — The Craftsman

Give him a goal, not a recipe.

Role: Autonomous deep worker

Model: GPT 5.3 Codex · temperature: 0.1

Explores the codebase, matches your patterns, and delivers end-to-end. Keymaker doesn't need step-by-step instructions — give him a destination and he'll find the path, writing production-quality code along the way.

---

03. Cipher — The Language Architect

Grammars, parsers, and the art of formal languages.

Role: DSL engineering specialist

Model: Claude Sonnet 4.6 · temperature: 0.1

Grammars, parsers, type systems, code generators, metamodels. 11 composable skills covering textX, ANTLR4, tree-sitter, PyEcore, and more. If it involves defining a language or transforming code, Cipher is your specialist.

---

04. Sentinel — The Security Auditor

Reads every line. Changes nothing. Reports everything.

Role: Read-only security specialist

Model: Claude Sonnet 4.6 · temperature: 0.1

Scans for vulnerabilities but never touches code. OWASP Top 10, SAST, DAST, dependency CVEs, secret detection, crypto audit, infrastructure hardening. 9 composable security skills. Sentinel reports findings with CWE IDs, exact locations, and actionable remediation.

---

05. Sati — The Frontend Specialist

Crafts stunning UI/UX, even without design mockups.

Role: Frontend specialist

Model: Claude Sonnet 4.6 · temperature: 0.1

React/Next.js, Svelte/SvelteKit, accessibility, performance, design tokens, component architecture, build tooling. Sati ships production-grade UI work with browser verification via Playwright. Invoke directly with @sati/ or task(subagent_type="sati") for any non-trivial frontend task.

---

06. Oracle — The Plan Builder

Architecture demands precision. Oracle delivers it.

Role: Strategic planning, architecture decisions, work plan generation

Model: Claude Sonnet 4.6 · temperature: 0.1

Creates detailed, structured work plans from complex requests. Decomposes ambiguous requirements into atomic, verifiable steps with clear success criteria. Oracle builds the plan — Morpheus executes it.

---

07. Merovingian — The Consultant

High-IQ reasoning for problems that refuse to yield.

Role: High-IQ consultation, hard debugging, architecture design

Model: Claude Sonnet 4.6 · temperature: 0.1

Read-only consultation for hard debugging (after 2+ failed attempts), multi-system tradeoffs, and architecture decisions requiring deep reasoning. Merovingian analyzes — never implements.

---

08. Architect — The Master Orchestrator

Where plans become reality.

Role: Plan execution orchestrator, session coordination

Model: Claude Sonnet 4.6 · temperature: 0.1

Executes Oracle's work plans, coordinates session state, manages task dependencies, and ensures every phase completes before moving to the next. The Architect is the bridge between planning and shipping.

---

09. Seraph — The Pre-Planner

Sees what others miss before work begins.

Role: Pre-planning analysis, ambiguity detection, AI failure prevention

Model: Claude Opus 4.6 · temperature: 0.3

Analyzes requests to identify hidden intentions, ambiguities, scope creep, and AI failure points. Seraph intervenes before planning starts — preventing costly mistakes downstream.

---

10. Smith — The Validator

Every plan meets Smith's standards — or gets rewritten.

Role: Plan validation, completeness review, gap detection

Model: Claude Sonnet 4.6 · temperature: 0.1

Evaluates work plans against rigorous clarity, verifiability, and completeness standards. Catches gaps, ambiguities, and missing context before implementation begins. Smith is the last line of defense.

---

11. Operator — The Researcher

Finds what you need, where it lives.

Role: External documentation, OSS search, library research

Model: Claude Haiku 4.5 · temperature: 0.1

Specialized codebase understanding agent for multi-repository analysis, searching remote codebases, retrieving official documentation, and finding implementation examples using GitHub CLI, Context7, and Web Search.

---

12. Trinity — The Search Engine

Finds anything, anywhere, instantly.

Role: Blazing fast codebase grep, pattern discovery

Model: Claude Haiku 4.5 · temperature: 0.1

Contextual grep for codebases. Answers "Where is X?", "Which file has Y?", "Find the code that does Z". Fires multiple in parallel for broad searches. Quick, medium, or very thorough — you choose.

---

13. Construct — The Media Analyst

Sees what's inside — images, PDFs, diagrams.

Role: PDF, image & diagram analysis

Model: Claude Sonnet 4.6 · temperature: 0.1

Analyzes media files that require interpretation beyond raw text. Extracts specific information or summaries from documents, describes visual content. Use when you need analyzed/extracted data rather than literal file contents.

---

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 →

---

Features

	Agent Orchestration
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
Curated MCPs	Exa (web search), Context7 (official docs), Grep.app (GitHub code search), Document Reader
Claude Code Compat	Full compatibility — commands, agents, skills, MCPs, hooks from settings.json
Software Dev Pipeline	6-phase TDD workflow (PLAN→BUILD→VERIFY→REVIEW→SECURE→SHIP), 5 team roles, adaptive phases
	Saturation Research
	AI Slop Detection

Full feature list → · Configuration guide → · Architecture diagram →

---

Software Development Pipeline

Matrixx includes a structured 6-phase development pipeline that coordinates specialized roles through PLAN → BUILD → VERIFY → REVIEW → SECURE → SHIP. Each phase has clear entry/exit criteria and is enforced by dedicated agents.

Team Roles

Role	Agent	Skills	Purpose
Architect	Oracle (Claude Opus)	—	System design, architecture decisions, task breakdown
Developer	Source category	git-master, tdd-enforcer	Implementation code with TDD
Tester	Source category	tdd-enforcer, quality-gate	Test authoring, coverage, verification
Quality Evaluator	Red-pill category	quality-gate, review-work	Lint, typecheck, 5-agent code review
Security Expert	Sentinel (Claude Opus)	security-core, security-sast, security-api, security-dependencies	Vulnerability scanning, CVE checks

Pipeline Phases

Phase	Skip?	Role	Exit Criteria
PLAN	Small tasks	Architect	Approach defined, files listed, edge cases documented
BUILD	Never	Developer	TDD (RED→GREEN→REFACTOR), bun test passes
VERIFY	Never	Quality	lint + typecheck + test + build — all pass
REVIEW	Small tasks	Quality (5-agent)	All reviewers PASS, no CRITICAL/MAJOR issues
SECURE	Small + non-security	Security	No CRITICAL/HIGH findings, dependencies checked
SHIP	Never	Developer	Atomic commits, PR to dev, CI passes

Task Size Adaptivity

Size	Files	Phases Used
Small	1-2	BUILD → VERIFY → SHIP
Medium	3-10	PLAN → BUILD → VERIFY → REVIEW → SHIP
Large	10+	ALL 6 PHASES
Security-related	Any	Always includes SECURE

Load the software-dev skill to activate the pipeline. The orchestrator automatically selects the right roles and phases based on task scope.

---

Security

Matrixx includes a three-tier security layer: reactive hooks, configurable policies, and a dedicated security auditing agent.

Enforcement Hooks

Built-in hooks protect against accidental secret exposure — no setup required.

Hook	What it does
Secret Leak Guard	Intercepts git commit and git push, runs gitleaks on staged changes, and blocks the operation if secrets are detected.
Env File Write Guard	Blocks agents from writing to sensitive files (.env, *.pem, *.key, credentials.json, id_rsa, and 16 other patterns).

Both hooks are enabled by default and run before all other hooks in the execution pipeline. Configure via matrixx.jsonc:

{
  "security": {
    "secret_scanning": { "enabled": true, "block_on_detection": true },
    "env_file_guard": { "enabled": true, "allowed_paths": [".env.example"] }
  }
}

Note: Secret scanning requires gitleaks installed in your PATH. Without it, the hook silently degrades.

Sentinel — Security Auditing Agent

Sentinel is a read-only security specialist with 9 composable skills covering the full application security stack:

Skill	Domain
security-core	OWASP Top 10, CWE classification, threat modeling (STRIDE)
security-secrets	Secret detection, credential scanning, pre-commit hooks
security-sast	Static analysis, code vulnerability patterns, taint tracking
security-dast	Dynamic analysis, runtime testing, fuzzing, penetration testing
security-dependencies	CVE scanning, SBOM generation, supply chain security
security-api	Authentication, authorization, CORS/CSRF, input validation
security-crypto	Encryption audit, key management, TLS, password hashing
security-infra	Container scanning, Dockerfile hardening, IaC audit, K8s security
security-review	Structured audit reports, severity classification, remediation guidance

Sentinel never modifies code — it reports findings with CWE IDs, exact locations, and actionable remediation. Any agent can load individual security skills via load_skills.

---

RTK Integration — Token Compression

Matrixx integrates 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:

{
  "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:

# 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

Overview	What Matrixx does, workflows, getting started
Agents Deep Dive	Full agent descriptions, skills, workflows, example prompts
Architecture	System diagrams, delegation flows, model routing
Features	Complete feature reference
Configuration	All config options, agent overrides, hooks, categories
Orchestration	How agents coordinate, delegate, and recover
Categories & Skills	Task categories, skill injection, delegation patterns

---

If this saves you time, a ⭐ goes a long way.

_{Productivity might spike too hard. Don't let your coworker notice. Actually — let's see who wins.}