PAIML MCP Agent Toolkit (pmat)

Zero-configuration AI context generation system with extreme quality enforcement and Toyota Way standards. Analyze any codebase instantly through CLI, MCP, or HTTP interfaces. Built by Pragmatic AI Labs.

🔥 Core Features

🗄️ TDG Dogfooding Storage (NEW in v2.68.0)

Persistent file score storage for continuous quality improvement! PMAT now tracks its own quality metrics:

📊 Automatic Storage: Every TDG analysis automatically persists scores to disk
⚡ Smart Caching: Repeated analyses use stored scores for instant results
📈 Historical Tracking: Foundation for quality trend analysis and regression detection
💾 Tiered Storage: Hot/warm/cold storage optimization (3.6MB+ real data stored)
🔍 Storage Management: pmat tdg storage stats for monitoring and diagnostics
🏭 True Dogfooding: PMAT eating its own dog food by tracking its own code quality

🎯 Pre-commit Hooks Management (New in v2.66.0)

Single source of truth configuration for quality gate enforcement! Eliminate configuration duplication with PMAT-managed pre-commit hooks:

Dynamic Hook Generation: Hooks generated from pmat.toml configuration
Quality Gate Enforcement: Complexity, SATD, coverage checks at commit time
Zero Configuration Duplication: One config file, all thresholds synchronized
Easy Management: pmat tdg hooks install --backup to get started
📖 Full Documentation →

🚀 v2.70.0 Release: Actionable Entropy Analysis System! Transform noisy entropy into actionable code improvements:

🎯 AST Pattern Detection: 6 actionable pattern types (ErrorHandling, DataValidation, ResourceManagement, etc.)

🔧 Fix Suggestions: Each violation includes specific refactoring advice with LOC reduction estimates

📊 Noise Reduction: From 2255+ character-based violations to 10-50 actionable violations

🔌 MCP Integration: Full analyze_entropy tool with parameter schema for external tools

🛡️ Quality Gate Integration: Entropy violations trigger quality gate failures in Strict/Extreme profiles

📋 CLAUDE.md Enforcement: Mandatory entropy analysis in quality standards and daily workflows

🎯 v2.63.0 Release: Advanced Code Similarity Detection System! Industry-leading duplicate and similarity detection:

🔍 4 Clone Types: Exact (Type-1), Renamed (Type-2), Modified (Type-3), Semantic (Type-4) detection

📊 Entropy Analysis: Actionable AST pattern-based entropy with fix suggestions and LOC reduction estimates

🧮 Advanced Algorithms: Winnowing, TF-IDF, Cosine Similarity, Jaccard Index, Levenshtein Distance

📄 Multi-Format Output: JSON, Markdown, CSV, SARIF, and Summary formats

🚀 Performance: Optimized for 100K+ LOC with parallel processing

🔧 Full Integration: CLI commands, MCP tools, and comprehensive examples

🚀 v2.39.0 Release: TDG System with MCP Integration & Advanced Monitoring! Production-ready technical debt analysis:

🌐 Web Dashboard: Real-time monitoring with Axum-based interface and Server-Sent Events

🛠️ 6 MCP Tools: Enterprise-grade external integration (tdg_analyze_with_storage, tdg_system_diagnostics, etc.)

📊 Advanced Analytics: Metrics aggregation, performance profiling, bottleneck detection

🚨 Alert System: Configurable thresholds with multi-channel notifications

📤 Multi-format Export: JSON, CSV, SARIF, HTML, Markdown, XML, Prometheus support

💾 Storage Flexibility: Pluggable backends (Sled, RocksDB, InMemory) with trait abstraction

🔧 v2.14.0 Release: Technical Debt Elimination via TDD! Major fixes using Test-Driven Development:

✅ Language Detection Fixed: Functions now properly detected (was 0, now detects all)

🚫 Zero Stub Implementations: All stub code eliminated with real implementations

📉 Complexity Reduced: Ruchy parser from 89 to ≤4 cyclomatic complexity (95% reduction)

🧪 TDD Coverage: 80%+ test coverage on critical language detection paths

🏭 Toyota Way Applied: ONE implementation principle, zero defect tolerance

🎯 v2.13.0: Technical Debt Grading (TDG) System! Complete code quality scoring with 6 orthogonal metrics:

📊 Comprehensive Scoring: Structural complexity, semantic complexity, code duplication, coupling analysis

📚 Documentation Coverage: Language-specific documentation pattern detection and scoring

🎨 Consistency Analysis: Naming conventions, indentation patterns, and code style consistency

🏆 Grade Classification: A+ through F grading system with detailed component breakdowns

🌍 Multi-Language Support: 10+ languages including Rust, Python, JavaScript, TypeScript, Go, Java, C/C++

🛠️ CLI & MCP Integration: pmat analyze tdg command and MCP tools for programmatic access

📈 Project Analysis: Directory-level analysis with language distribution and aggregated scoring

🚀 v2.10.0: Claude Code Agent Mode - "Always Working" Achievement! Transform PMAT into a persistent background quality agent:

🤖 Claude Code Integration: Native MCP server for seamless Claude Code integration

💾 Persistent State: Monitoring state maintained across restarts with auto-save

⚙️ Production Ready: Environment-specific configs for dev, prod, and CI/CD

📊 Real-time Monitoring: Continuous quality tracking with file system watching

🏗️ Service Architecture: Systemd deployment with health checks and auto-restart

🎯 v2.9.0: Universal Demo "Just Works" Achievement! Complete AI-powered repository intelligence with multi-language analysis:

🤖 AI-Powered Recommendations: Framework-aware repository recommendations with complexity-based learning tiers

🌍 Multi-Language Intelligence: Advanced polyglot analysis with cross-language dependency detection

🏛️ Architecture Pattern Recognition: Microservices, Layered, Event-driven pattern detection with confidence scoring

📚 Repository Showcase Gallery: Curated collection of 8+ repositories across languages and complexity levels

⚡ Universal Demo: Any GitHub repository URL → Complete analysis with AI recommendations

🌐 Enhanced Web Demo: Interactive visualizations with 3 new API endpoints (/api/recommendations, /api/polyglot, /api/showcase)

Toyota Way Excellence: Zero compilation defects maintained throughout development

🚀 Quick Start

Installation

Choose your preferred installation method - PMAT is available across all major package ecosystems:

🦀 Rust (Recommended)

cargo install pmat

📦 Package Managers

# macOS/Linux - Homebrew
brew install pmat

# Windows - Chocolatey  
choco install pmat

# Ubuntu/Debian - APT
sudo apt install pmat                    # (via PPA - coming soon)

# Arch Linux - AUR
yay -S pmat

# Node.js - npm (global)
npm install -g pmat-agent

🐳 Docker

# Latest version
docker run --rm -v $(pwd):/workspace paiml/pmat:latest pmat --version

# Interactive analysis
docker run --rm -v $(pwd):/workspace -w /workspace paiml/pmat:latest pmat context

🔧 From Source

git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit
make build

📥 Direct Download

# Linux/macOS Quick Install
curl -sSfL https://raw.githubusercontent.com/paiml/paiml-mcp-agent-toolkit/master/scripts/install.sh | sh

# Windows PowerShell
# Download from: https://github.com/paiml/paiml-mcp-agent-toolkit/releases

Basic Usage

# Analyze current directory
pmat context

# Technical Debt Grading (TDG) - v2.39.0!
pmat tdg . --include-components

# Start TDG web dashboard
pmat tdg dashboard --port 8081 --open

# TDG analysis with automatic persistent storage (NEW - v2.68.0!)
pmat tdg server/src/tdg/analyzer_ast.rs
# Scores automatically stored in ~/.pmat/tdg-warm and ~/.pmat/tdg-cold

# View storage statistics and dogfooding progress
pmat tdg storage stats

# Get complexity metrics
pmat analyze complexity --top-files 10

# Find technical debt
pmat analyze satd

# Code similarity detection - v2.63.0! 🔍
pmat analyze duplicates --detection-type all     # Find all types of duplicates
pmat analyze duplicates --format sarif           # Export to SARIF format
pmat analyze duplicates --detection-type semantic --threshold 0.7

# Analysis with timeout control - NEW! 🔧
pmat analyze complexity --timeout 30    # 30-second timeout
pmat analyze dead-code --timeout 60     # 60-second timeout  
pmat analyze satd --timeout 45          # 45-second timeout

# Run quality gates
pmat quality-gate --strict

# Start MCP server
pmat mcp

Universal Demo - "Just Works" Analysis

# Analyze any GitHub repository with AI recommendations
cargo run --example analyze_github_repo -- --url https://github.com/rust-lang/rust-clippy

# Compare multiple repositories across languages
cargo run --example compare_repos

# Run quality gates on GitHub repositories
cargo run --example quality_gate_github -- https://github.com/owner/repo

# Start interactive web demo
pmat demo --serve
# Then visit http://localhost:8080 for:
# • AI-powered repository recommendations
# • Multi-language project intelligence
# • Repository showcase gallery
# • Interactive analysis visualizations

Toyota Way Development (NEW)

# Setup quality enforcement (one-time)
make setup-quality

# Start development with quality checks
make dev

# Create quality-enforced commit
make commit

# Verify sprint quality
make sprint-close

🎯 Core Capabilities

Analysis Engine

