<h1 align="center">PMAT</h1>

<p align="center">

</p>

<p align="center">
<strong>Zero-configuration AI context generation for any codebase</strong>
</p>

<div align="center">

Installation | Usage | Features | Examples | Documentation

</div>

---

Table of Contents

- What is PMAT?
- Installation
- Usage
- Features
- Architecture

What is PMAT?

PMAT (Pragmatic Multi-language Agent Toolkit) provides everything needed to analyze code quality and generate AI-ready context:

- Context Generation - Deep analysis for Claude, GPT, and other LLMs
- Technical Debt Grading - A+ through F scoring with 6 orthogonal metrics
- Mutation Testing - Test suite quality validation (85%+ kill rate)
- Repository Scoring - Quantitative health assessment (0-289 scale, 11 categories)
- Git History RAG - Semantic search across commit history with RRF fusion
- Semantic Search - Natural language code discovery
- Compliance Governance - 30+ checks across code quality, best practices, and reproducibility
- Design by Contract - Toyota Way contract profiles with checkpoint validation and rescue protocols
- Autonomous Kaizen - Toyota Way continuous improvement with auto-fix and commit
- MCP Integration - 20 tools for Claude Code, Cline, and AI agents, validated end-to-end for concurrent multi-agent (ultracode) workflows
- Quality Gates - Pre-commit hooks, CI/CD integration, .pmat-gates.toml config
- 20+ Languages - Rust, TypeScript, Python, Go, Java, C/C++, Lua, Lean, and more

Part of the PAIML Stack, following Toyota Way quality principles (Jidoka, Genchi Genbutsu, Kaizen).

Annotated Code Search

<div align="center">

<p><em><code>pmat query "cache invalidation" --churn --duplicates --entropy --faults</code></em></p>
</div>

Every result includes TDG grade, Big-O complexity, git churn, code clones, pattern diversity, fault annotations, call graph, and syntax-highlighted source.

Installation

# Install from crates.io
cargo install pmat

> Note for macOS Users: If you experience issues installing via rustup, we recommend installing/updating Rust using Homebrew: brew install rust before running cargo install pmat.

Or from source (latest)

git clone https://github.com/paiml/paiml-mcp-agent-toolkit cd paiml-mcp-agent-toolkit && cargo install --path .

Usage

bash

Generate AI-ready context

pmat context --output context.md --format llm-optimized

Analyze code complexity

pmat analyze complexity

Grade technical debt (A+ through F)

pmat analyze tdg

Score repository health

pmat repo-score .

Pre-flight verify before committing (CI-faithful: fmt + complexity + satd + clippy + tests)

pmat verify --format json

Run mutation testing

pmat mutate --target src/

Start MCP server (stdio) for Claude Code, Cline, etc.

MCP_VERSION=2024-11-05 pmat

Autonomous-agent pre-flight (pmat verify)
pmat verify runs the exact gate set CI enforces — format, complexity, satd, clippy, tests — fail-fast, with machine-readable output, so an agent gets "green here ⇒ green in CI" before committing. The canonical loop: edit → pmat verify --format json → fix on red → commit on green. See docs/agent-instructions/autonomous-verify-loop.md.
Ultracode validated
PMAT releases are dogfooded with ultracode — Claude Code's multi-agent

dynamic-workflow orchestration — as both the test harness and the target

workload:
- Full CLI sweep: 111 commands exercised by parallel agent fleets per release

- MCP surface: all 20 tools validated over stdio JSON-RPC — per-tool calls

  with schema-derived arguments, 8-way concurrent server sessions against one

  working tree (zero lock errors, zero scratch leftovers), and byte-level

  framing checks (stdout is exclusively JSON-RPC)

- Determinism: TDG baselines and penalty attributions serialize

  byte-identically across runs, so independent agents converge instead of

  diverging on ordering noise

- Concurrency-safe caches: PID-unique scratch files with atomic

  rename-into-place and stale-orphan sweeping; advisory-locked metric recording
Findings from each sweep are adversarially re-verified by skeptic agents

before they drive fixes — see the release case studies in the

pmat book.
Features
Context Generation
Generate comprehensive context for AI assistants:

bash
pmat context # Basic analysis
pmat context --format llm-optimized # AI-optimized output
pmat context --include-tests # Include test files

Technical Debt Grading (TDG)

Six orthogonal metrics for accurate quality assessment:

bash
pmat analyze tdg # Project-wide grade
pmat analyze tdg --include-components # Per-component breakdown
pmat tdg baseline create # Create quality baseline
pmat tdg check-regression # Detect quality degradation

Grading Scale:

- A+/A: Excellent quality, minimal debt

- B+/B: Good quality, manageable debt

- C+/C: Needs improvement

- D/F: Significant technical debt

Mutation Testing
Validate test suite effectiveness:

bash
pmat mutate --target src/lib.rs # Single file
pmat mutate --target src/ --threshold 85 # Quality gate
pmat mutate --failures-only # CI optimization

Supported Languages: Rust, Python, TypeScript, JavaScript, Go, C/C++, C#, Lua, Lean, Java, Kotlin, Ruby, Swift, PHP, Bash, SQL, Scala, YAML, Markdown + MLOps model formats (GGUF, SafeTensors, APR)

Repository Health Scoring
Evidence-based quality metrics (0-289 scale, 11 categories):

bash
pmat rust-project-score # Fast mode (~3 min)
pmat rust-project-score --full # Comprehensive (~10-15 min)
pmat repo-score . --deep # Full git history

Workflow Prompts

Pre-configured AI prompts enforcing EXTREME TDD:

bash
pmat prompt --list # Available prompts
pmat prompt code-coverage # 85%+ coverage enforcement
pmat prompt debug # Five Whys analysis
pmat prompt quality-enforcement # All quality gates

Git History RAG

Search git history by intent using TF-IDF semantic embeddings:

bash

Fuse git history into code search

pmat query "fix memory leak" -G

Search with churn, clones, entropy, faults

pmat query "error handling" --churn --duplicates --entropy --faults

bash

Run the example

cargo run --example git_history_demo

Git Hooks
Automatic quality enforcement:

bash
pmat hooks install # Install pre-commit hooks
pmat hooks install --tdg-enforcement # With TDG quality gates
pmat hooks status # Check hook status
``

Compliance Governance (pmat comply`)

30+ automated checks across code quality, best practices, and governance:

…