Introduction

matcha is an engineering philosophy for AI coding agents. It makes agents think before they code — checking purpose, reusing existing code, auditing the stack, and reviewing before shipping.

How It Works

matcha operates at 4 layers:

Who Is It For?

Key Features

What's Inside

Example: Before vs After matcha

Quick Start

Up and running in 2 minutes.

npx @plumpslabs/matcha@latest initCopy

npm install -g @plumpslabs/matcha && matcha initCopy

curl -fsSL https://raw.githubusercontent.com/plumpslabs/matcha/main/install.sh | bashCopy

cp .agents/skills/matcha/modules/project.md ./MATCHA_PROJECT.md
# Edit with your framework, package manager, coding standardsCopy

ls AGENTS.md GEMINI.md hooks/matcha-shield.js
# All three must exist — matcha is now active for every agent.Copy

Installation

Multiple ways to install matcha depending on your setup.

Option A: npx — one command, nothing installed globally

npx @plumpslabs/matcha@latest initCopy

npx downloads matcha temporarily, runs init into the current project, then discards it. No global install, no cleanup. Re-run any time to update.

During init, matcha asks which providers to configure (1 Claude · 2 OpenCode · 3 Cursor · 4 Windsurf · 5 Kiro · 6 Universal). Existing providers are auto-detected. For scripting: matcha init --platforms .opencode,.claude

Option B: Global install — matcha command works everywhere

npm install -g @plumpslabs/matcha
matcha init        # install matcha rules into the current project
matcha status      # verify + show platform detectionCopy

The matcha CLI is available in every project. Run matcha init in each project you want to enable.

Option C: Project-local dev dependency — pinned per repo

npm install --save-dev @plumpslabs/matcha
npx matcha initCopy

Scoped to one project via package.json. Best for teams — the matcha version is locked with the code.

Option D: One-liner — no npm required

curl -fsSL https://raw.githubusercontent.com/plumpslabs/matcha/main/install.sh | bashCopy

Pure shell script, works on macOS / Linux / WSL. Installs the rules files only (no CLI).

Which one should I use?

What Gets Installed

Claude Code Setup

matcha works natively with Claude Code via plugin marketplace or manual setup.

Method 1: Plugin Marketplace

# Inside Claude Code
/install matchaCopy

Method 2: npm install

npx @plumpslabs/matcha@latest initCopy

Method 3: Curl script

curl -fsSL https://raw.githubusercontent.com/plumpslabs/matcha/main/install.sh | bashCopy

ls AGENTS.md .claude/skills/matcha/SKILL.md
# Should show both files — Claude Code is configured ✅Copy

MCP Configuration (Optional)

Add matcha MCP tools for additional enforcement:

{
  "mcpServers": {
    "matcha": {
      "command": "node",
      "args": ["hooks/matcha-mcp-server.js"]
    }
  }
}Copy

Place in .mcp.json (per-project) or ~/.claude.json (global).

OpenCode Setup

matcha auto-detects OpenCode and configures agents + skills.

npx @plumpslabs/matcha@latest initCopy

MCP Configuration

OpenCode's mcp schema requires command to be an array (executable + args together).

Per-project

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "matcha": {
      "type": "local",
      "command": ["node", "hooks/matcha-mcp-server.js"],
      "enabled": true
    }
  }
}Copy

Place in opencode.json / opencode.jsonc in the project root.

Global (all projects) — no absolute path needed

npm install -g @plumpslabs/matcha
# Then in ~/.config/opencode/opencode.json:
{
  "mcp": {
    "matcha": {
      "type": "local",
      "command": ["matcha", "mcp"],
      "enabled": true
    }
  }
}Copy

