🍵 matcha

Simple. Efficient. Deliberate. Never twice.

Engineering philosophy for AI coding agents.
6 modules · 7 commands · 6 agents · 7 hooks · 1 MCP server

---

What is matcha?

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

Without matcha: Agent jumps in, writes code, realizes mid-way something was wrong.

With matcha: Agent stops, asks "why?", searches for existing solutions, then implements deliberately.

The 6-Checkpoint Filter

Every implementation passes through:

🎯 Purpose → 🔎 Reuse → 🔍 Stack → 🛠️ Implementation → 🧹 Cleanup → ✅ Verify → 🔒 Review

#	Check	What it prevents
🎯	Purpose + Reuse	Building the wrong thing, duplicating existing code
🔍	Stack	Adding overlapping dependencies
🛠️	Implementation	Over-engineering, hardcoding
🧹	Cleanup	Shipping debug code, temp files
✅	Verify	Shipping broken code
🔒	Review	Shipping bad patterns, security issues

---

Quick Start (2 minutes)

Option A: One-liner (any agent)

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

Auto-detects your platform and installs the right files.

Option B: Claude Code Plugin

/plugin marketplace add https://github.com/plumpslabs/matcha
/plugin install matcha@plumpslabs-matcha

Option C: From cloned repo

git clone https://github.com/plumpslabs/matcha.git
cd matcha
node bin/matcha.js init

Verify

node bin/matcha.js status

---

Project Constraints

matcha now supports project-specific rules — things the agent must know that can't be inferred from reading code.

Create MATCHA_PROJECT.md in your project root:

# Project Constraints

### Example `MATCHA_PROJECT.md` (Auto-generated per project)

```markdown
# 🍵 MATCHA_PROJECT.md — Project Constraints

## 1. Stack & Architecture
- **Language / Ecosystem:** Polyglot (Rust / Go / Python / Java / JS)
- **Architecture Pattern:** Pure Core Logic, High Cohesion, Low Coupling

## 2. Verification Commands
- **Typecheck / Lint:** [native project check command]
- **Test Suite:** [native project test command]
- **Build Target:** [native project build command]

Keep it under 80 lines. Only rules that surprise new developers.

---

Usage

Daily Flow (The 4-Phase Lifecycle)

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Phase 1: PLAN  │ →  │ Phase 2: SEARCH │ →  │ Phase 3: CODE   │ →  │  Phase 4: SHIP  │
│  @matcha-planner│    │  @matcha-finder │    │ @matcha-debugger│    │ /matcha:review  │
│  (/matcha:why)  │    │  (Reuse Check)  │    │ (Systematic Fix)│    │ @matcha-cleaner │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘

1. Phase 1: Plan & Intent — @matcha-planner or /matcha:why (Intent Discovery)
2. Phase 2: Search & Reuse — @matcha-finder (hunt existing code file:line)
3. Phase 3: Code & Debug — Follow 8-Pillar Directives + @matcha-debugger if stuck
4. Phase 4: Review & Ship — /matcha:review (blocking L0-L3 gate) + @matcha-cleaner

Minimal cheat-sheet: plan → reuse → implement → review. Everything else is automatic or optional. Full step-by-step guide with example prompts lives in the Workflow Guide.

Commands

Command	Purpose
/matcha:toggle	Toggle governance on/off instantly (
/matcha:on	Enable matcha governance & safety checks
/matcha:off	Pause governance & planning gate (free mode)
/matcha:why	Intent Discovery — answer before coding
/matcha:review	Blocking review gate — 9 categories
/matcha:audit	Stack health — overlaps, waste, security
/matcha:intensity	Set level: observe / enforce / audit
/matcha:status	Session dashboard
/matcha:debt	Technical debt from // matcha: markers
/matcha:markers	Scan markers by severity

Agents

Agent	Role
@matcha-planner	Plan through checkpoints (read-only)
@matcha-finder	Hunt existing code before writing
@matcha-auditor	Stack audit for overlaps
@matcha-reviewer	Review gate — blocks bad code
@matcha-cleaner	Remove temp/debug/unused
@matcha-debugger	Systematic debugging

🔒 Enforced permissions (OpenCode permission: + Claude Code disallowedTools:): planner/finder/reviewer/auditor are read-only — edit is denied for all source code. Only plan/report files are writable (.agents/plan/current.md, .agents/reports/**). debugger/cleaner may modify code. Other providers: prompt-level + hooks.

Intensity Levels

Level	Behavior
observe	Tips only. No blocking.
enforce	Full filter + review gate. Default.
audit	Enforce + mandatory cleanup.

Session Memory (survive context loss)

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

File	Write	Read
.agents/plan/current.md	Planning gate → overwrite (living plan)	Start of every task
.agents/reports/<agent>-<YYYY-MM>.md	Review/Audit output → append	Resuming or auditing history
.agents/plan/decisions.log	matcha decision <type> <reason>	matcha markers / /matcha:debt

• Lazy-load only — memory files are never auto-injected into context; read on demand.
• Lifecycle (anti-stale) — current.md holds one active task: intent mismatch at start → overwrite; done (review PASS) → reviewer archives to reports/planner-<YYYY-MM>.md + resets to empty template. Only PASS resets — BLOCK / PASS_WITH_FIXES keeps the plan for fix iteration.
• Living over archive — current.md overwrites, never appends. Reports append monthly; keep latest 5 per agent.
• Format: YAML frontmatter (title, date, type, agent, status, tags) — grep-able, git-friendly.

---

MCP Server

matcha ships an MCP server for cross-platform use. It exposes matcha's checks as tools any MCP-capable agent can call (Claude, Cursor, Windsurf, AGY, OpenCode, Cline, Roo). Optional — the rules files work without it; MCP adds deterministic, programmatic enforcement.

Setup (per-project)

Add to your MCP client config (Claude/Cursor/Windsurf/AGY format):

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

OpenCode uses a different schema — command must be an array:

{
  "mcp": {
    "matcha": {
      "type": "local",
      "command": ["node", "hooks/matcha-mcp-server.js"],
      "enabled": true
    }
  }
}

Setup (global, no absolute path)

Install the CLI once, then reference it — works from any project:

npm install -g @plumpslabs/matcha
# Claude/Cursor/Windsurf/AGY:
#   "mcpServers": { "matcha": { "command": "matcha", "args": ["mcp"] } }
# OpenCode:
#   "mcp": { "matcha": { "type": "local", "command": ["matcha", "mcp"], "enabled": true } }

Tools

Tool	Purpose
matcha_shield_check	Check command for dangerous patterns
matcha_post_write_scan	Scan file for cleanup issues (13+ languages)
matcha_stop_tips	Generate tips from git diff
matcha_plan_validate	Validate Intent Discovery plan

Start manually

node hooks/matcha-mcp-server.js
# or
npm run mcp

---

Hooks

Hook	When	What it does
planning-gate.js	Before first edit	Blocks code until an Intent Discovery plan exists
matcha-shield.js	Before tool use	Blocks dangerous commands + mode detection
audit-log.js	Override / Toggle	Tamper-evident governance & override logging
blast-radius.js	Pre/Post edit	Dynamic risk scoring (L0-L3) based on git diff
evidence-collector.js	Verification	Captures empirical test exit codes (anti-theater)
matcha-post-write.js	After file write	Scans for debug code, secrets, empty catches
matcha-stop.js	Task complete	Generates tips from git diff
matcha-metrics.js	Session	Tracks session metrics
matcha-agy-hooks.js	Antigravity tool use	Routes agy tool names to gate decisions
matcha-instructions.js	Session start	Injects matcha rules into agent context

Platform Support

Platform	Integration
Claude Code	.claude/settings.json hooks
OpenCode	.opencode/plugins/matcha.js
Any MCP client	MCP server (see above)
Any platform	.agents/ universal format

---

Multi-Language Support

matcha checks work across 13+ languages:

JS · TypeScript · Go · Python · Rust · Java · C# · C/C++ · Ruby · Swift · PHP · Kotlin · Dart

Plus SQL queries and prose (markdown) writing quality.

---

Architecture

Source of Truth:
├── AGENTS.md                    ← Primary cross-tool file
├── skills/matcha/
│   ├── SKILL.md                 ← Router (references modules)
│   └── modules/
│       ├── core.md              ← 6-checkpoint filter + modes
│       ├── project.md           ← Project constraints (fill in once)
│       ├── modes.md             ← Context-aware mode switching
│       ├── risk.md              ← Risk-based review routing (L0-L3)
│       ├── engineering.md       ← Universal engineering bar (errors, logging, validation, API, state)
│       ├── legacy.md            ← Legacy code protocol

├── hooks/
│   ├── patterns.json            ← Multi-language pattern registry (13+)
│   ├── matcha-trigger-packs.json ← Domain-specific risk signals
│   ├── planning-gate.js         ← Planning gate enforcement (blocks edits before plan)
│   ├── danger-checks.js         ← Danger pattern detection (shield/planning support)
│   ├── mode-detect.js           ← Context-aware mode detection
│   ├── matcha-agy-hooks.js      ← Antigravity (agy) hook adapter
│   ├── matcha-mcp-server.js     ← MCP server (4 tools)
│   ├── matcha-shield.js         ← Safety gate + mode detection
│   ├── matcha-post-write.js     ← Cleanup enforcement
│   ├── matcha-stop.js           ← End-of-task tips
│   └── matcha-metrics.js        ← Session metrics tracking
├── commands/                    ← 7 slash commands
├── .agents/agents/              ← 6 agent definitions
├── agents/ · rules/ · mcp_config.json      ← AGY plugin package (agy plugin install)
└── plugin.json · .claude-plugin/ · gemini-extension.json  ← plugin manifests

Build System

npm run build          # Generate all platform adapters from source
npm run build:check    # Build + verify copies in sync

---

Companion Tools

• 🐻 Kuma — Runtime safety enforcement (MCP server)
• 🦊 Fennec — AI-native developer observability (MCP server)

The stack: matcha 🍵 (philosophy) + kuma 🐻 (safety) + fennec 🦊 (observability)

---

Benchmarks

npm run benchmark              # Compliance score
npm run benchmark:agentic      # A/B/C comparison (baseline vs terse vs matcha)
npm run benchmark:agentic-live # Live Claude Code sessions

---

Contributing

See CONTRIBUTING.md for guidelines.

npm test              # Run tests
npm run build         # Rebuild adapters
npm run build:check   # Verify everything in sync

---

License

MIT © plumpslabs

---

Simple. Efficient. Deliberate. Never twice.