Empathy Framework

Empathy Framework

AI-powered developer workflows with cost optimization and pattern learning.

Run code review, debugging, testing, and release workflows from your terminal or Claude Code. Smart tier routing saves 34-86% on LLM costs.

pip install empathy-framework[developer]

🎯 Transitioning to Claude-Native Architecture

Empathy Framework is evolving to focus exclusively on Anthropic/Claude to unlock features impossible with multi-provider abstraction:

• 📦 Prompt Caching: 90% cost reduction on repeated prompts
• 📖 Flexible Context: 200K via subscription for most tasks, up to 1M via API for large codebases
• 🧠 Extended Thinking: See Claude's internal reasoning process
• 🔧 Advanced Tool Use: Optimized for agentic workflows

Timeline:

• ✅ v4.8.0 (Jan 2026): Deprecation warnings for OpenAI/Google/Ollama providers
• ✅ v5.0.0 (Jan 26, 2026): Non-Anthropic providers removed (BREAKING - COMPLETE)
• ✅ v5.0.2 (Jan 28, 2026): Cost optimization suite with batch processing and caching monitoring

Migration Guide: docs/CLAUDE_NATIVE.md

What's New in v5.3.0

🎨 Dashboard Enhancements - Improved usability and clarity:

• Agent Display Names - Human-readable labels for agents in dashboard (e.g., "Code Analyzer" instead of UUID)
• Comprehensive Help Panel - 5-section accordion explaining dashboard features, use cases, and Redis setup
• UX Improvements - "Source Agent:" label clarity, "Redis Requires Enabling" status message
• Browser Cache Busting - Date-based versioning ensures updates appear immediately

📚 Documentation Improvements:

• Clarified flexible context strategy (200K subscription + 1M API routing)
• Added Redis requirement documentation for dashboard
• Root directory cleanup (8 archived files)

🧪 Test Infrastructure:

• Sequential test execution to fix import timing issues
• All agent tracking tests passing (19/19)

See Full Changelog

What's New in v5.1.0

🤖 Multi-Agent Orchestration - Full support for custom agents and Anthropic LLM agents:

• Agent Coordination Dashboard - Real-time monitoring with 6 coordination patterns:

  • Agent heartbeats and status tracking
  • Inter-agent coordination signals
  • Event streaming across agent workflows
  • Approval gates for human-in-the-loop
  • Quality feedback and performance metrics
  • Demo mode with test data generation

• Custom Agents - Build specialized agents for your workflow needs

• LLM Agents from Anthropic - Leverage Claude's advanced capabilities

• Dashboard accessible at http://localhost:8000 with python examples/dashboard_demo.py (Requires Redis)

🔐 Authentication Strategy System - Intelligent routing between Claude subscriptions and Anthropic API:

# Interactive setup
python -m empathy_os.models.auth_cli setup

# View current configuration
python -m empathy_os.models.auth_cli status

# Get recommendation for a file
python -m empathy_os.models.auth_cli recommend src/module.py

💰 Automatic Cost Optimization - Workflows choose the best auth method:

• Small/medium modules (<2000 LOC) → Claude subscription (free)
• Large modules (>2000 LOC) → Anthropic API (pay for what you need)
• 7 workflows integrated: document-gen, test-gen, code-review, bug-predict, security-audit, perf-audit, release-prep
• Auth mode tracking in all workflow outputs for telemetry

🧪 Comprehensive Testing - 7 new integration tests for auth strategy:

• All workflows tested with auth enabled/disabled
• API and subscription mode verification
• Cost tracking validation

📖 Documentation - 950+ lines across 3 guides:

• AUTH_STRATEGY_GUIDE.md - User guide for configuration
• AUTH_CLI_IMPLEMENTATION.md - CLI command reference
• AUTH_WORKFLOW_INTEGRATIONS.md - Integration patterns

See Full Changelog

What's New in v5.0.2

💰 50% Cost Savings with Batch API - Process non-urgent tasks asynchronously:

empathy batch submit batch_requests.json  # Submit batch job
empathy batch status msgbatch_abc123      # Check progress
empathy batch results msgbatch_abc123 output.json  # Download results

Perfect for: log analysis, report generation, bulk classification, test generation

📊 Precise Token Counting - >98% accurate cost tracking:

• Integrated Anthropic's count_tokens() API for billing-accurate measurements
• 3-tier fallback: API → tiktoken (local) → heuristic
• Cache-aware cost calculation (25% write markup, 90% read discount)

📈 Cache Performance Monitoring - Track your 20-30% caching savings:

empathy cache stats           # Show hit rates and cost savings
empathy cache stats --verbose # Detailed token metrics
empathy cache stats --format json  # Machine-readable output

