Crates.io Documentation Tests Coverage License: MIT MSRV CHANGELOG

Installation | MCP Server | 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 - 157 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 over stdio and HTTP (identical surfaces), validated end-to-end for concurrent multi-agent (ultracode) workflows — see MCP Server
  • 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 .

MCP Server

PMAT is an MCP server first and a CLI second. One binary serves three surfaces, and they share one tool registry — you pick a surface, not a feature set.

Surface Start it with Use it when
CLI pmat analyze complexity --path . A human or a shell script reads the output.
MCP over stdio pmat --mode mcp An MCP client launches pmat itself as a subprocess — Claude Code, Claude Desktop, Cline. One client, one process, no port, no token.
MCP over HTTP pmat serve --transport http --port 8765 One long-lived server that several clients — or another machine — talk to. Streamable HTTP, bearer auth.

New in 3.32.0: mcp-http moved into the default feature set. cargo install pmat now gives you the HTTP transport; the old --features mcp-http dance is gone. Compiling the transport in does not open a socket — only pmat serve binds one.

Quickstart — stdio

Claude Code launches pmat as a subprocess. Nothing to keep running, nothing to authenticate.

cargo install pmat
claude mcp add --scope user pmat -- pmat --mode mcp
claude mcp list
# pmat: pmat --mode mcp - ✔ Connected

Claude Desktop takes the same command as JSON, in its own claude_desktop_config.json:

{
  "mcpServers": {
    "pmat": { "command": "pmat", "args": ["--mode", "mcp"] }
  }
}

For clients that cannot pass flags, MCP_VERSION=1 pmat starts the identical server. Smoke-test the stdio surface without any client at all:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | pmat --mode mcp 2>/dev/null | jq -r '.result.tools | length'
# 19

Quickstart — HTTP

One server, many clients. Copy-paste the whole block:

cargo install pmat

export PMAT_MCP_HTTP_TOKEN='pmat-mcp-demo-token-0123456789'   # >= 16 chars; use your own
pmat serve --transport http --port 8765 &
#   pmat MCP (streamable HTTP) listening on http://127.0.0.1:8765/
#     auth: Bearer, from PMAT_MCP_HTTP_TOKEN; unauthenticated requests get 401
#     tools: 20
sleep 2

claude mcp add --scope user --transport http pmat http://127.0.0.1:8765/ \
  --header "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN"
claude mcp list
# pmat: http://127.0.0.1:8765/ (HTTP) - ✔ Connected

The server binds 127.0.0.1 unless you pass --host. To reach it from another machine, bind an externally routable address and treat PMAT_MCP_HTTP_TOKEN as a real secret — the tool surface can read and analyse any path the server process can read.

Four gotchas that cost an hour each

1. MCP is served at the root path /, not /mcp. There is no path prefix.

for p in / /mcp /health; do
  printf '%-7s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' -X POST "http://127.0.0.1:8765$p" \
    -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}')"
done
# /       200
# /mcp    404
# /health 404

2. PMAT_MCP_HTTP_TOKEN is mandatory and must be at least 16 characters. Below that the server refuses to start rather than falling back to serving unauthenticated — the underlying pmcp transport answers every request when no auth provider is wired, so "no token" has to mean "no server". Requests with no token, or a wrong one, get 401.

PMAT_MCP_HTTP_TOKEN=too-short-123 pmat serve --transport http --port 8765
# Error: PMAT_MCP_HTTP_TOKEN must be at least 16 characters; got 13

3. Hand-rolled clients must send Accept: application/json, text/event-stream. The streamable transport rejects the request without it, and curl -f turns that into an empty string with no message — so probe with plain curl -s while debugging.

curl -s -w '\n-> HTTP %{http_code}\n' -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# {"jsonrpc":"2.0","error":{"code":-32700,"message":"Accept header must include application/json or text/event-stream"},"id":null}
# -> HTTP 406

4. There is no /health endpoint. GET /health is a 404, so a curl -f .../health readiness loop never turns green and never says why. Probe with a real tools/list call instead:

curl -s -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq -r '.result.tools | length'
# 19

No MCP session id is involved: initialize returns no Mcp-Session-Id header, and tools/call works directly — with or without a preceding initialize.

HTTP is not a reduced surface

Both transports are built from the same registry, so HTTP serves all 20 tools, not a subset. The tools/list payloads are byte-identical:

printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"p","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | pmat --mode mcp 2>/dev/null \
  | jq -Sc 'select(.id==2)|.result.tools|sort_by(.name)' > /tmp/pmat-stdio-tools.json

curl -s -X POST http://127.0.0.1:8765/ \
  -H "Authorization: Bearer $PMAT_MCP_HTTP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | jq -Sc '.result.tools|sort_by(.name)' > /tmp/pmat-http-tools.json

cmp /tmp/pmat-stdio-tools.json /tmp/pmat-http-tools.json && echo "identical"
# identical

The 19: analyze_complexity, analyze_satd, analyze_dead_code, analyze_dag, analyze_deep_context, analyze_big_o, analyze_reachability, analyze_hardcoded_paths, analyze_vacuous_tests, quality_gate, quality_proxy, generate_context, scaffold_project, git_operation, pmat_query_code, pmat_get_function, pmat_find_similar, pmat_index_stats, pdmt_deterministic_todos. Names and descriptions are also committed as the machine-checked manifest mcp.json at the repository root, regenerated from the server's own registrations — so it cannot drift from what the two transports actually serve.

Transports that are not implemented

--transport also accepts web-socket, http-sse, both and all. None of them are implemented; each exits 2 with a message saying so. http is the only value that serves.

