crackerjack 0.54.12

Crackerjack Python project management tool

Crackerjack

Quick Links

• Overview
• Installation
• Quick Start
• Core Workflow
• Quality Hook Modes
• 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:

# 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:

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	✅ Viarepo: local hooks	✅ 6 native tools incrackerjack/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	✅ Viapre-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 (singlepython -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:

# 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
• Quick Start
• AI Auto-Fix Features
• Skills Tracking Integration
• Core Workflow
• Core Features
• Legacy Architecture & Performance
• Adapters
• MCP Server Configuration
• Quality Hook Modes
• Command Reference
• Publishing & Version Management
• Troubleshooting

Installation

Prerequisites

• Python 3.13+
• UV package manager

Install UV

# 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

# 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

# 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

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
2. Analyze Failures: AI parses error messages and identifies likely root causes
3. AI Fixes: AI reads source code and makes targeted modifications
4. Repeat: Continue until checks pass or the iteration limit is reached (up to 8 iterations)
5. 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

# 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):

# ✅ 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

   export ANTHROPIC_API_KEY=sk-ant-...
   

2. Configuration file: settings/adapters.yml

   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:

# 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:

# 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) • Simple setup • Low latency	• Tight coupling • Requires session-buddy in Python path	• Local development • Single-machine setups
mcp	• Loose coupling • Remote deployment • Easy testing	• Higher latency • More complex	• Distributed systems • Microservices • Multi-project setups
auto (default)	• Tries MCP first • Automatic fallback • Best of both	• Slightly slower initial connection	• Most scenarios (recommended)

Usage Patterns

1. Automatic Tracking (Default)

All agent invocations are automatically tracked via AgentOrchestrator:

# 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

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

# 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:

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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
2. Code Cleaning Stage (between fast and comprehensive): AI-assisted cleanup before the comprehensive hook run
3. 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 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, 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

# 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

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 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	UsesAgentContext pattern (predates legacy)

Key Architectural Patterns

# ✅ 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):

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

New Approach (legacy):

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):

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

After (1 settings file, ~300 LOC):

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:

# 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:

# 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

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
2. Testability: Easy mocking with depends.get()
3. Maintainability: Clear separation between adapters and orchestration
4. Observability: Structured logging with context fields
5. Security: Input validation, timeout protection, origin validation
6. 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

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:

# 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:

# 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:

# 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:

# 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:

# 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

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

Quick index: 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):

   uv sync --group dev
   

2. Start the MCP server:

   # Start MCP server
   python -m crackerjack start
   

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

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

   For installed crackerjack (from PyPI):

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

   For local development version:

   {
     "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:

# 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:

{
  "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

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

/crackerjack:init: Initialize or update project configuration

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

Quality Hook Modes

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)

# 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

# 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	Seedocs/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 - AI assistant guidelines and developer commands

---

Command Reference

Core Workflow Commands:

# 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:

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:

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):

# 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:

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:

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:

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:

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:

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:

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

Experimental Features:

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):

# 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):

# 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):

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

Version Management

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:

# Start MCP server
python -m crackerjack start

MCP client configuration (stdio-based):

{
  "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 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:

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

Example Workflow:

# 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

# 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

# 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

# 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

# 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

# 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

# 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
• Command Help: python -m crackerjack run --help
• MCP Tools: Use get_next_action tool for guidance

Contributing

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

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

License

BSD 3-Clause License - see LICENSE file.

---

Issues: GitHub Issues Repository: GitHub

Test