Installation | Usage | Features | Examples | Documentation

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

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:

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.yaml functions exist in src/, detects ghost bindings (L0-L3 enforcement levels)
• CB-1209: Contract trait enforcement — checks tests/contract_traits.rs for 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 co