Installation | Usage | Features | Examples | Documentation
Table of Contents
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 - 19 tools for Claude Code, Cline, and AI agents
- Quality Gates - Pre-commit hooks, CI/CD integration,
.pmat-gates.tomlconfig - 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
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
# Or from source (latest)
git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit && cargo install --path .
Usage
# 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 .
# Run mutation testing
pmat mutate --target src/
# Start MCP server for Claude Code, Cline, etc.
pmat mcp
Features
Context Generation
Generate comprehensive context for AI assistants:
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:
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:
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):
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:
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:
# 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
# Run the example
cargo run --example git_history_demo
Git Hooks
Automatic quality enforcement:
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:
pmat comply check # Run all compliance checks
pmat comply check --strict # Exit non-zero on failure
pmat comply check --format json # Machine-readable output
pmat comply migrate # Update to latest version
Key Checks:
- CB-200: TDG Grade Gate — blocks on non-A functions (auto-rebuilds stale index)
- CB-304: Dead code percentage enforcement
- CB-400: Shell/Makefile quality via bashrs
- CB-500: Rust best practices (30+ patterns)
- CB-600: Lua best practices
- CB-900: Markdown link validation
- CB-1000: MLOps model quality
Provable-Contracts Enforcement (CB-1200..1210):
- CB-1208: Binding existence — verifies
binding.yamlfunctions exist insrc/, detects ghost bindings (L0-L3 enforcement levels) - CB-1209: Contract trait enforcement — checks
tests/contract_traits.rsfor compiler-verified trait impls (13 kernel traits) - CB-1210: Precondition quality — flags mass-generated boilerplate and missing postconditions
Configure via .pmat.yaml:
comply:
thresholds:
min_tdg_grade: "A"
pv_lint_is_error: true # CB-1201: FAIL on pv lint failure
min_binding_existence: 95 # CB-1208: 95% binding verification
require_all_traits: true # CB-1209: 13/13 traits required
min_kani_coverage: 20 # CB-1206: minimum Kani proof %
Infrastructure Score (pmat infra-score)
CI/CD quality scoring (0-100 + 10 bonus for provable-contracts):
pmat infra-score # Text output
pmat infra-score --format json # Machine-readable
pmat infra-score -v --failures-only # Show only failing checks
Categories: Workflow Architecture (25pts), Build Reliability (25pts), Quality Pipeline (20pts), Deployment & Release (15pts), Supply Chain (15pts), Provable Contracts bonus (10pts).
Document Search (pmat query --docs)
Search documentation files (Markdown, text, YAML) alongside code:
pmat query "authentication" --docs # Code + docs results
pmat query "deployment" --docs-only # Only documentation
pmat query "API endpoints" --no-docs # Exclude docs (default)
Autonomous Kaizen (pmat kaizen)
Toyota Way continuous improvement — scan, auto-fix, commit:
pmat kaizen --dry-run # Scan only (no changes)
pmat kaizen # Apply safe auto-fixes
pmat kaizen --commit --push # Fix, commit, and push
pmat kaizen --format json -o report.json # CI/CD integration
# Cross-stack mode: scan all batuta stack crates in one invocation
pmat kaizen --cross-stack --dry-run # Scan all crates
pmat kaizen --cross-stack --commit # Fix and commit per-crate
pmat kaizen --cross-stack -f json # Grouped JSON report
Function Extraction (pmat extract)
Extract function boundaries with metadata:
pmat extract src/lib.rs # Extract functions from file
pmat extract --list src/ # List all functions with imports and visibility
Examples
Generate Context for AI
# For Claude Code
pmat context --output context.md --format llm-optimized
# With semantic search
pmat embed sync ./src
pmat semantic search "error handling patterns"
CI/CD Integration
# Add to your CI pipeline
steps:
- uses: actions/checkout@v4
- run: cargo install pmat
- run: pmat analyze tdg --fail-on-violation --min-grade B
- run: pmat mutate --target src/ --threshold 80
Quality Baseline Workflow
# 1. Create baseline
pmat tdg baseline create --output .pmat/baseline.json
# 2. Check for regressions
pmat tdg check-regression \
--baseline .pmat/baseline.json \
--max-score-drop 5.0 \
--fail-on-regression
Architecture
pmat/
├── src/
│ ├── cli/ Command handlers and dispatchers
│ ├── services/