session-buddy

Session Buddy

!Code style: crackerjack !Runtime: oneiric !Framework: FastMCP !uv !Python: 3.13+

A session management MCP server for Claude Code.

A dedicated MCP server that manages session lifecycle, searchable memory, and cross-project intelligence for Claude Code sessions.

Quick Links

• What Makes Session Buddy Unique?
• Features
• Automatic Session Management
• Integration with Crackerjack
• Development

Quality & CI

Crackerjack is the standard quality-control and CI/CD gate for Session Buddy. Use the same Crackerjack workflow locally that the project expects in CI.

What Makes Session Buddy Unique?

Session Buddy focuses on three things that set it apart from a simple session log:

Automatic Knowledge Capture

Session Buddy can extract structured insights from conversation patterns and make them searchable in later sessions. That reduces manual note-taking and turns normal development work into reusable project memory.

Cross-Project Intelligence

Session Buddy can surface relevant knowledge across related repos, services, or packages, which is especially useful for monorepos, microservices, and tightly coupled project families.

Privacy-First Architecture

• Local processing by default
• Local embedding support
• No required external API dependency for core workflows
• Fast search and retrieval oriented toward interactive use

---

Features

Advanced Analytics & Integration

Session Buddy extends core session management with real-time monitoring, analytics, and cross-session learning.

Real-Time Monitoring

• WebSocket Server - Live dashboard streaming at 1-second intervals

  • Top 10 most active skills displayed in real-time
  • Performance anomaly detection with Z-score analysis
  • Client subscriptions (all skills or specific skill monitoring)

• Prometheus Metrics - Monitoring export

  • 5 metric types: Counters, Histograms, Gauges
  • HTTP endpoint on port 9090 for scraping
  • Thread-safe updates for concurrent access

Advanced Analytics

• Predictive Models - ML-based skill success prediction

  • RandomForest classifier with 7 features
  • 30-day historical training window
  • Feature importance analysis

• A/B Testing Framework - Experiment with recommendation strategies

  • Deterministic user assignment (SHA-256 hashing)
  • Statistical significance testing (t-test, p < 0.05)
  • Automated winner determination

• Time-Series Analysis - Trend detection and forecasting

  • Linear regression trend detection
  • Hourly aggregation for dashboards
  • Anomaly detection using Z-scores

Cross-Session Learning

• Collaborative Filtering - Learn from similar users

  • Jaccard similarity for user matching
  • Personalized recommendations
  • SHA-256 privacy hashing for user IDs

• Community Baselines - Global skill effectiveness

  • Cross-user aggregation
  • Percentile rankings
  • User vs global comparisons

Tool Integration

• Crackerjack Integration - Quality gate tracking

  • Phase mapping to workflow stages
  • Automatic failure recommendations
  • ASCII workflow visualizations

• IDE Plugin Protocol - Context-aware recommendations

  • Code pattern detection (tests, imports, async)
  • Language-specific skill patterns
  • Keyboard shortcut management

• CI/CD Tracking - Pipeline analytics

  • Stage-by-stage monitoring
  • Bottleneck identification (< 80% success)
  • JSON export for dashboards

Skills Taxonomy

• Categories - Organized skill domains

  • Code Quality, Testing, Documentation, Deployment, etc.
  • 6 predefined categories
  • Multi-modal skill types (code → diagnostics, testing → test_results)

• Dependencies - Co-occurrence patterns

  • Lift score calculation
  • Relationship mapping
  • Workflow-aware recommendations

Performance:

• Real-time metrics: < 100ms
• Anomaly detection: < 200ms
• Collaborative filtering: < 200ms
• MCP tools: < 50ms

Core Session Management

• Session Initialization: Setup with UV dependency management, project analysis, and automation tools
• Quality Checkpoints: Mid-session quality monitoring with workflow analysis and optimization recommendations
• Session Cleanup: Cleanup with learning capture and handoff file creation
• Status Monitoring: Real-time session status and project context analysis
• Auto-Generated Shortcuts: Automatically creates /start, /checkpoint, and /end Claude Code slash commands

Intelligence Features

Session Buddy includes local knowledge-capture and sharing features that help work carry across sessions and repos:

Automatic Insights Capture & Injection

What It Does: