Metadata-Version: 2.4
Name: crackerjack
Version: 0.54.4
Summary: Crackerjack Python project management tool
Project-URL: documentation, https://github.com/lesleslie/crackerjack
Project-URL: homepage, https://github.com/lesleslie/crackerjack
Project-URL: repository, https://github.com/lesleslie/crackerjack
Author-email: Les Leslie <les@wedgwoodwebworks.com>
License: BSD-3-CLAUSE
License-File: LICENSE
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: aiohttp>=3.13.2
Requires-Dist: alive-progress>=3.3.0
Requires-Dist: bandit>=1.9.2
Requires-Dist: codespell>=2.4.1
Requires-Dist: complexipy>=5.1.0
Requires-Dist: creosote>=4.1.0
Requires-Dist: dhara>=0.8.1
Requires-Dist: docstring-to-markdown>=0.17
Requires-Dist: fastapi>=0.124.2
Requires-Dist: fastmcp>=2.13.2
Requires-Dist: hatchling>=1.28.0
Requires-Dist: hypothesis>=6.0.0
Requires-Dist: ipython>=8.0.0
Requires-Dist: keyring>=25.7.0
Requires-Dist: libcst>=1.0.0
Requires-Dist: linkcheckmd>=1.4.0
Requires-Dist: mcp-common[treesitter]>=0.9.4
Requires-Dist: mcp>=1.23.3
Requires-Dist: mdformat-ruff>=0.1.3
Requires-Dist: mdformat>=1.0.0
Requires-Dist: numpy>=2.3.5
Requires-Dist: oneiric>=0.3.2
Requires-Dist: pip-audit>=2.10.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyleak>=0.1.14
Requires-Dist: pyscn==1.5.0
Requires-Dist: pytest-asyncio>=1.3.0
Requires-Dist: pytest-benchmark>=5.2.3
Requires-Dist: pytest-cov>=7.0.0
Requires-Dist: pytest-mock>=3.15.1
Requires-Dist: pytest-snob>=0.1.14
Requires-Dist: pytest-timeout>=2.4.0
Requires-Dist: pytest-xdist>=3.8.0
Requires-Dist: pytest>=9.0.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: redbaron>=0.9.2
Requires-Dist: refurb>=2.2.0
Requires-Dist: rich>=14.2.0
Requires-Dist: ruff>=0.14.8
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: scipy-stubs>=1.16.3.3
Requires-Dist: scipy>=1.16.3
Requires-Dist: skylos>=2.5.3
Requires-Dist: sqlmodel>=0.0.37
Requires-Dist: structlog>=25.5.0
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: transformers>=5.1.0
Requires-Dist: typer>=0.20.0
Requires-Dist: types-aiofiles>=25.1.0.20251011
Requires-Dist: types-psutil>=7.1.3.20251211
Requires-Dist: types-pyyaml>=6.0.12.20250915
Requires-Dist: uv-bump>=0.3.2
Requires-Dist: uv>=0.9.17
Requires-Dist: uvicorn>=0.38.0
Requires-Dist: vulture>=2.14
Requires-Dist: watchdog>=6.0.0
Requires-Dist: websockets>=15.0.1
Requires-Dist: zuban>=0.3.0
Provides-Extra: neural
Requires-Dist: sentence-transformers>=2.2.0; extra == 'neural'
Requires-Dist: torch>=2.0.0; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'neural'
Requires-Dist: torch>=2.0.0; (sys_platform == 'darwin' and platform_machine == 'x86_64') and extra == 'neural'
Requires-Dist: torch>=2.0.0; (sys_platform == 'linux') and extra == 'neural'
Requires-Dist: torch>=2.0.0; (sys_platform == 'win32') and extra == 'neural'
Description-Content-Type: text/markdown

# Crackerjack

