Simple. Efficient. Deliberate. Never twice.
Anti-bloat engineering convention for AI coding agents.
Every AI coding session starts the same: jump in, write code, realize mid-way you missed something obvious. matcha is a 6-checkpoint filter that runs before, during, and after every implementation— catching the things you'd catch yourself if you stopped to think.
Minimum moving parts. One function = one thing. If it feels complex, it's wrong.
No filler. No dead code. Every line earns its place.
Think before you code. 5W1H check before starting. Explicit errors.
Search before you write. Reuse, don't rewrite.
Every implementation passes through these gates:
What/Why/Who/When/Where/How. Can't answer Why/How? → STOP.
Before writing: search codebase for existing implementations. Never write what already exists.
Scan manifests, services, deps. Overlap found? → STOP. Report.
No hardcode. Explicit errors. One function. "Is there a simpler path?"
Done = working AND clean. Temp files, debug code, unused imports. Decision log.
Auto-detect + run tests, typecheck, lint. Tests fail? → STOP and fix first.
Three ways to get matcha on your AI coding agent:
See QUICKSTART.md for the full guide · install.sh
Six specialized agents, each covering a checkpoint in the matcha filter:
| Agent | Checkpoint | Use Case |
|---|---|---|
| @matcha-planner | 🎯 Purpose | Plan features through 4 checkpoints |
| @matcha-finder | 🔎 Reuse | Hunt existing code before writing new |
| @matcha-auditor | 🔍 Stack | Stack audit for service overlap |
| @matcha-reviewer | 🛠️ + 🧹 + ✅ | Code review + verify tests passed |
| @matcha-cleaner | 🧹 Cleanup | Remove temp/debug/unused code |
| @matcha-debugger | 🎯 → ✅ | Systematic debugging |
| Command | Description |
|---|---|
| /matcha:status | Session status & component availability |
| /matcha:why | 5W1H check before starting |
| /matcha:audit | Stack audit for overlaps & inefficiencies |
| /matcha:review | Post-implementation review |
| /matcha:intensity | Set level: observe / enforce / audit |
| /matcha:debt | Show technical debt from decision logs |
From the cloned repository:
| Command | Description |
|---|---|
node bin/matcha.js status | Show version, platform, components, shield status |
node bin/matcha.js why | 5W1H interactive check (supports piped input) |
node bin/matcha.js audit | Quick project stack audit (manifests, CI/CD, Docker, env) |
node bin/matcha.js verify | Auto-detect test framework, run tests + typecheck + lint |
node bin/matcha.js init | Run install.sh from the cloned repo |
Run benchmarks from the repo:
| Command | Description |
|---|---|
npm run benchmark | Compliance scan on current project |
npm run benchmark:json | Compliance scan with JSON output |
node benchmark/generate-report.js | Full 3-arm agentic benchmark + report generation |
node benchmark/agentic-runner.js --simulate | Simulated benchmark using default solutions (no Claude required) |
node benchmark/agentic-runner.js --arm matcha | Single arm only (no Claude required) |
Invoke: @matcha-reviewer or /matcha:audit · Full reference in AGENTS.md
matcha ships 3 lifecycle hooks that enforce philosophy deterministically—no prompt engineering, no guessing.
Blocks dangerous commands before they reach the OS: rm -rf /, git push --force, DROP DATABASE, curl | bash, shutdown, mkfs, chmod 777 and more. Also implements the 5W1H planning gate in enforce mode.
Automatically scans modified files after every Write/Edit for cleanup issues: empty catch blocks (critical), hardcoded credentials, debug logs, TODO/FIXME left in code. Injects additionalContext for self-correction.
Scans git diff for real issues at session end. Reports: debug code, oversized functions, untracked files, import density. Deterministic—no LLM guesswork.
| Platform | Integration |
|---|---|
| Claude Code | .claude/settings.json — PreToolUse + PostToolUse + Stop hooks |
| OpenCode | tool.execute.before in matcha.mjs plugin |
| Qoder | hooks.json — before:tool_use event |
| Antigravity CLI | gemini-extension.json — tool lifecycle |
Learn more: Kuma (runtime safety) · Fennec (developer observability) · Architecture docs →
Planner · Finder · Auditor · Reviewer · Cleaner · Debugger
PreToolUse (shield) → PostToolUse (cleanup) → Stop (tips)
TypeScript, Go, Python, Java, PHP, React Native + common rules
Claude Code · OpenCode · Cursor · Windsurf · Cline · Kiro · Qoder · Qwen · Codebuff · Antigravity · OpenClaw · agy
20 coding tasks × baseline/terse/matcha. Correctness + Adversarial + LOC metrics.
Kuma blocks dangerous commands. Fennec gives AI browser + terminal visibility.
| Level | Behavior |
|---|---|
| observe | Tips only. No blocking. |
| enforce | Full 6-checkpoint filter. Default. |
| audit | Enforce + mandatory cleanup. Everything flagged. |