pmat serve --transport web-socket --port 8765
# error: pmat serve --transport websocket is not yet implemented

There is no stdio value for --transport — passing one is a clap error. Stdio is pmat --mode mcp.

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 .

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

# Run mutation testing
pmat mutate --target src/

# Start the MCP server over stdio, for Claude Code, Cline, etc. (see "MCP Server" above)
pmat --mode mcp

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) — plus a transport-parity check that the HTTP tools/list payload is byte-identical to the stdio one
  • 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-large-files     # Include files >500KB normally skipped

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)

157 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 definitions below the minimum grade (default A). Reads the index pmat query built; it never builds or rewrites one, and reports Skip / "Not measured" when .pmat/context.db is absent
  • 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"          # CB-200 floor; `.pmat-gates.toml` [tdg] min_grade overrides this
    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 --push                     # Fix, commit, and push (use --no-commit to skip)
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              # 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 --list src/lib.rs         # Function/struct/enum/trait boundaries, as JSON

Examples

Generate Context for AI

# For Claude Code
pmat context --output context.md --format llm-optimized

# With semantic search
pmat embed sync --path ./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/     Analysis engines (TDG, SATD, complexity, agent context)
│   ├── mcp_server/   MCP protocol server
│   ├── mcp_pmcp/     PMCP protocol integration
│   └── models/       Configuration and data models
├── examples/         113 runnable examples
└── docs/
    └── specifications/  Technical specs

Quality

Metric Value
Tests 21,200+ passing
Coverage 99.66%
Mutation Score >80%
Languages 20 supported + MLOps model formats
MCP Tools 20 available

Falsifiable Quality Commitments

Per Popper's demarcation criterion, all claims are measurable and testable:

Commitment Threshold Verification Method
Context Generation < 5 seconds for 10K LOC project time pmat context on test corpus
Memory Usage < 500 MB for 100K LOC analysis Measured via heaptrack in CI
Test Coverage ≥ 85% line coverage cargo llvm-cov (CI enforced)
Mutation Score ≥ 80% killed mutants pmat mutate --threshold 80
Build Time < 3 minutes incremental cargo build --timings
CI Pipeline < 15 minutes total GitHub Actions workflow timing
Binary Size < 50 MB release binary ls -lh target/release/pmat
Language Parsers All 20 languages parse without panic Fuzz testing in CI

How to Verify:

# Run self-assessment with Popper Falsifiability Score
pmat popper-score --verbose

# Individual commitment verification
cargo llvm-cov --html        # Coverage ≥85%
pmat mutate --threshold 80   # Mutation ≥80%
cargo build --timings        # Build time <3min

Failure = Regression: Any commitment violation blocks CI merge.

Benchmark Results (Statistical Rigor)

All benchmarks use Criterion.rs with proper statistical methodology:

Operation Mean 95% CI Std Dev Sample Size
Context (1K LOC) 127ms [124, 130] ±12.3ms n=1000 runs
Context (10K LOC) 1.84s [1.79, 1.90] ±156ms n=500 runs
TDG Scoring 156ms [148, 164] ±18.2ms n=500 runs
Complexity Analysis 23ms [22, 24] ±3.1ms n=1000 runs

Comparison Baselines (vs. Alternatives):

Metric PMAT ctags tree-sitter Effect Size
10K LOC parsing 1.84s 0.3s 0.8s d=0.72 (medium)
Memory (10K LOC) 287MB 45MB 120MB -
Semantic depth Full Syntax only AST only -

See docs/BENCHMARKS.md for complete statistical analysis.

ML/AI Reproducibility

PMAT uses ML for semantic search and embeddings. All ML operations are reproducible:

Random Seed Management:

  • Embedding generation uses fixed seed (SEED=42) for deterministic outputs
  • Clustering operations use fixed seed (SEED=12345)
  • Seeds documented in docs/ml/REPRODUCIBILITY.md

Model Artifacts:

  • Pre-trained models from HuggingFace (all-MiniLM-L6-v2)
  • Model versions pinned in Cargo.toml
  • Hash verification on download

Dataset Sources

PMAT does not train models but uses these data sources for evaluation:

Dataset Source Purpose Size
CodeSearchNet GitHub/Microsoft Semantic search benchmarks 2M functions
PMAT-bench Internal Regression testing 500 queries

Data provenance and licensing documented in docs/ml/REPRODUCIBILITY.md.

Sovereign Stack

PMAT is built on the PAIML Sovereign Stack - pure-Rust, SIMD-accelerated libraries:

Library Purpose Version
aprender ML library (text similarity, clustering, topic modeling) 0.64
aprender-graph CSR graph database (PageRank, Louvain) 0.64
aprender-db Columnar analytics database (lib trueno_db, optional) 0.64
aprender-rag RAG pipeline with VectorStore 0.64
aprender-viz Terminal graph visualization 0.64
aprender-compute SIMD/GPU compute for matrix operations (lib trueno) 0.64
aprender-zram-core SIMD LZ4/ZSTD compression (optional) 0.64
aprender-contracts Provable contracts (with aprender-contracts-macros) 0.64
pmcp MCP protocol SDK (streamable HTTP transport) 2.17
pmat Code analysis toolkit 3.38.0

Key Benefits:

  • Pure Rust (no C dependencies, no FFI)
  • SIMD-first (AVX2, AVX-512, NEON auto-detection)
  • 2-4x speedup on graph algorithms via aprender adapter

Documentation

Contributing

See CONTRIBUTING.md for development setup, testing, and pull request guidelines.

See Also

License

MIT License - see LICENSE for details.