[![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)
[![Runtime: oneiric](https://img.shields.io/badge/runtime-oneiric-6e5494)](https://github.com/lesleslie/oneiric)
[![Framework: FastMCP](https://img.shields.io/badge/framework-FastMCP-0ea5e9)](https://github.com/jlowin/fastmcp)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Python: 3.13+](https://img.shields.io/badge/python-3.13%2B-green)](https://www.python.org/downloads/)

## Quick Links

- [Overview](#overview)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Workflow](#core-workflow)
- [Quality Hook Modes](#quality-hook-modes)
- [MCP Server Configuration](#mcp-server-configuration)

## Overview

Crackerjack is the standard quality-control and CI/CD runner across the Bodai ecosystem. It unifies linting, typing, tests, security checks, packaging, and release-oriented workflows behind a consistent command surface.

Core capabilities:

- Unified quality gates for linting, typing, tests, security, and packaging
- Fast local and CI execution paths
- AI-assisted fixing and MCP integration where appropriate
- Release and publishing workflows for Python projects

## What Problem Does Crackerjack Solve?

**Instead of configuring multiple tools separately:**

```bash
# Traditional workflow
pip install black isort flake8 mypy pytest
# Configure each tool individually
# Set up git hooks manually
# Remember different commands for each tool
```

**Crackerjack provides unified commands:**

```bash
pip install crackerjack
python -m crackerjack run        # Setup + quality checks
python -m crackerjack run --run-tests        # Add testing
python -m crackerjack run --all patch # Full release workflow
```

**Key differentiators:**

- **Single command** replaces 6+ separate tools
- **Pre-configured** with Python best practices
- **UV integration** for fast dependency management
- **Automated publishing** with PyPI authentication
- **MCP server** for AI agent integration

## The Crackerjack Philosophy

Crackerjack is built on the following core principles:

- **Code Clarity:** Code should be easy to read, understand, and maintain
- **Automation:** Tedious tasks should be automated, allowing developers to focus on solving problems
- **Consistency:** Code style, formatting, and project structure should be consistent across projects
- **Reliability:** Tests are essential, and code should be checked rigorously
- **Tool Integration:** Leverage powerful existing tools instead of reinventing the wheel
- **Auto-Discovery:** Prefer automatic discovery of configurations and settings over manual configuration when possible, reducing setup friction and configuration errors
- **Static Typing:** Static typing is essential for all development

## Crackerjack vs Pre-commit: Architecture & Features

Crackerjack and pre-commit solve related but different problems. While pre-commit is a language-agnostic git hook manager, Crackerjack is a comprehensive Python development platform with quality enforcement built-in.

### Architectural Differences

| Aspect | Pre-commit | Crackerjack |
| ------------------- | -------------------------------------------------------- | --------------------------------------------------------------------- |
| **Execution Model** | Wrapper framework that spawns subprocesses for each hook | Direct tool invocation with adapter architecture |
| **Concurrency** | Synchronous sequential execution (one hook at a time) | **Async-first with 11 concurrent adapters** - true parallel execution |
| **Performance** | Overhead from framework wrapper + subprocess spawning | Zero wrapper overhead, 70% cache hit rate, 50% faster workflows |
| **Language Focus** | Language-agnostic (Python, Go, Rust, Docker, etc.) | Python-first with native tool implementations |
| **Configuration** | YAML-based`.pre-commit-config.yaml` with repo URLs | Python-based configuration with sensible defaults |
| **Hook Management** | Clones repos, manages environments per hook | Native Python tools + direct UV invocation |

### Feature Comparison

#### Quality Hooks & Tools

| Feature | Pre-commit | Crackerjack |
| ------------------------- | ----------------------------------- | ---------------------------------------------- |
| **Code Formatting** | ✅ Via hooks (black, ruff, etc.) | ✅ Native Ruff integration + mdformat |
| **Linting** | ✅ Via hooks (flake8, pylint, etc.) | ✅ Native Ruff + codespell |
| **Type Checking** | ✅ Via hooks (mypy, pyright) | ✅**Zuban** (20-200x faster than pyright) |
| **Security Scanning** | ✅ Via hooks (bandit, gitleaks) | ✅ Native bandit + gitleaks integration |
| **Dead Code Detection** | ✅ Via vulture hook | ✅**Skylos** (20x faster than vulture) |
| **Complexity Analysis** | ❌ Not built-in | ✅ Native complexipy integration |
| **Dependency Validation** | ❌ Not built-in | ✅ Native creosote unused dependency detection |
| **Custom Python Tools** | ✅ Via`repo: local` hooks | ✅ 6 native tools in`crackerjack/tools/` |

#### Development Workflow

| Feature | Pre-commit | Crackerjack |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
| **Git Integration** | ✅ Pre-commit, pre-push, commit-msg hooks | ✅ Git hooks + suggested commit messages |
| **Testing Framework** | ❌ Not included | ✅ Built-in pytest with coverage ratchet |
| **CI/CD Integration** | ✅ Via`pre-commit run --all-files` | ✅ Unified`--ci` mode with quality + tests |
| **Version Management** | ❌ Not included | ✅ Version bumping + AI recommendations |
| **Publishing** | ❌ Not included | ✅ PyPI publishing with UV authentication |
| **Hook Stages** | ✅ Multiple stages (commit, push, merge, manual) | ✅ Fast (~5s) vs Comprehensive (~30s) strategies |
| **Retry Logic** | ❌ No built-in retry | ✅ Automatic retry for formatting hooks |
| **Parallel Execution** | ✅ Limited parallelism (sequential by default) | ✅**Async-first architecture**: 11 concurrent adapters, 76% speedup |

#### Advanced Features

| Feature | Pre-commit | Crackerjack |
| ---------------------------- | ------------------------------------------------- | --------------------------------------------- |
| **AI Integration** | ❌ Not built-in | ✅ 12 specialized AI agents + auto-fixing |
| **Dependency Injection** | ❌ Not applicable | ✅ legacy framework with protocol-based DI |
| **Caching** | ✅ Per-file hash caching | ✅ Content-based caching (70% hit rate) |
| **MCP Server** | ❌ Not included | ✅ Built-in MCP server for Claude integration |
| **Monitoring** | ❌ Not included | ✅ MCP status + progress monitors |
| **Configuration Management** | ✅ YAML +`--config` flag | ✅ settings with YAML + local overrides |
| **Auto-Update** | ✅`pre-commit autoupdate` | ⚠️ Manual UV dependency updates |
| **Language Support** | ✅ 15+ languages (Python, Go, Rust, Docker, etc.) | ✅ Python + external tools (gitleaks, etc.) |

#### Configuration & Ease of Use

| Feature | Pre-commit | Crackerjack |
| ------------------------ | ---------------------------------------------- | ----------------------------------------- |
| **Setup Complexity** | Medium (YAML config +`pre-commit install`) | Low (single`python -m crackerjack run`) |
| **Configuration Format** | YAML with repo URLs and hook IDs | Python settings with intelligent defaults |
| **Hook Discovery** | Manual (add repos to`.pre-commit-config.yaml`) | Automatic (17 tools pre-configured) |
| **Tool Installation** | Auto (pre-commit manages environments) | UV-based (one virtual environment) |
| **Learning Curve** | Medium (understand repos, hooks, stages) | Low (unified Python commands) |

### When to Use Each

**Choose Pre-commit when:**

- ✅ Working with multiple languages (Go, Rust, Docker, etc.)
- ✅ Need language-agnostic hook framework
- ✅ Want to use hooks from community repositories
- ✅ Polyglot projects requiring diverse tooling
- ✅ Simple YAML-based configuration preferred

**Choose Crackerjack when:**

- ✅ Python-focused development (Python 3.13+)
- ✅ Want comprehensive development platform (testing, publishing, AI)
- ✅ Need maximum performance (async architecture, Rust tools, caching, 11x parallelism)
- ✅ Desire AI-powered auto-fixing and recommendations
- ✅ Want unified workflow (quality + tests + publishing in one command)
- ✅ Prefer Python-based configuration over YAML
- ✅ Need advanced features (coverage ratchet, MCP integration, monitoring)

### Migration from Pre-commit

Crackerjack can **coexist** with pre-commit if needed, but most Python projects can fully migrate:

```bash
# Remove pre-commit (optional)
pre-commit uninstall
rm .pre-commit-config.yaml

# Install crackerjack
uv tool install crackerjack

# Run quality checks (replaces pre-commit run --all-files)
python -m crackerjack run

# With tests (comprehensive workflow)
python -m crackerjack run --run-tests
```

**Note**: Crackerjack Phase 8 successfully migrated from pre-commit framework to direct tool invocation, achieving 50% performance improvement while maintaining full compatibility with existing quality standards.

## Guide

- [Installation](#installation)
- [Quick Start](#quick-start)
- [AI Auto-Fix Features](#ai-auto-fix-features)
- [Skills Tracking Integration](#skills-tracking-integration)
- [Core Workflow](#core-workflow)
- [Core Features](#core-features)
- [Legacy Architecture & Performance](#legacy-architecture--performance)
- [Adapters](#adapters)
- [MCP Server Configuration](#mcp-server-configuration)
- [Quality Hook Modes](#quality-hook-modes)
- [Command Reference](#command-reference)
- [Publishing & Version Management](#publishing--version-management)
- [Troubleshooting](#troubleshooting)

## Installation

### Prerequisites

- Python 3.13+
- [UV](https://github.com/astral-sh/uv) package manager

### Install UV

```bash
# Recommended: Official installer script
curl -LsSf https://astral.sh/uv/install.sh | sh

# Alternative: Using pipx
pipx install uv

# Alternative: Using Homebrew (macOS)
brew install uv
```

### Install Crackerjack

```bash
# Recommended: Using UV (fastest)
uv tool install crackerjack

# Alternative: Using pip
pip install crackerjack

# For existing project: Add as dependency
uv add crackerjack
```

## Quick Start

### Initialize a Project

```bash
# Navigate to your project directory
cd your-project

# Initialize with Crackerjack
python -m crackerjack run

# Or use interactive mode
python -m crackerjack run -i
```

## AI Auto-Fix Features

![AI Agent Orchestration](docs/diagrams/ai-agent-orchestration.png)
*12 specialized AI agents with confidence-based routing and batch processing*

Crackerjack provides two distinct approaches to automatic error fixing:

### 1. Hook Auto-Fix Modes (Basic Formatting)

Limited tool-specific auto-fixes for simple formatting issues:

- `ruff --fix`: Import sorting, basic formatting
- `trailing-whitespace --fix`: Removes trailing whitespace
- `end-of-file-fixer --fix`: Ensures files end with newline

**Limitations:** Only handles simple style issues, cannot fix type errors, security issues, test failures, or complex code quality problems.

### 2. AI Agent Auto-Fixing

AI-assisted code quality enforcement that can automatically fix many issue types:

#### How AI Agent Auto-Fixing Works

1. **Run All Checks**: Fast hooks, comprehensive hooks, full test suite
1. **Analyze Failures**: AI parses error messages and identifies likely root causes
1. **AI Fixes**: AI reads source code and makes targeted modifications
1. **Repeat**: Continue until checks pass or the iteration limit is reached (up to 8 iterations)
1. **Review Results**: Validate the generated changes before commit

#### Comprehensive Coverage

The AI agent can fix:

- **Type Errors (zuban)**: Adds missing annotations, fixes type mismatches
- **Security Issues (bandit)**: Security hardening including:
  - **Shell Injection Prevention**: Removes `shell=True` from subprocess calls
  - **Weak Cryptography**: Replaces MD5/SHA1 with SHA256
  - **Insecure Random Functions**: Replaces `random.choice` with `secrets.choice`
  - **Unsafe YAML Loading**: Replaces `yaml.load` with `yaml.safe_load`
  - **Token Exposure**: Masks PyPI tokens, GitHub PATs, and sensitive credentials
  - **Debug Print Removal**: Eliminates debug prints containing sensitive information
- **Dead Code (vulture)**: Removes unused imports, variables, functions
- **Performance Issues**: Reworks inefficient patterns (list concatenation, string building, nested loops)
- **Documentation Issues**: Auto-generates changelogs, maintains consistency across .md files
- **Test Failures**: Fixes missing fixtures, import errors, assertions
- **Code Quality (refurb)**: Applies refactoring, reduces complexity
- **All Hook Failures**: Formatting, linting, style issues

#### AI Agent Commands

```bash
# Standard AI agent mode (recommended)
python -m crackerjack run --ai-fix --run-tests --verbose

# Preview fixes without applying (dry-run mode)
python -m crackerjack run --dry-run --run-tests --verbose

# Custom iteration limit
python -m crackerjack run --ai-fix --max-iterations 15

# MCP server
python -m crackerjack start

# Lifecycle commands (start/stop/restart/status/health) are available via MCPServerCLIFactory.
```

#### MCP Integration

When using crackerjack via MCP tools (session-buddy):

```python
# ✅ CORRECT - Use semantic command + ai_agent_mode parameter
crackerjack_run(command="test", ai_agent_mode=True)

# ✅ CORRECT - With additional arguments
crackerjack_run(command="check", args="--verbose", ai_agent_mode=True, timeout=600)

# ✅ CORRECT - Dry-run mode
crackerjack_run(command="test", args="--dry-run", ai_agent_mode=True)

# ❌ WRONG - Don't put flags in command parameter
crackerjack_run(command="--ai-fix -t")  # This will error!

# ❌ WRONG - Don't use --ai-fix in args
crackerjack_run(command="test", args="--ai-fix")  # Use ai_agent_mode=True instead
```

#### Configuration

Auto-fix requires:

1. **Anthropic API key**: Set environment variable

   ```bash
   export ANTHROPIC_API_KEY=sk-ant-...
   ```

1. **Configuration file**: `settings/adapters.yml`

   ```yaml
   ai: claude
   ```

#### Key Benefits

- **Simple Invocation**: No complex flag combinations needed
- **Workflow Automation**: Can handle the quality workflow automatically
- **Context-Aware Analysis**: Uses code context and business logic when proposing changes
- **Broad Coverage**: Handles more than formatting-only fixes
- **Reviewable Results**: Produces changes that should still be reviewed before merge

#### Specialized Agent Architecture

**12 Specialized AI Agents** for code quality improvements:

- **SecurityAgent**: Fixes shell injections, weak crypto, token exposure, unsafe library usage
- **RefactoringAgent**: Reduces complexity ≤15, extracts helper methods, applies SOLID principles
- **PerformanceAgent**: Optimizes algorithms, fixes O(n²) patterns, improves string building
- **DocumentationAgent**: Auto-generates changelogs, maintains .md file consistency
- **DRYAgent**: Eliminates code duplication, extracts common patterns to utilities
- **FormattingAgent**: Handles code style, import organization, formatting violations
- **TestCreationAgent**: Fixes test failures, missing fixtures, dependency issues
- **ImportOptimizationAgent**: Removes unused imports, restructures import statements
- **TestSpecialistAgent**: Advanced testing scenarios, fixture management
- **SemanticAgent**: Advanced semantic analysis, code comprehension, refactoring suggestions based on business logic understanding
- **ArchitectAgent**: High-level architectural patterns, design recommendations, system-level optimization strategies
- **EnhancedProactiveAgent**: Early issue detection, predictive quality monitoring, and pre-merge optimization

**Agent Coordination Features**:

- **Confidence Scoring**: Routes issues to best-match agent (≥0.7 confidence)
- **Batch Processing**: Groups related issues for efficient parallel processing
- **Collaborative Mode**: Multiple agents handle complex cross-cutting concerns

#### Security & Safety Features

- **Command Validation**: All AI modifications are validated for safety
- **Regex Validation**: Centralized pattern checks reduce dangerous regex issues
- **No Shell Injection**: Uses secure subprocess execution with validated patterns
- **Rollback Support**: All changes can be reverted via git
- **Human Review**: Review AI-generated changes before commit

#### High-Performance Rust Tool Integration

**High-Performance Static Analysis Tools**:

- **Skylos** (Dead Code Detection): Replaces vulture with **20x performance improvement**

  - Rust-powered dead code detection and import analysis
  - Integrates with crackerjack's quality workflow
  - Zero configuration changes required

- **Zuban** (Type Checking): Replaces pyright with **20-200x performance improvement**

  - Fast type checking and static analysis
  - Drop-in replacement for slower Python-based tools
  - Maintains full compatibility with existing configurations

**Performance Benefits**:

- **Shorter Development Cycles**: Quality hooks complete faster than the previous toolchain
- **Faster Feedback**: Tool output returns quickly during development
- **Integration**: Works with existing crackerjack workflows
- **Stable CLI Surface**: Keeps the same CLI interface while improving performance

**Implementation Details**:

```bash
# These commands now benefit from Rust tool speed improvements:
python -m crackerjack run                    # Dead code detection 20x faster
python -m crackerjack run --run-tests        # Type checking 20-200x faster
python -m crackerjack run --ai-fix --run-tests # Complete workflow optimized
```

**Benchmark Results**: Internal measurements show higher throughput during comprehensive quality checks.

## Skills Tracking Integration

Crackerjack integrates with **session-buddy** for AI agent metrics tracking and skill recommendations.

### What is Skills Tracking?

**Automated metrics collection** for all AI agent invocations:

- **Which agents were selected** - Track agent choices and why
- **User queries** - Record problems that triggered agent selection
- **Alternatives considered** - Log which other agents were evaluated
- **Success/failure rates** - Measure agent effectiveness by context
- **Performance metrics** - Duration, completion rates, by workflow phase
- **Semantic discovery** - Find best agents for problems using vector similarity

### Why It Matters

**Learn from Every Agent Invocation**:

- 🎯 **Better Agent Selection**: Learn which agents work best for specific problems
- 📊 **Performance Insights**: Identify bottlenecks and optimization opportunities
- 🧠 **Semantic Discovery**: Find agents using natural language queries
- 🔄 **Continuous Improvement**: System gets smarter with every invocation
- 📈 **Workflow Correlation**: Understand agent effectiveness by Oneiric phase

### Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Crackerjack                              │
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐│
│  │  Agent        │    │  Agent        │    │  Agent        ││
│  │  Orchestrator │───▶│  Context      │───▶│  Skills       ││
│  │              │    │              │    │  Tracker      ││
│  └───────────────┘    └───────────────┘    └───────┬───────┘│
│                                                 │          │
└─────────────────────────────────────────────────┼───────────┘
                                                  │
                              ┌─────────────────────┴─────────────────┐
                              │   Skills Tracking Protocol           │
                              │  (track_invocation, get_recommendations)│
                              └─────────────────────┬─────────────────┘
                                                  │
                    ┌─────────────────────────────┼─────────────────────┐
                    │                             │                     │
            ┌───────▼────────┐          ┌────────▼────────┐    ┌───────▼──────┐
            │  Direct API   │          │   MCP Bridge    │    │   No-Op      │
            │  (Tight Coupling)│       │  (Loose Coupling)│    │  (Disabled)  │
            │  session-buddy│          │  session-buddy  │    │              │
            └───────────────┘          └─────────────────┘    └──────────────┘
                    │
            ┌───────▼────────┐
            │ Dhara Storage│
            │ (SQLite + WAL) │
            └────────────────┘
```

### Configuration

**Enable/Disable in `settings/local.yaml` or `settings/crackerjack.yaml`**:

```yaml
# Enable skills tracking (default: true)
skills:
  enabled: true

  # Backend choice: "direct", "mcp", "auto"
  backend: auto  # Tries MCP first, falls back to direct

  # Database location (default: .session-buddy/skills.db)
  db_path: null

  # MCP server URL (for MCP bridge)
  mcp_server_url: "http://localhost:8678"

  # Recommendation settings
  min_similarity: 0.3          # Minimum similarity for recommendations (0.0-1.0)
  max_recommendations: 5       # Max agents to recommend
  enable_phase_aware: true     # Consider workflow phase in recommendations
  phase_weight: 0.3           # Weight for phase effectiveness (0.0-1.0)
```

### Backend Options

| Backend | Pros | Cons | Best For |
| -------------------- | -------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- |
| **`direct`** | • Fast (direct API)<br>• Simple setup<br>• Low latency | • Tight coupling<br>• Requires session-buddy in Python path | • Local development<br>• Single-machine setups |
| **`mcp`** | • Loose coupling<br>• Remote deployment<br>• Easy testing | • Higher latency<br>• More complex | • Distributed systems<br>• Microservices<br>• Multi-project setups |
| **`auto`** (default) | • Tries MCP first<br>• Automatic fallback<br>• Best of both | • Slightly slower initial connection | • Most scenarios (recommended) |

### Usage Patterns

#### 1. Automatic Tracking (Default)

All agent invocations are **automatically tracked** via `AgentOrchestrator`:

```python
# In agent_orchestrator.py
async def _execute_crackerjack_agent(agent, request):
    # Automatic tracking
    completer = request.context.track_skill_invocation(
        skill_name=agent.metadata.name,
        user_query=request.task.description,
        workflow_phase=request.task.category,
    )

    try:
        result = await agent.agent.analyze_and_fix(issue)
        completer(completed=True)  # Record success
    except Exception as e:
        completer(completed=False, error_type=str(e))  # Record failure
        raise
```

#### 2. Manual Tracking in Custom Code

```python
from crackerjack.agents.base import AgentContext

# Track with manual control
context = AgentContext(
    project_path=Path("/my/project"),
    skills_tracker=tracker,  # From dependency injection
)

# Track invocation
completer = context.track_skill_invocation(
    skill_name="MyCustomAgent",
    user_query="Fix complexity issues",
    workflow_phase="comprehensive_hooks",
)

# ... do work ...

# Complete tracking
completer(completed=True)
```

#### 3. Get Recommendations

```python
# Get agent recommendations for a problem
recommendations = context.get_skill_recommendations(
    user_query="How do I fix type errors in async code?",
    limit=5,
    workflow_phase="comprehensive_hooks",
)

# Returns:
# [
#   {
#     "skill_name": "RefactoringAgent",
#     "similarity_score": 0.92,
#     "completed": True,
#     "duration_seconds": 45.2,
#     "workflow_phase": "comprehensive_hooks"
#   },
#   ...
# ]
```

### Data Migration

**Migrate from JSON-based metrics to Dhara database**:

```bash
# 1. Backup existing JSON
cp .crackerjack/metrics.json .crackerjack/metrics.json.backup

# 2. Run migration (dry-run first)
python scripts/migrate_skills_to_sessionbuddy.py --dry-run

# 3. Actual migration
python scripts/migrate_skills_to_sessionbuddy.py

# 4. Validate migration
python scripts/validate_skills_migration.py

# 5. Rollback if needed
python scripts/rollback_skills_migration.py
```

**Migration Features**:

- ✅ **Automatic backup** - Creates `.pre-migration.backup` files
- ✅ **Dry-run mode** - Preview changes without modifying database
- ✅ **Validation** - Checks JSON structure and required fields
- ✅ **Rollback support** - Restore from backup if issues occur
- ✅ **Progress tracking** - See migration status in real-time

### Performance Considerations

**Direct API (Tight Coupling)**:

- **Latency**: < 1ms per invocation (in-process)
- **Throughput**: 10,000+ invocations/second
- **Memory**: ~5MB per session
- **Best for**: Local development, single-machine setups

**MCP Bridge (Loose Coupling)**:

- **Latency**: 5-10ms per invocation (network round-trip)
- **Throughput**: 1,000+ invocations/second
- **Memory**: ~10MB per session (includes client)
- **Best for**: Distributed systems, microservices

**Overhead**:

- **No-op (disabled)**: Zero overhead (~0.001µs per check)
- **Direct**: ~0.5% overhead in typical workflows
- **MCP**: ~2% overhead in typical workflows

### Advanced Features

#### Semantic Skill Discovery

```python
# Find agents using natural language
recommendations = tracker.get_recommendations(
    user_query="I need help with memory leaks in async code", limit=5
)

# Semantic search finds:
# - PerformanceAgent (specializes in leaks)
# - RefactoringAgent (async patterns)
# - TestSpecialistAgent (memory testing)
```

#### Workflow-Phase-Aware Recommendations

```python
# Get recommendations for specific Oneiric phase
recommendations = tracker.get_recommendations(
    user_query="Fix import errors",
    workflow_phase="fast_hooks",  # Only agents effective in fast_hooks
    limit=3,
)

# Considers:
# - Which agents work best in fast_hooks phase
# - Historical completion rates by phase
# - Average duration by phase
```

#### Selection Ranking

```python
# Track which alternative agents were considered
completer = context.track_skill_invocation(
    skill_name="RefactoringAgent",  # Selected agent
    user_query="Fix complexity",
    alternatives_considered=["PerformanceAgent", "DRYAgent"],
    selection_rank=1,  # First choice
)
```

### Troubleshooting

**Skills tracking not working**:

```bash
# Check if session-buddy is available
python -c "from session_buddy.core.skills_tracker import get_session_tracker; print('OK')"

# Verify configuration
python -c "from crackerjack.config import CrackerjackSettings; s = CrackerjackSettings.load(); print(s.skills)"

# Check database
ls -la .session-buddy/skills.db
```

**MCP connection failures**:

```bash
# Verify MCP server is running
python -m crackerjack status

# Test MCP connection
curl http://localhost:8678/health

# Check fallback to direct tracking
# MCP failures automatically fall back to direct API
```

**Migration issues**:

```bash
# Validate JSON before migration
python scripts/validate_skills_migration.py --json-only

# Run with verbose output
python scripts/migrate_skills_to_sessionbuddy.py --verbose

# Rollback if needed
python scripts/rollback_skills_migration.py --force
```

### See Also

- **CLAUDE.md**: Complete developer documentation with integration examples
- **docs/features/SKILLS_INTEGRATION.md\`**: Detailed feature documentation
- **scripts/migrate_skills_to_sessionbuddy.py\`**: Migration tool source code

## Core Workflow

**Three-stage quality enforcement with code cleaning:**

1. **Fast Hooks** (~5 seconds): Essential formatting and security checks
1. **Code Cleaning Stage** (between fast and comprehensive): AI-assisted cleanup before the comprehensive hook run
1. **Comprehensive Hooks** (~30 seconds): Complete static analysis on cleaned code

**Optimal Execution Order**:

- **Fast hooks first** # → **retry once if any fail** (formatting fixes cascade to other issues)
- **Code cleaning** # → Remove TODO detection, apply standardized patterns
- **Post-cleaning fast hooks sanity check** # → Ensure cleaning didn't introduce issues
- **Full test suite** # → Collect ALL test failures (don't stop on first)
- **Comprehensive hooks** # → Collect ALL quality issues on clean codebase
- **AI batch fixing** # → Process all collected issues intelligently

**With AI integration:**

- `--ai-fix` flag enables automatic error resolution with specialized sub-agents
- MCP server allows AI agents to run crackerjack commands with real-time progress tracking
- Structured error output for programmatic fixes with confidence scoring
- Centralized regex pattern system ensures safe automated text transformations

## Core Features

### Project Management

- **Effortless Project Setup:** Initializes new Python projects with a standard directory structure, `pyproject.toml`, and essential configuration files
- **UV Integration:** Manages dependencies and virtual environments using [UV](https://github.com/astral-sh/uv) for fast package operations
- **Dependency Management:** Automatically detects and manages project dependencies

### Code Quality

- **Automated Code Cleaning:** Removes unnecessary docstrings, line comments, and trailing whitespace
- **Consistent Code Formatting:** Enforces a unified style using [Ruff](https://github.com/astral-sh/ruff), the Python linter and formatter
- **Comprehensive Quality Hooks:** Direct tool invocation with no wrapper overhead - runs Python tools, Rust analyzers, and security scanners efficiently
- **Interactive Checks:** Supports interactive quality checks (like `refurb`, `bandit`, and `pyright`) to fix issues in real-time
- **Static Type Checking:** Enforces type safety with Pyright integration

### Testing & Coverage Ratchet System

- **Built-in Testing:** Automatically runs tests using `pytest` with parallelization
- **Coverage Ratchet:** Coverage ratchet system that targets 100% - coverage can only increase, never decrease
- **Milestone Celebrations:** Progress tracking with milestone achievements (15%, 20%, 25%... # → 100%)
- **No Arbitrary Limits:** Replaced traditional hard limits with continuous improvement toward perfection
- **Visual Progress:** Rich terminal displays showing journey to 100% coverage
- **Benchmark Testing:** Performance regression detection and monitoring
- **Easy Version Bumping:** Provides commands to bump the project version (patch, minor, or major)
- **Simplified Publishing:** Automates publishing to PyPI via UV with enhanced authentication

#### Coverage Ratchet Philosophy

**Target: 100% Coverage** - A project policy backed by the coverage ratchet
📈 **Continuous Improvement** - Each test run can only maintain or improve coverage
🏆 **Milestone System** - Celebrate achievements at 15%, 25%, 50%, 75%, 90%, and 100%
🚫 **No Regression** - Once you achieve a coverage level, you can't go backward

```bash
# Show coverage progress
python -m crackerjack run --coverage-report

# Run tests with ratchet system
python -m crackerjack run --run-tests

# Example output:
# 🎉 Coverage improved from 10.11% to 15.50%!
# 🏆 Milestone achieved: 15% coverage!
# 📈 Progress: [███░░░░░░░░░░░░░░░░░] 15.50% # → 100%
# 🎯 Next milestone: 20% (+4.50% needed)
```

### Git Integration

- **Suggested Commit Messages:** Analyzes git changes and suggests commit messages based on file types and modifications
- **Commit and Push:** Commits and pushes your changes with standardized commit messages
- **Pull Request Creation:** Creates pull requests to upstream repositories on GitHub or GitLab
- **Git Hook Integration:** Ensures code quality before commits with fast, direct tool execution

## Legacy Architecture & Performance

![Oneiric Workflow DAG](docs/diagrams/oneiric-workflow-dag.png)
*Complete execution pipeline: CLI → Workflow Selection → Fast/Comprehensive Hooks → Tests → AI Batch Fixing*

Crackerjack is built on the **legacy DI framework** framework, providing dependency injection, caching, and parallel execution.

### What is the legacy architecture?

[legacy](https://github.com/lesleslie/crackerjack) is a lightweight dependency injection framework that enables:

- **Module-level registration** via `depends.set()` for clean dependency management
- **Runtime-checkable protocols** ensuring type safety across all components
- **Async-first design** with lifecycle management and timeout strategies
- **Clean separation of concerns** through adapters, orchestrators, and services

### Architecture Overview

**legacy Workflow Engine (Default since Phase 4.2)**

```
User Command # → BasicWorkflowEngine (legacy)
    ↓
Workflow Selection (Standard/Fast/Comprehensive/Test)
    ↓
Action Handlers (run_fast_hooks, run_code_cleaning, run_comprehensive_hooks, run_test_workflow)
    ↓
asyncio.to_thread() for non-blocking execution
    ↓
WorkflowPipeline (DI-injected via context)
    ↓
Phase Execution (_run_fast_hooks_phase, _run_comprehensive_hooks_phase, etc.)
    ↓
HookManager + TestManager (Manager Layer: 80% compliant)
    ↓
Direct adapter.check() calls (No subprocess overhead)
    ↓
ToolProxyCacheAdapter (Content-based caching, 70% hit rate)
    ↓
Parallel Execution (Up to 11 concurrent adapters)
    ↓
Results Aggregation with real-time console output
```

**Legacy Orchestrator Path** (opt-out with `--use-legacy-orchestrator`)

```
User Command # → WorkflowOrchestrator (Legacy)
    ↓
SessionCoordinator (@depends.inject + protocols)
    ↓
PhaseCoordinator (Orchestration Layer)
    ↓
HookManager + TestManager
    ↓
[Same execution path as legacy from here...]
```

**Architecture Compliance (Phase 2-4.2 Audit Results)**

| Layer | Compliance | Status | Notes |
| ------------------------ | ---------- | ------------- | ------------------------------------------------------------ |
| **legacy Workflows** | 95% | ✅ Production | **Default since Phase 4.2** - Real-time output, non-blocking |
| **CLI Handlers** | 90% | ✅ Excellent | Gold standard:`@depends.inject` + `Inject[Protocol]` |
| **Services** | 95% | ✅ Excellent | Phase 3 refactored, consistent constructors |
| **Managers** | 80% | ✅ Good | Protocol-based injection, minor improvements needed |
| **Legacy Orchestration** | 70% | ⚠️ Opt-out | Available with`--use-legacy-orchestrator` |
| **Coordinators** | 70% | ⚠️ Mixed | Phase coordinators ✅, async needs standardization |
| **Agent System** | 40% | 📋 Legacy | Uses`AgentContext` pattern (predates legacy) |

**Key Architectural Patterns**

```python
# ✅ GOLD STANDARD Pattern (from CLI Handlers)
from legacy.depends import depends, Inject
from crackerjack.models.protocols import Console


@depends.inject
def setup_environment(console: Inject[Console] = None, verbose: bool = False) -> None:
    """Protocol-based injection with @depends.inject decorator."""
    console.print("[green]Environment ready[/green]")


# ❌ ANTI-PATTERN: Avoid manual fallbacks
def setup_environment_wrong(console: Console | None = None):
    self.console = console or Console()  # Bypasses DI container
```

### Performance Benefits

| Metric | Legacy | legacy Workflows (Phase 4.2) | Improvement |
| ----------------------- | --------------- | ---------------------------- | ---------------- |
| **Fast Hooks** | ~45s | ~48s | Comparable |
| **Full Workflow** | ~60s | ~90s | Real-time output |
| **Console Output** | Buffered | **Real-time streaming** | UX improvement |
| **Event Loop** | Sync (blocking) | **Async (non-blocking)** | Responsive |
| **Cache Hit Rate** | 0% | **70%** | New capability |
| **Concurrent Adapters** | 1 | **11** | 11x parallelism |
| **DI Context** | Manual | **Protocol-based injection** | Type safety |

### Core Components

#### 1. Quality Assurance Adapters

**Location:** `crackerjack/adapters/`

legacy-registered adapters for all quality checks:

- **Format:** Ruff formatting, mdformat
- **Lint:** Codespell, complexity analysis
- **Security:** Bandit security scanning, Gitleaks secret detection
- **Type:** Zuban type checking (20-200x faster than Pyright)
- **Refactor:** Creosote (unused dependencies), Refurb (Python idioms)
- **Complexity:** Complexipy analysis
- **Utility:** Various validation checks
- **AI:** Claude integration for auto-fixing

#### 2. Hook Orchestrator

**Location:** `crackerjack/orchestration/hook_orchestrator.py`

Features:

- **Dual execution mode:** Legacy (pre-commit CLI) + legacy (direct adapters)
- **Dependency resolution:** Hook ordering (e.g., format before lint)
- **Adaptive strategies:** Fast, comprehensive, or dependency-aware execution
- **Graceful degradation:** Timeout strategies prevent hanging

#### 3. Cache Adapters

**Location:** `crackerjack/orchestration/cache/`

Two caching strategies:

- **ToolProxyCache:** Content-based caching with file hash verification
- **MemoryCache:** In-memory LRU cache for testing

Benefits:

- **70% cache hit rate** in typical workflows
- **Content-aware invalidation:** Only re-runs when files actually change
- **Configurable TTL:** Default 3600s (1 hour)

#### 4. MCP Server Integration

**Location:** `crackerjack/mcp/`

legacy-registered services:

- **MCPServerService:** FastMCP server for AI agent integration
- **ErrorCache:** Pattern tracking for AI fix recommendations
- **JobManager:** WebSocket job tracking and progress streaming
- **WebSocketSecurityConfig:** Security hardening (localhost-only, rate limiting)

### Migration from Pre-commit

Crackerjack has migrated from pre-commit subprocess calls to direct adapter execution:

**Old Approach (Pre-commit):**

```bash
pre-commit run ruff --all-files  # Subprocess overhead
```

**New Approach (legacy):**

```bash
python -m crackerjack run --fast  # Direct Python API, 70% faster
```

**Migration Guide:** See `docs/README.md` (Migration Notes)

### Configuration Management

Crackerjack utilizes a **dual configuration system** to handle both runtime application settings and project configuration templates:

#### 1. Runtime Configuration (settings)

**settings** manages application runtime configuration:

**Before (11 config files, ~1,808 LOC):**

```python
from crackerjack.models.config import WorkflowOptions, HookConfig
from crackerjack.orchestration.config import OrchestrationConfig
# ... multiple configuration imports
```

**After (1 settings file, ~300 LOC):**

```python
from legacy.depends import depends
from crackerjack.config import CrackerjackSettings

settings = depends.get(CrackerjackSettings)
# Auto-loads from: env vars (CRACKERJACK_*), .env file, defaults
```

**Benefits:**

- **83% LOC reduction** in configuration code
- **Automatic environment variable loading** (CRACKERJACK\_\* prefix)
- **Type validation** via Pydantic
- **Single source of truth** for all runtime settings
- **Backward compatible** - Public API unchanged (`create_workflow_options()`)

#### 2. Project Configuration Templates (ConfigTemplateService)

**ConfigTemplateService** manages project-level configuration templates for files like `.pre-commit-config.yaml` and `pyproject.toml`:

```bash
# Check for available configuration updates
python -m crackerjack run --check-config-updates

# Show diff for specific configuration type
python -m crackerjack run --diff-config pre-commit

# Apply configuration updates interactively
python -m crackerjack run --apply-config-updates --config-interactive

# Refresh configuration cache
python -m crackerjack run --refresh-cache
```

**ConfigTemplateService Benefits:**

- **Version-based tracking** - Each configuration has version control
- **User-controlled updates** - Explicit approval required for changes
- **Diff visibility** - Shows changes before applying
- **Cache management** - Automatic pre-commit cache invalidation
- **Template management** - Centralized configuration templates as code

**Config Merge Service (Initialization)**

The ConfigMergeService handles configuration merging during project initialization:

```python
# Used by InitializationService for new project setup
merge_result = config_merge_service.smart_merge_pyproject(
    source_config, target_path, project_name
)
```

**For Complete Configuration System Details:** See `docs/README.md` (Project Structure and Coding Standards).

**Migration Details:** See `docs/README.md` (Migration Notes)

### Using the legacy dependency injection system

Example: Custom QA Adapter

```python
import uuid
from contextlib import suppress
from legacy.depends import depends
from crackerjack.adapters._qa_adapter_base import QAAdapterBase

# Module-level registration (legacy pattern)
MODULE_ID = uuid.UUID("01937d86-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
MODULE_STATUS = "stable"


class CustomAdapter(QAAdapterBase):
    @property
    def adapter_name(self) -> str:
        return "Custom Checker"

    @property
    def module_id(self) -> uuid.UUID:
        return MODULE_ID

    async def check(self, files, config):
        # Your quality check logic here
        return QAResult(passed=True, issues=[])


# Register with DI container
with suppress(Exception):
    depends.set(CustomAdapter)
```

### Performance Optimization

#### Caching

- **Content-based keys:** `{hook_name}:{config_hash}:{content_hash}`
- **File hash verification:** Detects actual file changes, not just timestamps
- **LRU eviction:** Automatic cleanup of old entries

#### Parallel Execution

- **Dependency-aware scheduling:** Runs independent hooks in parallel
- **Semaphore control:** Prevents resource exhaustion
- **Async I/O:** 76% faster for I/O-bound operations

#### Timeout Strategies

- **Graceful degradation:** Continues execution even if one hook times out
- **Configurable limits:** Default 60s per hook, 300s overall
- **Context managers:** Automatic cleanup on timeout

### Legacy architecture benefits

1. **Type Safety:** Runtime-checkable protocols ensure correctness
1. **Testability:** Easy mocking with `depends.get()`
1. **Maintainability:** Clear separation between adapters and orchestration
1. **Observability:** Structured logging with context fields
1. **Security:** Input validation, timeout protection, origin validation
1. **Performance:** 47% faster overall execution with caching

### Documentation

- See `docs/README.md` for consolidated documentation and references.
- **Code Review Report:** Available from maintainers

**Status:** ✅ Production Ready (as of 2025-10-09)

## Advanced Pattern Management System

![Pattern Management](docs/diagrams/pattern-management.png)
*Centralized pattern registry with validation, safety limits, and thread-safe caching*

### Advanced Regex Pattern Validation

Crackerjack includes a centralized regex pattern management system that reduces dangerous regex issues through validation and safety controls.

#### Key Components

**📦 Centralized Pattern Registry** (`crackerjack/services/regex_patterns.py`):

- **18+ validated patterns** for security, formatting, version management
- **ValidatedPattern class** with comprehensive testing and safety limits
- **Thread-safe compiled pattern caching** for performance
- **Iterative application** for complex multi-word cases (e.g., `pytest - hypothesis - specialist`)

**🔧 Pattern Categories**:

- **Command & Flag Formatting**: Fix spacing in `python -m command`, `--flags`, hyphenated names
- **Security Token Masking**: PyPI tokens, GitHub PATs, generic long tokens, assignment patterns
- **Version Management**: Update `pyproject.toml` versions, coverage requirements
- **Code Quality**: Subprocess security fixes, unsafe library replacements, formatting normalization
- **Test Optimization**: Assert statement normalization, job ID validation

**⚡ Performance & Safety Features**:

```python
# Thread-safe pattern cache with size limits
CompiledPatternCache.get_compiled_pattern(pattern)

# Safety limits prevent catastrophic backtracking
MAX_INPUT_SIZE = 10 * 1024 * 1024  # 10MB max
MAX_ITERATIONS = 10  # Iterative application limit

# Iterative fixes for complex cases
pattern.apply_iteratively("pytest - hypothesis - specialist")
# # → "pytest-hypothesis-specialist"

# Performance monitoring capabilities
pattern.get_performance_stats(text, iterations=100)
```

#### Security Pattern Examples

**Token Masking Patterns**:

```python
# PyPI tokens (word boundaries prevent false matches)
"pypi-AgEIcHlwaS5vcmcCJGE4M2Y3ZjI"  # → "pypi-****"

# GitHub personal access tokens (exactly 40 chars)
"ghp_1234567890abcdef1234567890abcdef1234"  # → "ghp_****"

# Generic long tokens (32+ chars with word boundaries)
"secret_key=abcdef1234567890abcdef1234567890abcdef"  # → "secret_key=****"
```

**Subprocess Security Fixes**:

```python
# Automatic shell injection prevention
subprocess.run(cmd, shell=True)  # → subprocess.run(cmd.split())
subprocess.call(cmd, shell=True)  # → subprocess.call(cmd.split())
```

**Unsafe Library Replacements**:

```python
# Weak crypto # → Strong crypto
hashlib.md5(data)  # → hashlib.sha256(data)
hashlib.sha1(data)  # → hashlib.sha256(data)

# Insecure random # → Cryptographic random
random.choice(options)  # → secrets.choice(options)

# Unsafe YAML # → Safe YAML
yaml.load(file)  # → yaml.safe_load(file)
```

#### Pattern Validation Requirements

**Every pattern MUST include**:

- ✅ **Comprehensive test cases** (positive, negative, edge cases)
- ✅ **Replacement syntax validation** (no spaces in `\g<N>`)
- ✅ **Safety limits** and performance monitoring
- ✅ **Thread-safe compilation** and caching
- ✅ **Descriptive documentation** and usage examples

**Quality Guarantees**:

- **Zero regex-related bugs** since implementation
- **Performance optimized** with compiled pattern caching
- **Security hardened** with input size limits and validation
- **Maintenance friendly** with centralized pattern management

### Pre-commit Regex Validation Hook

**Future Enhancement**: Automated validation hook to ensure all regex usage follows safe patterns:

```bash
# Validates all .py files for regex pattern compliance
python -m crackerjack run.tools.validate_regex_usage
```

This pattern management system standardizes regex validation and helps reduce spacing and security issues in text processing.

## Adapters

![Adapter Taxonomy](docs/diagrams/adapter-taxonomy.png)
*18 QA adapters organized by category with protocol-based registration*

Adapters connect Crackerjack to external tools and subsystems (e.g., Ruff, Zuban, Bandit) using legacy patterns. Each adapter exposes typed settings, async initialization, and standardized results.

- AI — Claude-powered code fixes: [crackerjack/adapters/ai/README.md](./crackerjack/adapters/ai/README.md)
- Complexity — Code complexity analysis (Complexipy): [crackerjack/adapters/complexity/README.md](./crackerjack/adapters/complexity/README.md)
- Format — Python/Markdown formatting (Ruff, Mdformat): [crackerjack/adapters/format/README.md](./crackerjack/adapters/format/README.md)
- Lint — Spelling and simple linters (Codespell): [crackerjack/adapters/lint/README.md](./crackerjack/adapters/lint/README.md)
- LSP — Rust tools with LSP (Zuban, Skylos): [crackerjack/adapters/lsp/README.md](./crackerjack/adapters/lsp/README.md)
- Refactor — Modernization, dead code, unused deps (Refurb, Skylos, Creosote): [crackerjack/adapters/refactor/README.md](./crackerjack/adapters/refactor/README.md)
- Security — Static analysis and secrets (Bandit, Gitleaks, Pyscn): [crackerjack/adapters/security/README.md](./crackerjack/adapters/security/README.md)
- Type — Static type checking (Zuban, Pyrefly, Ty): [crackerjack/adapters/type/README.md](./crackerjack/adapters/type/README.md)
- Utility — Config-driven checks (EOF newline, regex, size, lock): [crackerjack/adapters/utility/README.md](./crackerjack/adapters/utility/README.md)

Quick index: [crackerjack/adapters/README.md](./crackerjack/adapters/README.md).

## MCP Server Configuration

### What is MCP?

Model Context Protocol (MCP) enables AI agents to interact directly with Crackerjack's CLI tools for autonomous code quality fixes.

### Setup MCP Server

1. **Install development dependencies (includes MCP tools):**

   ```bash
   uv sync --group dev
   ```

1. **Start the MCP server:**

   ```bash
   # Start MCP server
   python -m crackerjack start
   ```

1. **Configure your MCP client (e.g., Claude Desktop):**

   Add to your MCP configuration file (`mcp.json`):

   **For installed crackerjack (from PyPI):**

   ```json
   {
     "mcpServers": {
       "crackerjack": {
         "command": "uvx",
         "args": [
           "crackerjack",
           "start"
         ],
         "env": {
           "UV_KEYRING_PROVIDER": "subprocess",
           "EDITOR": "code --wait"
         }
       }
     }
   }
   ```

   **For local development version:**

   ```json
   {
     "mcpServers": {
       "crackerjack": {
         "command": "uvx",
         "args": [
           "--from",
           "/path/to/crackerjack",
           "crackerjack",
           "start"
         ],
         "env": {
           "UV_KEYRING_PROVIDER": "subprocess",
           "EDITOR": "code --wait"
         }
       }
     }
   }
   ```

### Environment Variables & Security

Crackerjack supports several environment variables for configuration:

- **UV_PUBLISH_TOKEN\`**: PyPI authentication token for publishing ⚠️ **Keep secure!**
- **UV_KEYRING_PROVIDER\`**: Keyring provider for secure credential storage (e.g., "subprocess")
- **EDITOR\`**: Default text editor for interactive commit message editing (e.g., "code --wait")
- **AI_AGENT\`**: Set to "1" to enable AI agent mode with structured JSON output

#### Security Best Practices

**Token Security:**

- **Never commit tokens to version control**
- Use `.env` files (add to `.gitignore`)
- Prefer keyring over environment variables
- Rotate tokens regularly

**Recommended setup:**

```bash
# Create .env file (add to .gitignore)
echo "UV_PUBLISH_TOKEN=pypi-your-token-here" > .env
echo ".env" >> .gitignore

# Or use secure keyring storage
keyring set https://upload.pypi.org/legacy/ __token__
```

**Example MCP configuration with environment variables:**

```json
{
  "mcpServers": {
    "crackerjack": {
      "command": "uvx",
      "args": [
        "--from",
        "/path/to/crackerjack",
        "crackerjack",
        "start"
      ],
      "env": {
        "UV_KEYRING_PROVIDER": "subprocess",
        "EDITOR": "code --wait",
        "UV_PUBLISH_TOKEN": "pypi-your-token-here"
      }
    }
  }
}
```

### Available MCP Tools

**Job Execution & Monitoring:**

- **execute_crackerjack\`**: Start iterative auto-fixing with job tracking
- **get_job_progress\`**: Real-time progress for running jobs
- **run_crackerjack_stage\`**: Execute specific quality stages (fast, comprehensive, tests)

**Error Analysis:**

- **analyze_errors\`**: Analyze and categorize code quality errors
- **smart_error_analysis\`**: AI-powered error analysis with cached patterns

**Session Management:**

- **get_stage_status\`**: Check current status of quality stages
- **get_next_action\`**: Get optimal next action based on session state
- **session_management\`**: Manage sessions with checkpoints and resume capability

### Slash Commands

**`/crackerjack:run`**: Autonomous code quality enforcement with AI agent

```bash
# Through MCP
{
  "command": "/crackerjack:run",
  "args": []
}
```

**`/crackerjack:init`**: Initialize or update project configuration

```bash
# Through MCP
{
  "command": "/crackerjack:init",
  "args": ["--force"]  # Optional: force reinitialize
}
```

## Quality Hook Modes

![Quality Hooks](docs/diagrams/quality-hooks.png)
*Fast hooks (~5s) and Comprehensive hooks (~30s) with retry logic and AI-fix integration*

Crackerjack runs quality checks in a two-stage process for optimal development workflow:

### Hook Details

**Fast Hooks (~5 seconds):**

- Ruff formatting and linting
- Trailing whitespace cleanup
- UV lock file updates
- Security credential detection
- Spell checking

**Comprehensive Hooks (~30 seconds):**

- Zuban type checking
- Bandit security analysis
- Dead code detection (vulture)
- Dependency analysis (creosote)
- Complexity limits (complexipy)
- Modern Python patterns (refurb)

```bash
# Default behavior runs comprehensive hooks
python -m crackerjack run

# Skip hooks if you only want setup/cleaning
python -m crackerjack run --skip-hooks
```

### Common Commands

```bash
# Quality checks only
python -m crackerjack run

# With testing
python -m crackerjack run --run-tests

# Xcode tests (macOS)
python -m crackerjack run --xcode-tests

# Full release workflow
python -m crackerjack run --all patch

# AI agent mode
python -m crackerjack run --ai-fix
```

## Quick Reference Index

**📋 Command Index by Use Case**

| Use Case | Command | Description |
| ----------------------- | -------------------------------------------------- | --------------------------------------- |
| **Basic Quality Check** | `python -m crackerjack run` | Run quality checks only |
| **Quality + Tests** | `python -m crackerjack run --run-tests` | Quality checks with test suite |
| **AI Auto-Fix** | `python -m crackerjack run --ai-fix --run-tests` | AI-powered fixing + tests (recommended) |
| **Full Release** | `python -m crackerjack run --all patch` | Version bump, quality checks, publish |
| **Quick Publish** | `python -m crackerjack run --publish patch` | Version bump + publish only |
| **Start MCP Server** | `python -m crackerjack start` | Launch MCP agent integration |
| **AI Debugging** | `python -m crackerjack run --ai-debug --run-tests` | Verbose AI debugging mode |
| **Coverage Status** | `python -m crackerjack run --coverage-status` | Show coverage ratchet progress |
| **Clear Caches** | `python -m crackerjack run --clear-cache` | Reset all cache data |
| **Fast Iteration** | `python -m crackerjack run --skip-hooks` | Skip quality checks during dev |
| **Documentation** | `python -m crackerjack run --generate-docs` | Generate API documentation |
| **Advanced Features** | See`docs/README.md` | Advanced flags and workflows |

**📑 Alphabetical Flag Reference**

| Flag | Short | Description |
| ----------------------- | ----- | --------------------------------------------------- |
| `--ai-debug` | - | Verbose debugging for AI auto-fixing |
| `--ai-fix` | - | Enable AI-powered auto-fixing |
| `--all` | `-a` | Full release workflow (bump, test, publish) |
| `--benchmark` | - | Run tests in benchmark mode |
| `--boost-coverage` | - | Auto-improve test coverage (default) |
| `--bump` | `-b` | Bump version (patch/minor/major/auto) |
| `--cache-stats` | - | Display cache statistics |
| `--clear-cache` | - | Clear all caches and exit |
| `--commit` | `-c` | Commit and push changes to Git |
| `--comp` | - | Run only comprehensive hooks |
| `--coverage-status` | - | Show coverage ratchet status |
| `--debug` | - | Enable debug output |
| `--dev` | - | Enable development mode for monitors |
| `--enhanced-monitor` | - | Advanced monitoring with patterns |
| `--fast` | - | Run only fast hooks |
| `--generate-docs` | - | Generate API documentation |
| `--interactive` | `-i` | Use Rich UI interface |
| `--monitor` | - | Multi-project progress monitor |
| `--orchestrated` | - | Advanced orchestrated workflow mode |
| `--publish` | `-p` | Bump version and publish to PyPI |
| `--quick` | - | Quick mode (3 iterations, for CI/CD) |
| `--run-tests` | `-t` | Execute test suite |
| `--skip-hooks` | `-s` | Skip pre-commit hooks |
| `--strip-code` | `-x` | Remove docstrings/comments |
| `--thorough` | - | Thorough mode (8 iterations) |
| `--verbose` | `-v` | Enable verbose output |
| `--watchdog` | - | Service watchdog with auto-restart |
| `--xcode-configuration` | - | Xcode build configuration |
| `--xcode-destination` | - | Xcode destination string |
| `--xcode-project` | - | Path to Xcode project for tests |
| `--xcode-scheme` | - | Xcode scheme to test |
| `--xcode-tests` | - | Run Xcode tests (can be combined with`--run-tests`) |

**🔗 Related Documentation**

- **Advanced Features**: See `docs/README.md` - consolidated advanced flags
- **Developer Guide**: [CLAUDE.md](./CLAUDE.md) - AI assistant guidelines and developer commands

______________________________________________________________________

## Command Reference

**Core Workflow Commands:**

```bash
# Quality checks and development
python -m crackerjack run                    # Quality checks only
python -m crackerjack run --run-tests        # Quality checks + tests
python -m crackerjack run --ai-fix --run-tests  # AI auto-fixing + tests (recommended)
python -m crackerjack run --xcode-tests      # Xcode tests (macOS)

# Release workflow
python -m crackerjack run --all patch # Full release workflow
python -m crackerjack run --publish patch      # Version bump + publish
```

**AI-Powered Development:**

```bash
python -m crackerjack run --ai-fix              # AI auto-fixing mode
python -m crackerjack run --ai-debug --run-tests # AI debugging with verbose output
python -m crackerjack run --ai-fix --run-tests --verbose # Full AI workflow
python -m crackerjack run --orchestrated        # Advanced orchestrated workflow
python -m crackerjack run --quick               # Quick mode (3 iterations max)
python -m crackerjack run --thorough            # Thorough mode (8 iterations max)
```

**Monitoring & Observability:**

```bash
python -m crackerjack run --monitor             # Multi-project progress monitor
python -m crackerjack run --enhanced-monitor    # Enhanced monitoring with patterns
python -m crackerjack run --watchdog            # Service watchdog (auto-restart)
```

**MCP Server Lifecycle Commands (Phase 3 Modernization):**

```bash
# New Typer-based commands (Phase 3)
python -m crackerjack start      # Start MCP server (fully functional)
python -m crackerjack stop       # Stop server
python -m crackerjack restart    # Restart server
python -m crackerjack status     # Server status
python -m crackerjack health     # Health check
python -m crackerjack health --probe  # Liveness probe

# Migration note: Legacy flags --start-mcp-server, --stop-mcp-server,
# --restart-mcp-server are still available under `crackerjack run`,
# but prefer these commands.
```

**Performance & Caching:**

```bash
python -m crackerjack run --cache-stats         # Display cache statistics
python -m crackerjack run --clear-cache         # Clear all caches
python -m crackerjack run --benchmark           # Run in benchmark mode
```

**Coverage Management:**

```bash
python -m crackerjack run --coverage-status     # Show coverage ratchet status
python -m crackerjack run --coverage-goal 85.0  # Set explicit coverage target
python -m crackerjack run --no-coverage-ratchet # Disable coverage ratchet temporarily
python -m crackerjack run --boost-coverage      # Auto-improve test coverage (default)
python -m crackerjack run --no-boost-coverage   # Disable coverage improvements
```

**Zuban LSP Server Management:**

```bash
python -m crackerjack run --start-zuban-lsp     # Start Zuban LSP server
python -m crackerjack run --stop-zuban-lsp      # Stop Zuban LSP server
python -m crackerjack run --restart-zuban-lsp   # Restart Zuban LSP server
python -m crackerjack run --no-zuban-lsp        # Disable automatic LSP startup
python -m crackerjack run --zuban-lsp-port 8677 # Custom LSP port
python -m crackerjack run --zuban-lsp-mode tcp  # Transport mode (tcp/stdio)
python -m crackerjack run --zuban-lsp-timeout 30 # LSP operation timeout
python -m crackerjack run --enable-lsp-hooks    # Enable LSP-optimized hooks
```

**Documentation Generation:**

```bash
python -m crackerjack run --generate-docs       # Generate comprehensive API docs
python -m crackerjack run --docs-format markdown # Documentation format (markdown/rst/html)
python -m crackerjack run --validate-docs       # Validate existing documentation
```

**Global Locking & Concurrency:**

```bash
python -m crackerjack run --disable-global-locking # Allow concurrent execution
python -m crackerjack run --global-lock-timeout 600 # Lock timeout in seconds
python -m crackerjack run --cleanup-stale-locks # Clean stale lock files (default)
python -m crackerjack run --no-cleanup-stale-locks # Don't clean stale locks
python -m crackerjack run --global-lock-dir ~/.crackerjack/locks # Custom lock directory
```

**Git & Version Control:**

```bash
python -m crackerjack run --no-git-tags         # Skip creating git tags
python -m crackerjack run --skip-version-check  # Skip version consistency verification
```

**Experimental Features:**

```bash
python -m crackerjack run --experimental-hooks  # Enable experimental pre-commit hooks
python -m crackerjack run --enable-pyrefly      # Enable pyrefly type checking (experimental)
python -m crackerjack run --enable-ty           # Enable ty type verification (experimental)
```

**Common Options:**

- `-i, --interactive`: Rich UI interface with better experience
- `-v, --verbose`: Detailed output for debugging
- `-c, --commit`: Auto-commit and push changes to Git
- `--skip-hooks`: Skip quality checks during development iteration
- `--strip-code`: Remove docstrings/comments for production
- `--dev`: Enable development mode for progress monitors
- `--fast`: Run only fast hooks (formatting and basic checks)
- `--comp`: Run only comprehensive hooks (type checking, security, complexity)
- `--quick`: Quick mode (3 iterations max, ideal for CI/CD)
- `--thorough`: Thorough mode (8 iterations max, for complex refactoring)
- `--debug`: Enable debug output with detailed information
- `--no-config-update`: Do not update configuration files
- `--update-precommit`: Update pre-commit hooks configuration

## Style Guide

**Code Standards:**

- Python 3.13+ with modern type hints (`|` unions, PEP 695)
- No docstrings (self-documenting code)
- Pathlib over os.path
- Protocol-based interfaces
- Cognitive complexity ≤15 per function
- UV for dependency management

## Publishing & Version Management

### Secure PyPI Authentication

**Keyring Storage (Most Secure):**

```bash
# Install keyring support
uv add keyring

# Store token securely
keyring set https://upload.pypi.org/legacy/ __token__
# Enter your PyPI token when prompted
```

**Environment Variable (Alternative):**

```bash
# For CI/CD or temporary use
export UV_PUBLISH_TOKEN=pypi-your-token-here

# ⚠️ Security Warning: Never commit this to git
```

**Environment File (Local Development):**

```bash
# Create .env file (must be in .gitignore)
echo "UV_PUBLISH_TOKEN=pypi-your-token-here" > .env
echo ".env" >> .gitignore
```

### Version Management

```bash
python -m crackerjack run --publish patch  # 1.0.0 -> 1.0.1
python -m crackerjack run --publish minor  # 1.0.0 -> 1.1.0
python -m crackerjack run --publish major  # 1.0.0 -> 2.0.0
```

### Security Considerations

- **Token Rotation**: Rotate PyPI tokens every 90 days
- **Scope Limitation**: Use project-scoped tokens when possible
- **Access Review**: Regularly audit who has publish access
- **Backup Tokens**: Keep backup tokens in secure location

## MCP Integration

**AI Agent Support:**
Crackerjack provides an MCP server for AI agent integration:

```bash
# Start MCP server
python -m crackerjack start
```

**MCP client configuration (stdio-based):**

```json
{
  "mcpServers": {
    "crackerjack": {
      "command": "uvx",
      "args": [
        "--from",
        "/path/to/crackerjack",
        "crackerjack",
        "start"
      ]
    }
  }
}
```

**Available tools:** `execute_crackerjack`, `get_job_progress`, `run_crackerjack_stage`, `analyze_errors`, `smart_error_analysis`, `get_next_action`, `session_management`

## Complementary Tools

### Session Buddy MCP Server

For enhanced AI-assisted development with conversation memory and context persistence, consider using the [session-buddy](https://github.com/lesleslie/session-buddy) server alongside Crackerjack:

## Session Buddy Integration

**Automatic for Git Projects:**

- Session management starts automatically
- No manual `/start` or `/end` needed
- Checkpoints auto-compact when necessary
- Works with `python -m crackerjack run`

**Benefits of Combined Usage:**

- **Persistent Learning**: Session Buddy remembers your error patterns and successful fixes
- **Context Preservation**: Maintains conversation context across Claude sessions
- **Quality Tracking**: Monitors your project's quality score evolution over time
- **Workflow Optimization**: Learns from your development patterns to suggest improvements
- **Shared Coordination**: The two servers share insights across the workflow
- **Automatic Lifecycle**: Automates the git-repository session lifecycle

**Quick Setup:**

```json
{
  "mcpServers": {
    "crackerjack": {
      "command": "python",
      "args": ["-m", "crackerjack", "start"]
    },
    "session-mgmt": {
      "command": "python",
      "args": ["-m", "session_mgmt_mcp.server"]
    }
  }
}
```

**Example Workflow:**

```bash
# Just start working - session auto-initializes!
python -m crackerjack run --ai-fix --run-tests

# Checkpoint periodically (auto-compacts if needed)
/checkpoint

# Quit any way - session auto-saves
/quit  # or Cmd+Q, or network disconnect
```

**How They Work Together:**

- **Crackerjack** handles code quality enforcement, testing, and release management
- **Session Buddy** maintains AI conversation context and learns from your patterns
- **Combined**: Creates a development environment that records what worked in earlier sessions

The integration is automatic - session-mgmt includes a comprehensive `crackerjack_integration.py` module that captures quality metrics, test results, and error patterns for learning across sessions.

## Troubleshooting

### Common Issues

#### Installation Problems

```bash
# UV not found
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# Python 3.13+ required
uv python install 3.13
uv python pin 3.13
```

#### Authentication Errors

```bash
# PyPI token issues
keyring get https://upload.pypi.org/legacy/ __token__  # Verify stored token
keyring set https://upload.pypi.org/legacy/ __token__  # Reset if needed

# Permission denied
chmod +x ~/.local/bin/uv
```

#### Hook Failures

```bash
# Pre-commit hooks failing
python -m crackerjack run --skip-hooks  # Skip hooks temporarily
pre-commit clean                     # Clear hook cache
pre-commit install --force          # Reinstall hooks

# Update hooks
python -m crackerjack run --update-precommit

# Type checking errors
python -m crackerjack run               # Run quality checks
```

#### MCP Server Issues

```bash
# Server won't start
python -m crackerjack start --verbose

# Server connection issues
# Check if server is running
python -m crackerjack status

# Test server health
python -m crackerjack health
```

#### Performance Issues

```bash
# Slow execution
python -m crackerjack run --test-workers 1    # Reduce parallelism
python -m crackerjack run --skip-hooks        # Skip time-consuming checks

# Memory issues
export UV_CACHE_DIR=/tmp/uv-cache         # Use different cache location
```

### Debug Mode

```bash
# Enable verbose output
python -m crackerjack run --verbose

# Check debug logs (in XDG cache directory)
ls ~/.cache/crackerjack/logs/debug/

# MCP debugging
python -m crackerjack start --verbose
```

### Getting Help

- **GitHub Issues**: [Report bugs](https://github.com/lesleslie/crackerjack/issues)
- **Command Help**: `python -m crackerjack run --help`
- **MCP Tools**: Use `get_next_action` tool for guidance

## Contributing

1. Fork and clone the repository
1. Run `uv sync --group dev` to install dependencies
1. Ensure `python -m crackerjack run` passes all checks
1. Submit pull request

**Requirements:** Python 3.13+, UV package manager, all quality checks must pass

## License

BSD 3-Clause License - see [LICENSE](LICENSE) file.

______________________________________________________________________

**Issues:** [GitHub Issues](https://github.com/lesleslie/crackerjack/issues)
**Repository:** [GitHub](https://github.com/lesleslie/crackerjack)

# Test