🧭 Adaptive Routing Analytics - Intelligent tier recommendations:

empathy routing stats <workflow>    # Performance metrics
empathy routing check --all         # Tier upgrade recommendations
empathy routing models --provider anthropic  # Compare models

🔧 Dashboard Fixes - All 6 agent coordination patterns now operational:

• Agent heartbeats displaying correctly
• Event streaming functional
• Coordination signals working
• Approval gates operational

See Full Changelog | Batch API Guide | User API Docs

What's New in v4.9.0

⚡ 18x Faster Performance - Massive performance gains through Phase 2 optimizations:

• Redis Two-Tier Caching: 2x faster memory operations (37,000x for cached keys)
• Generator Expressions: 99.9% memory reduction across 27 optimizations
• Parallel Scanning: Multi-core processing enabled by default (2-4x faster)
• Incremental Scanning: Git diff-based updates (10x faster)

🧭 Natural Language Workflows - Use plain English instead of workflow names:

/workflows "find security vulnerabilities"  # → security-audit
/workflows "check code performance"         # → perf-audit
/workflows "predict bugs"                   # → bug-predict
/plan "review my code"                      # → code-review

📊 Real-World Performance:

• Combined workflow: 3.59s → 0.2s (18x faster)
• Full scan: 3,472 files in 0.98s (was 3.59s)
• Redis cached operations: 37ms → 0.001ms

🎯 Improved Navigation:

• Split /workflow into /workflows (automated analysis) and /plan (planning/review)
• Clearer hub organization with better categorization
• Natural language routing matches intent to workflow

See CHANGELOG.md | Performance Docs

What's New in v4.7.0

$0 Workflows via Skills - Multi-agent workflows run through Claude Code's Task tool instead of API calls. No additional cost with your Claude subscription.

Socratic Workflows - Interactive discovery through guided questions. Workflows ask what you need rather than requiring upfront configuration.

Security Hardened - Fixed critical vulnerabilities (path traversal, JWT, SSRF).

Hub-Based Commands - Organized workflows into intuitive command hubs.

Quick Start

1. Install

pip install empathy-framework[developer]

2. Configure

# Auto-detect API keys
python -m empathy_os.models.cli provider

# Or set explicitly
python -m empathy_os.models.cli provider --set anthropic

3. Use

In Claude Code:

/dev           # Developer tools (debug, commit, PR, review)
/testing       # Run tests, coverage, benchmarks
/workflows     # Automated analysis (security, bugs, perf)
/plan          # Planning, TDD, code review
/docs          # Documentation generation
/release       # Release preparation

# Natural language support:
/workflows "find security issues"
/plan "review my code"

# Direct tool access via MCP (v5.1.1+):
# Claude Code automatically discovers Empathy tools through the MCP server
# Just describe what you need in natural language:
"Run a security audit on src/"          → Invokes security_audit tool
"Generate tests for config.py"          → Invokes test_generation tool
"Check my auth configuration"           → Invokes auth_status tool
"Analyze performance bottlenecks"       → Invokes performance_audit tool

MCP Server Integration (v5.1.1+):

Empathy Framework now includes a Model Context Protocol (MCP) server that exposes all workflows as native Claude Code tools:

• 10 Tools Available: security_audit, bug_predict, code_review, test_generation, performance_audit, release_prep, auth_status, auth_recommend, telemetry_stats, dashboard_status
• Automatic Discovery: No manual configuration needed - Claude Code finds tools via .claude/mcp.json
• Natural Language Access: Describe your need and Claude invokes the appropriate tool
• Verification Hooks: Automatic validation of Python/JSON files and workflow outputs

To verify MCP integration:

# Check server is running
echo '{"method":"tools/list","params":{}}' | PYTHONPATH=./src python -m empathy_os.mcp.server

# Restart Claude Code to load the MCP server
# Tools will appear in Claude's tool list automatically

See .claude/MCP_TEST_RESULTS.md for full integration details.

CLI:

empathy workflow run security-audit --path ./src
empathy workflow run test-coverage --target 90
empathy telemetry show  # View cost savings

Python:

from empathy_os import EmpathyOS

async with EmpathyOS() as empathy:
    result = await empathy.level_2_guided(
        "Review this code for security issues"
    )
    print(result["response"])

Command Hubs

Workflows are organized into hubs for easy discovery:

Natural Language Support:

# Use plain English - intelligent routing matches your intent
/workflows "find security vulnerabilities"  # → security-audit
/workflows "check code performance"         # → perf-audit
/workflows "predict bugs"                   # → bug-predict
/plan "review my code"                      # → code-review
/plan "help me plan this feature"           # → planning

# Or use traditional workflow names


…