Technical Debt Grading (TDG): 6-metric orthogonal code quality scoring with A+ through F grading
Real-time Dashboard: Web-based monitoring with live metrics and performance tracking
Advanced Analytics: Metrics aggregation, trend detection, bottleneck analysis
Performance Profiling: Flame graph generation, CPU/I/O/Memory analysis
Alert Management: Configurable thresholds with notification channels
Multi-format Export: 8 export formats (JSON, CSV, SARIF, HTML, Markdown, XML, Prometheus)
Storage Flexibility: Pluggable backends with tiered Hot/Warm/Cold architecture
MCP Integration: 6 enterprise tools for external system integration
Complexity Analysis: McCabe cyclomatic & cognitive complexity with AST precision
Dead Code Detection: Graph-based reachability analysis across 30+ languages
SATD Detection: Self-admitted technical debt with severity classification
Documentation Coverage: Language-specific pattern detection with scoring algorithms
Consistency Analysis: Naming conventions and code style consistency measurement
Deep Context Generation: Multi-dimensional analysis optimized for AI agents

🤖 AI-Powered Intelligence (NEW)

Smart Recommendations: Framework-aware repository suggestions with complexity matching
Polyglot Analysis: Cross-language dependency detection and architecture pattern recognition
Repository Showcase: Curated gallery with learning pathways from beginner to expert
Integration Points: Risk assessment of multi-language project coupling with mitigation strategies

Quality Systems

Quality Gates: Zero-tolerance enforcement (complexity ≤20, SATD=0, coverage >80%)
Quality Proxy: AI code interceptor with 7-stage validation pipeline
PDMT Integration: Deterministic todo generation with embedded quality requirements
Refactoring Engine: State machine-based code transformation with ACID snapshots

Integration Protocols

MCP Protocol: 24 tools via unified pmcp SDK 1.3.0 server (includes 6 new TDG enterprise tools)
TDG Web Dashboard: Axum-based real-time interface with SSE streaming
HTTP API: RESTful with Server-Sent Events streaming
CLI Interface: 50+ commands with POSIX-compliant exit semantics

📖 Documentation

Core Documentation

Complete Specification - Unified source of truth (36 sections)
TDG Guide - NEW! Technical Debt Grading system documentation
Transactional Hashed TDG - 🚀 v2.38.0! Enterprise-grade TDG with caching, scheduling, and resource control
API Reference - Service APIs and integration patterns
CLI Reference - Complete command documentation

Quality & Development

Toyota Way Guide - Development workflow and standards
Sprint Management - Task tracking and execution DAG
Quality Gates - Enforcement mechanisms

Integration Guides

MCP Integration - Model Context Protocol setup
PDMT Guide - Deterministic todo generation
CI/CD Integration - Pipeline integration

🏗️ Architecture

PMAT implements Toyota Production System principles through rigorous static analysis:

Kaizen (改善): Iterative file-by-file improvement with measurable ΔQ metrics
Genchi Genbutsu (現地現物): Direct AST traversal, no heuristics
Jidoka (自働化): Automated quality gates with fail-fast semantics
Zero SATD Policy: Compile-time enforcement of zero technical debt

Service Architecture

// Unified service layer with dependency injection
pub trait Service: Send + Sync {
    type Input: Serialize + DeserializeOwned;
    type Output: Serialize + DeserializeOwned;
    
    async fn process(&self, input: Self::Input) -> Result<Self::Output, Self::Error>;
}

// All protocols use unified request/response
#[derive(Serialize, Deserialize)]
pub struct UnifiedRequest {
    pub operation: Operation,
    pub params: Value,
    pub context: RequestContext,
}

Performance Characteristics

Startup: 4ms hot, 127ms cold (mmap'd grammar cache)
Analysis: 487K LOC/s single-thread, 3.9M LOC/s multi-core
Memory: 47MB base + 312KB per KLOC
SIMD: 43% vectorized paths, 2.7x AVX2 speedup

🛠️ Development

Requirements

Rust 1.80.0+
Git (for repository analysis)

Build from Source

git clone https://github.com/paiml/paiml-mcp-agent-toolkit
cd paiml-mcp-agent-toolkit

# Setup Toyota Way quality enforcement
make setup-quality

# Build and test
make build
make validate

# Run examples
make examples

Library Usage

[dependencies]
pmat = "2.39.0"

use pmat::services::code_analysis::CodeAnalysisService;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let service = CodeAnalysisService::new();
    
    // Generate AI-optimized context
    let context = service.generate_context(".", None).await?;
    
    // Analyze complexity with Toyota Way standards
    let complexity = service.analyze_complexity(".", Some(10)).await?;
    
    Ok(())
}

🔍 Language Support

