MaruCheck
github.com/kidus-m/marucheck- Category
- Developer Tools
- Rank
- No. 1684Tools index
Previous survey · No. 1673 ·
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Software Testing & Quality
- Interfaces
- CLI · MCP · Agent Skill / Plugin
- GitHub
- 6 stars
- Latest release
- v0.5.0
- Date
About
MaruCheck is a local-first CLI that verifies AI-generated code changes against human-owned "Quality Contracts" the coding agent cannot edit, catching cases where a green test suite hides silently altered behavior (like a quota exploit). It runs deterministic risk scoring, mutation testing, and semantic drift detection, and exposes an MCP server so an agent can request—but not grant—its own verification verdict.
What it does
A command-line gate between a coding agent's edits and your merge. You write what the product must do in a plain YAML file, a named person approves it, and from then on each change is checked against that approved text instead of against tests the agent may have rewritten. It reads the Git diff, works out which approved rules the change touches, runs the project's existing test tools on just those, and writes the results to disk as files you can inspect. It also plugs into Claude Code so the agent cannot end its turn while the gate says no.
Why it's ranked here
MIT licensed, published on npm, and aimed at a failure most agent tooling ignores: the same model writing the code and grading it. The risk score is plain arithmetic over a fixed table, for example 30 points for touching billing and 25 for authorization, so every verdict arrives with a readable list of reasons. A missing test tool is reported as unavailable, never as a pass. It is young and built for Next.js, React and TypeScript repositories only, but the core design choices hold up under reading.
What's good
The approval step is real: drafts and proposed amendments stay advisory, and only an owner's sign-off makes a rule blocking. The agent hook gives up after three consecutive blocks, so a stuck gate hands control back instead of looping forever. Past bugs can be recorded with their regression tests, and when related code changes later those tests are pulled back into the plan; low-relevance history is kept but adds no risk. The bundled example reproduces the whole pitch in about a minute: a green suite, then a blocked change.
Tradeoffs
It declares Node 24 and npm 11 as minimums, which rules out many existing CI images. Linking a change to a contract is keyword overlap: words of four or more letters from changed file names and symbols compared against the contract text, minus a stop list. A change whose names share no words with the contract will not be linked to it. It orchestrates tools you already have (Vitest, Jest, Playwright, axe, Semgrep, Gitleaks) and does not install them, so coverage is only as wide as your setup.
How to use it well
Start with one feature that has burned you before, such as billing or access control, and write three or four observable rules for it. Pin the exact package in dev dependencies rather than fetching it on demand. Run it locally until the verdicts make sense, then add the agent hook, and only then the GitHub pull-request check. It does not write tests or judge code quality; it checks that approved behavior still has passing evidence. A project without an existing test suite will mostly see unavailable results.
Technical notes+
packages/risk/src/index.ts sums CLASSIFICATION_POINTS (billing 30, authorization 25, migration 25) with change-size and blast-radius bands, adds missing-contract (8) and tests-unchanged (7) reasons, and maps the 0-100 score through riskLevelForScore (low up to 24, moderate up to 49, high up to 74). matchContract intersects camelCase-split tokens of length 4 or more after stop-word removal. packages/planner/src/index.ts marks a requirement blocking only when the contract status is approved and it is listed in evidencePolicy.blockingRequirements; adapterSelectionsFor prefers vitest over jest and falls back to unavailable. packages/mcp-server/src/server.ts is a hand-written JSON-RPC stdio handler. package.json bundles the CLI with esbuild into one CommonJS file, with typescript as the sole runtime dependency.
Observed
- License
- MIT
- Language
- TypeScript, organised as an npm workspaces monorepo
- Packaging
- npm package exposing a maru binary built as a single bundled CommonJS file
- Interfaces
- CLI, stdio MCP server, Claude Code Stop hook, GitHub pull-request workflow installer
- Runtime dependencies
- typescript is the only declared runtime dependency
- Verification adapters
- Vitest, Jest, Playwright, axe, Semgrep, Gitleaks, manual review
- Contract format
- YAML Quality Contracts with requirements, invariants, edge cases and an evidence policy
Read from README.md, package.json, packages/cli/src/cli.ts, packages/core/src/index.ts, packages/risk/src/index.ts, packages/planner/src/index.ts, packages/evidence/src/index.ts, packages/mcp-server/src/server.ts, packages/contracts/src/index.ts, docs/guides/recommended-first-workflow.md, LICENSE, examples/contracts/subscription-management.yml.
What it can do
Verify AI-generated code diffs against versioned Quality Contracts
Code diff → Verification verdict
Run deterministic risk scoring on code changes
Code diff → Risk score
Perform mutation testing on code changes
Code diff → Mutation test results
Detect semantic drift between code behavior and approved behavior
Code diff → Drift report
Expose an MCP server allowing an agent to request a verification verdict without granting it
MCP request → Verification verdict
Block changes that pass tests but violate approved behavior
Code diff and Quality Contract → Pass/block decision
Tags
Tech Stack
Media
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.