matcha mcp resolves via your global PATH — works from any project, nothing to update when you switch directories. (Fallback: absolute path ["node", "/path/to/matcha/hooks/matcha-mcp-server.js"] if the CLI isn't installed globally.)

Cursor Setup

matcha works with Cursor via AGENTS.md (native) and optional MCP.

npx @plumpslabs/matcha@latest initCopy

MCP Configuration (Optional)

{
  "mcpServers": {
    "matcha": {
      "command": "node",
      "args": ["hooks/matcha-mcp-server.js"]
    }
  }
}Copy

Place in .cursor/mcp.json (per-project) or ~/.cursor/mcp.json (global).

Windsurf Setup

matcha works with Windsurf via .windsurfrules.

npx @plumpslabs/matcha@latest initCopy

MCP Configuration

{
  "mcpServers": {
    "matcha": {
      "command": "node",
      "args": ["hooks/matcha-mcp-server.js"]
    }
  }
}Copy

Place in ~/.codeium/windsurf/mcp_config.json (global only).

agy (Antigravity) Setup

matcha works with agy (Antigravity CLI) via plugin install.

Method 1: Plugin Install

agy plugin install https://github.com/plumpslabs/matchaCopy

Method 2: npm install

npx @plumpslabs/matcha@latest initCopy

Method 3: Curl script

curl -fsSL https://raw.githubusercontent.com/plumpslabs/matcha/main/install.sh | bashCopy

What Gets Installed

The repo ships an AGY-compatible plugin manifest (plugin.json) plus root agents/ and mcp_config.json so agy plugin install picks up everything:

• skills/ — 1 skill (matcha) → usable via /matcha
• commands/ — 7 commands → converted to skills (matcha:review, matcha:why, ...)
• agents/ — 6 agents: 4 selectable in the /agents panel (planner, finder, auditor, reviewer) + 2 subagent-only (debugger, cleaner)
• mcp_config.json — matcha MCP server auto-registered
• GEMINI.md + AGENTS.md — rules files (read automatically)

Using matcha agents

AGY discovers the 6 matcha agents from .agents/agents/ (project) and the plugin's agents/ dir. Verify with:

agy agent          # list discovered agents (4 primary shown)
agy --agent matcha-planner "plan feature X"   # one-shot, no TUICopy

Kiro Setup

matcha works with Kiro via steering files in .kiro/steering/.

npx @plumpslabs/matcha@latest initCopy

MCP Server Setup

matcha exposes 4 tools via MCP (Model Context Protocol) for any compatible client.

Available Tools

What Is This For?

MCP (Model Context Protocol) lets any AI agent call matcha's checks as tools — deterministic enforcement that doesn't depend on the agent reading rules. It's optional: the rules files (AGENTS.md, skills, commands) work without it. MCP adds a second, programmatic layer for agents that support tool calls (Claude, Cursor, Windsurf, AGY, OpenCode, ...).

Start the Server

Locally (project hooks dir):

node hooks/matcha-mcp-server.js
# Runs via stdio JSON-RPCCopy

Or via the globally installed CLI (works from any project):

npm install -g @plumpslabs/matcha
matcha mcpCopy

Client Configuration

Each client has a different config format:

Global config tip: use "command": "matcha", "args": ["mcp"] (global CLI) — no absolute path, works after switching projects. Absolute path to hooks/matcha-mcp-server.js is only needed if the CLI isn't installed globally.

Philosophy

Simple. Efficient. Deliberate. Never twice.

The 6-Checkpoint Filter

Every implementation passes through 6 checkpoints:

Core Principles

• No hardcoded values — use env vars: APPNAME_VAR_NAME
• One function = one responsibility — pure functions first
• Prefer stdlib — 3 use cases minimum before abstracting
• Fail fast — validate inputs at boundaries
• Idempotent — operations safe to retry
• No empty catches — explicit error paths

Context-Aware Modes

matcha auto-detects what the agent is doing and adjusts behavior.

Modes are detected automatically from tool input. No manual switching needed.

Risk-Based Review

Not all code needs the same review. Route by risk.

Risk Tiers

Trigger Packs

matcha does NOT hardcode what "high risk" means. Detection uses domain-specific trigger packs:

See hooks/matcha-trigger-packs.json for all packs and custom template.

L2 Full Review Categories

Planning Gate

Blocks code modifications until an Intent Discovery plan exists.

Smart Auto-Skip

Planning gate is automatically skipped for:

• Read-only commands (git status, grep, ls)
• Test commands (npm test, vitest)
• Lint/format commands (eslint, prettier)
• Documentation files (.md, .txt)
• Test files (.test.js, .spec.ts)

Plan Format

<matcha_gate>
  <what>Describe what you are building/fixing — with file refs</what>
  <why>Why is this necessary? — with evidence</why>
  <how>Simplest implementation path — numbered steps</how>
</matcha_gate>Copy

Validation Rules

• <what> must reference specific files
• <why> must include evidence (metrics, errors)
• <how> must list 2+ concrete steps
• Each section must be 15+ characters

Proportionality & Trivial Fast-Pass

Match ceremony to risk. The gates exist to protect — not to slow you down. Over-analysis is not rigor; it is waste.

Trivial Plan Marker

For trivial tasks, write a minimal plan carrying the <!-- trivial --> marker (or type: plan-trivial in frontmatter) plus a **Problem:** line — the hook accepts it without the full What/Why/How gate. Without the marker, the hook still requires Problem + Goals + Success Criteria.

<!-- trivial -->
# 🍵 Intent Discovery
- **Problem:** Rename `foo` to `bar` in src/x.jsCopy

What Skips the Gate Automatically (Smart Auto-Skip)

• Commands: read-only (git status, grep, ls), tests (npm test, vitest), lint/format (eslint, prettier), package managers
• Files: docs (.md), tests (.test.js), config & low-risk data (.yaml, .jsonc, .css, .html, .env*, .lock, tsconfig, Dockerfile), matcha session files (current.md)
• Never skipped: dependency manifests (package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile), component source (.vue, .svelte), production code — these change logic or the dependency tree

Exit Conditions Beat STOP

Before stopping to ask the user, ask: is this actually blocking, or can I proceed on a recorded assumption? Prefer proceeding with a visible assumption over blocking on trivia. Record assumptions in the plan's Assumptions field so they survive context compaction.

Project Constraints

matcha supports project-specific rules that agents must follow.

Setup

cp .agents/skills/matcha/modules/project.md ./MATCHA_PROJECT.mdCopy

Template Sections

• Stack: Framework, language, package manager
• Conventions: Naming, imports, error handling
• Architecture: Layers, patterns, anti-patterns
• Testing: Framework, coverage requirements
• Security: Auth, secrets, validation rules

Session Memory

Filesystem is durable memory; the context window is volatile. matcha persists gate artifacts so a compacted or fresh session resumes in under 500 tokens.

Rules

• Lazy-load only — never auto-inject memory files into context; read on demand. Zero token bloat.
• Living over archive — current.md overwrites, never appends. Reports append monthly; keep latest 5 per agent, delete older.
• Format — YAML frontmatter (title, date, type, agent, status, tags): grep-able, git-friendly, industry standard (same as ADRs & memory banks).
• Enforced permissions — planner/finder/reviewer/auditor are provider-enforced read-only (edit denied for all source code; writable paths only: .agents/plan/current.md for planner + reviewer, .agents/reports/** for planner/reviewer/auditor). Bash permissions: planner/finder get a lean read-only allowlist (git history, rg/find search, wc -l, head/tail) and block everything else (*: deny) — file contents are read via the read tool, not bash cat/sed. Auditor gets a read-only allowlist (git history, package managers, test runners, filters) with *: deny fallback — build commands are not allowlisted (they write dist/; blocked so subagents never stall on approval prompts — the orchestrating agent runs builds). Reviewer keeps full bash because its L0/L1 gates must run builds and tests. Web fetching stays denied for all (opencode webfetch is scalar-only); advisory lookups go through the orchestrating agent. debugger/cleaner may modify code.
• Gate artifacts only — persist plan/review/audit (they gate shipping). Skip finder/cleaner/debugger — cheaper to re-run than to archive.

Lifecycle (anti-stale)

current.md always holds exactly one active task:

1. Start — read it. Intent matches the current request? Continue and update in place. Mismatch → overwrite (never follow a stale plan).
2. During (step-by-step) — implement strictly in order from the Plan list: after each completed step check it off ([x]) and update the **▶ Current:** line (Step N/M, K done). Overwrite / check-off in place, never append. The plan always reflects the real position — a compacted or fresh session resumes exactly where you left off. Deviation → update the plan first.
3. Done (task ships = review PASS) — the reviewer finalizes the handoff: append plan content to reports/planner-<YYYY-MM>.md, write the verdict to reports/reviewer-<YYYY-MM>.md, then reset current.md to the empty template (status: active, TBD). Only a PASS resets — BLOCK / PASS_WITH_FIXES keeps the plan for fix iteration.

Portable across providers — .agents/plan/ + .agents/reports/ are plain files in the project, readable by any provider (OpenCode, AGY, Claude, Cursor, …). Switch provider mid-task? The new session injects AGENTS.md → reads current.md → resumes. The filesystem is the memory; the provider is just the host.

Workflow Guide (The 4-Phase Lifecycle)

How to actually use matcha day-to-day: which agent or command to call, when, and in what order — from a blank task to a reviewed, shippable change.

End-to-End Flow Diagram

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Phase 1: PLAN  │ →  │ Phase 2: SEARCH │ →  │ Phase 3: CODE   │ →  │  Phase 4: SHIP  │
│  @matcha-planner│    │  @matcha-finder │    │  Main agent     │    │ /matcha:review  │
│  (/matcha:why)  │    │  (Reuse Check)  │    │ (verify + debug)│    │ @matcha-cleaner │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘

Implementasi dilakukan oleh main agent (bukan sub-agent) — mengikuti plan di .agents/plan/current.md step-by-step. @matcha-debugger hanya dipanggil jika terjadi error, dan @matcha-finder bisa dipanggil ulang saat menemukan kode yang bisa di-reuse.

When to Call What

Mode by Situation

Commands Reference

7 slash commands for matcha workflows.

Note: /matcha:status now surfaces session metrics (planning-gate blocks, shield blocks, reviews run, issues caught, FP rate) when .agents/matcha-metrics.json exists — so matcha can measure its own overhead.

CLI Reference

Run matcha <command> after installing via npm (or node bin/matcha.js <command> from the repo). All commands resolve state at the workspace root (monorepo-aware).

Agents Reference

6 specialized agents for matcha workflows.

Read-only agents (planner/finder/reviewer/auditor) have provider-enforced edit: deny (OpenCode) / disallowedTools: Write, Edit (Claude Code) — they can never modify source code. Only plan/report paths are writable. debugger/cleaner may modify code.

Provider note: enforced in OpenCode (permission:) and Claude Code (disallowedTools:). Other providers (agy, Cursor, Windsurf) read the same agents as prompts — enforcement there is prompt-level + safety hooks.

Hooks Reference

4 lifecycle hooks for deterministic enforcement.

Override

MATCHA_SHIELD_OFF=true  # Disable all shield checksCopy

Modules Reference

6 focused modules loaded on-demand.

Benchmark & Evidence

Matcha ships its own benchmark tooling (benchmark/) and publishes results — so the claim "rules improve output without bloating it" is measured, not asserted.

Complex-Task Benchmarks (v3) — where a thinking-first agent earns its cost

First run (free model, n=1–2/cell, 2026-08-08): the arena matcha was built for — and the arms split hard.

Honest reading: without rules the agent fails the multi-file refactor — it adds a few lines and stops; matcha is the only arm that extracts the service layer without breaking behavior. The table shows completed cells: matcha's second refactor cell and several security cells hit the free-model queue timeout (the same security task passed at 240s in an isolated dry-run), so its 1/1 is not cherry-picking. On the small security bug every arm that finished fixed it — no measurable edge for matcha there. Defect density only counts completed work: a 3-line no-op has no density to measure.

Quality metric: defect density — anti-pattern findings (empty catches, magic numbers, hardcoded secrets) per 100 LOC added by the agent, scanned via hooks/patterns.json. This is the value side of the ledger: baseline writes few, sloppy lines; matcha writes more, cleaner lines. Re-run: node benchmark/live-bench.js --task refactor-users-service --arm matcha --n 5 --timeout 480.

Small-Task Benchmarks (18 runs) — the cost of thinking first

Real feature implementation on the express-api fixture (3 features × 3 arms × 2 iterations). This is matcha's worst case: trivial single-file tasks. Process cost (tokens, steps, wall time) is measured from real provider events, not estimated. Lower is better for every chart except Correctness.

Median per arm · data as of 2026-08-07 (re-run: node benchmark/live-bench.js --all --n 5, then update docs/benchmark.json + this chart) · details in docs/BENCHMARK.md. Cost is the invoice for the quality shown above — not a defect.

Why matcha costs more — the mechanism: the extra tokens and time are mostly process steps, not code bloat. Matcha adds ~4 LLM turns per task (steps 8.5 → 12.5), which typically go to the planning gate (write a plan with evidence before touching files), verification (run the test suite), and the review pass. Each extra turn re-reads context — that's the ~49K cacheRead/step we measured. On small tasks those turns buy nothing visible — hence "overkill by design". On complex tasks they are exactly what turns a 0/2 failure into a completed, verified refactor.

Honest takeaway: cost (tokens/time) is context, not the verdict. Matcha spends more because it thinks before it implements — that buys precision, structure, and prevention. The quality side is why the cost is worth paying: defect density (anti-pattern findings per 100 LOC added, scanned on agent-written files only), correctness, and safe complex refactors. On small/trivial tasks matcha is overkill by design — Proportionality routes them through the ≤30-line fast path and the trivial plan; use /matcha:intensity observe for trivia.

So is matcha "slow and expensive"? Read the cost table as an invoice for verification, not a waste report: the same kind of process turns — planning and verification — that cost +63% on trivial tasks are the ones that completed a refactor every other arm abandoned. And the premium is capped by design — trivial edits skip the gate entirely (≤30-line fast path) and observe mode removes it altogether. You only pay the premium where you choose to — and it buys what no-rules arms never produce: a completed, verified result on the work that actually matters.

Real Multi-Turn Feature Benchmark (agy, 3 features)

Matcha-driven feature builds on agy (Gemini 3.5 Flash): 3 real features, all tests green, top compliance grade. The same-prompt with/without comparison lives in docs/BENCHMARK.md — matcha produced named status codes, explicit errors, and a per-user data structure at ~16% more LOC.

Legacy / internal runs. Agentic A/B (Claude Code, 20 tasks × 3 arms): all arms tied at 13/20 correct — matcha wrote 260 LOC vs 347 no-rules via reuse/no-duplication, but this benchmark doesn't differentiate. Standing-context A/B (20 cells, core-only vs full): −6.3% tokens median, within run-to-run noise — the slim is correct-by-architecture (~1.5K tok/step) but standing context is dominated by AGENTS.md + hooks + system prompt, not skill modules. Full write-ups in docs/BENCHMARK.md.

Which feature to use when

Rough rule: bigger than a one-file edit, or production-critical → matcha earns its keep. Everything else → fast path + observe keeps it out of the way.

Run It Yourself

Every published number is re-runnable — the harness ships in benchmark/:

node benchmark/live-bench.js --all --n 5        # full A/B: 6 tasks × 3 arms (headless opencode, tokens+time)
node benchmark/live-bench.js --task refactor-users-service --arm matcha --n 5 --timeout 480   # complex-task run
node benchmark/matcha-bench.js ./src            # compliance scan of your code
node benchmark/agentic-runner.js --simulate     # deterministic smoke test, no Claude neededCopy

Complex tasks run 200s+ per cell on free models — pass --timeout 480 for refactor/security tasks. Full methodology in docs/BENCHMARK.md.

Architecture

Layered by design. Each layer does one thing.