Rust: Full cargo integration with syn AST
TypeScript/JavaScript: SWC-based parsing
Python: RustPython AST analysis
C/C++: Tree-sitter with goto tracking
Ruchy: v1.5.0 support with advanced analysis
- Full AST parsing with 35+ token types
- Halstead metrics (volume, difficulty, effort, time, bugs)
- Dead code detection (unused functions/variables)
- Type inference for literals and binary operations
- Actor message flow analysis with deadlock detection
- Enhanced pattern matching complexity scoring
- Import/export dependency tracking
Kotlin: Tree-sitter based analysis
30+ Languages: Via tree-sitter grammar support

🤖 MCP Integration

PMAT provides 18 MCP tools via unified pmcp SDK server:

# Start MCP server (auto-detects transport)
pmat mcp

# Test with Claude Code
cargo run --example mcp_server_pmcp
cargo run --example test_pmcp_server

Available Tools

analyze_tdg - Technical Debt Grading with 6-metric scoring
analyze_tdg_compare - Compare TDG scores between files/projects
tdg_analyze_with_storage - NEW v2.39.0! TDG analysis with configurable storage backends
tdg_system_diagnostics - NEW v2.39.0! Comprehensive system health monitoring
tdg_storage_management - NEW v2.39.0! Storage operations and management
tdg_performance_profiling - NEW v2.39.0! Performance analysis with flame graphs
tdg_alert_management - NEW v2.39.0! Alert configuration and monitoring
tdg_export_data - NEW v2.39.0! Multi-format data export (8 formats)
analyze_complexity - Complexity metrics
analyze_satd - Technical debt detection
analyze_dead_code - Unused code analysis
quality_gate - Comprehensive quality validation
refactor_start - Begin refactoring workflow
pdmt_deterministic_todos - Generate quality todos
github_create_issue - Create GitHub issues
AI recommendation tools for intelligent repository analysis
And 10 more...

🤖 Claude Code Agent Mode (NEW v2.10.0)

Transform PMAT into a persistent background quality agent that continuously monitors your codebase:

Quick Start with Claude Code

# Start agent as MCP server for Claude Code
pmat agent mcp-server

# Configure in Claude Code settings.json:
{
  "mcpServers": {
    "pmat": {
      "command": "pmat",
      "args": ["agent", "mcp-server"],
      "env": {}
    }
  }
}

Background Daemon Mode

# Start monitoring a project
pmat agent start --project-path /path/to/project

# Check monitoring status
pmat agent status

# Stop monitoring
pmat agent stop

Key Features

Real-time Monitoring: File system watching with instant quality feedback
Persistent State: Maintains metrics across restarts with auto-save
Toyota Way Compliance: Enforces ≤20 complexity with zero SATD tolerance
Analysis Timeouts: Configurable timeouts prevent infinite hangs (NEW! 🔧)
Production Ready: Systemd service with health checks and auto-restart
MCP Native: Seamless Claude Code integration via stdio transport

Available Agent Tools

start_quality_monitoring - Begin monitoring a project
stop_quality_monitoring - Stop monitoring
get_quality_status - Current quality metrics
run_quality_gates - Execute quality checks
analyze_complexity - Complexity analysis
health_check - Agent health status

See Claude Code Agent Guide for detailed setup and deployment instructions.

🌐 TDG Web Dashboard API Endpoints (NEW v2.39.0)

# Real-time TDG metrics
GET /api/metrics

# System health status
GET /api/health

# Storage statistics
GET /api/storage/stats

# Run TDG analysis
GET /api/analysis?path=src/main.rs

# System diagnostics
GET /api/diagnostics

# Real-time metrics stream (SSE)
GET /api/events

# Storage operations
POST /api/storage/operation

🌐 Web Demo API Endpoints

# AI-powered repository recommendations
GET /api/recommendations

# Multi-language project intelligence
GET /api/polyglot

# Repository showcase gallery
GET /api/showcase

# Core analysis APIs
GET /api/summary
GET /api/metrics
GET /api/hotspots
GET /api/dag

📊 Quality Standards

PMAT enforces extreme quality standards:

Complexity: ≤20 cyclomatic, ≤15 cognitive
Technical Debt: 0 SATD comments allowed
Test Coverage: >80% with property-based testing
Code Quality: 0 lint warnings, 0 dead code
Documentation: Synchronized with every commit

Quality Gates

# Run comprehensive quality analysis
pmat quality-gate --strict

# CI/CD integration
pmat analyze complexity --fail-on-violation
pmat analyze satd --fail-on-violation
pmat quality-gate --strict --fail-on-violation

🚀 Contributing

PMAT follows Toyota Way development principles:

Setup quality enforcement: make setup-quality
Start development: make dev
Make changes with documentation updates
Quality-enforced commit: make commit
Sprint verification: make sprint-close

All contributions must meet:

Zero SATD comments
Complexity ≤20 per function
Full test coverage
Documentation updates

See CONTRIBUTING.md for detailed guidelines.

📋 License

Licensed under the MIT License. See LICENSE for details.

Built with ❤️ by Pragmatic AI Labs