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. -brightgreen) Empathy Framework is evolving to focus exclusively on Anthropic/Claude to unlock features impossible with multi-provider abstraction: - 📦 Prompt Caching: 90% cost reduct
Add this skill
npx mdskills install Smart-AI-Memory/empathy-frameworkComprehensive AI workflow framework with cost optimization, multi-agent orchestration, and extensive tooling
1# Empathy Framework23**AI-powered developer workflows with cost optimization and pattern learning.**45Run code review, debugging, testing, and release workflows from your terminal or Claude Code. Smart tier routing saves 34-86% on LLM costs.67[](https://pypi.org/project/empathy-framework/)8[-brightgreen)](https://github.com/Smart-AI-Memory/empathy-framework/actions)9[](https://www.python.org)10[](LICENSE)11[](https://github.com/Smart-AI-Memory/empathy-framework/blob/main/CHANGELOG.md)1213```bash14pip install empathy-framework[developer]15```1617---1819## 🎯 Transitioning to Claude-Native Architecture2021**Empathy Framework is evolving to focus exclusively on Anthropic/Claude** to unlock features impossible with multi-provider abstraction:2223- **📦 Prompt Caching:** 90% cost reduction on repeated prompts24- **📖 Flexible Context:** 200K via subscription for most tasks, up to 1M via API for large codebases25- **🧠 Extended Thinking:** See Claude's internal reasoning process26- **🔧 Advanced Tool Use:** Optimized for agentic workflows2728**Timeline:**2930- ✅ **v4.8.0 (Jan 2026):** Deprecation warnings for OpenAI/Google/Ollama providers31- ✅ **v5.0.0 (Jan 26, 2026):** Non-Anthropic providers removed (BREAKING - COMPLETE)32- ✅ **v5.0.2 (Jan 28, 2026):** Cost optimization suite with batch processing and caching monitoring3334**Migration Guide:** [docs/CLAUDE_NATIVE.md](docs/CLAUDE_NATIVE.md)3536---3738## What's New in v5.3.03940**🎨 Dashboard Enhancements** - Improved usability and clarity:4142- **Agent Display Names** - Human-readable labels for agents in dashboard (e.g., "Code Analyzer" instead of UUID)43- **Comprehensive Help Panel** - 5-section accordion explaining dashboard features, use cases, and Redis setup44- **UX Improvements** - "Source Agent:" label clarity, "Redis Requires Enabling" status message45- **Browser Cache Busting** - Date-based versioning ensures updates appear immediately4647**📚 Documentation Improvements**:4849- Clarified flexible context strategy (200K subscription + 1M API routing)50- Added Redis requirement documentation for dashboard51- Root directory cleanup (8 archived files)5253**🧪 Test Infrastructure**:5455- Sequential test execution to fix import timing issues56- All agent tracking tests passing (19/19)5758[See Full Changelog](CHANGELOG.md#530---2026-01-31)5960---6162## What's New in v5.1.06364**🤖 Multi-Agent Orchestration** - Full support for custom agents and Anthropic LLM agents:6566- **Agent Coordination Dashboard** - Real-time monitoring with 6 coordination patterns:67 - Agent heartbeats and status tracking68 - Inter-agent coordination signals69 - Event streaming across agent workflows70 - Approval gates for human-in-the-loop71 - Quality feedback and performance metrics72 - Demo mode with test data generation7374- **Custom Agents** - Build specialized agents for your workflow needs75- **LLM Agents from Anthropic** - Leverage Claude's advanced capabilities76- Dashboard accessible at `http://localhost:8000` with `python examples/dashboard_demo.py` **(Requires Redis)**7778**🔐 Authentication Strategy System** - Intelligent routing between Claude subscriptions and Anthropic API:7980```bash81# Interactive setup82python -m empathy_os.models.auth_cli setup8384# View current configuration85python -m empathy_os.models.auth_cli status8687# Get recommendation for a file88python -m empathy_os.models.auth_cli recommend src/module.py89```9091**💰 Automatic Cost Optimization** - Workflows choose the best auth method:9293- Small/medium modules (<2000 LOC) → Claude subscription (free)94- Large modules (>2000 LOC) → Anthropic API (pay for what you need)95- 7 workflows integrated: document-gen, test-gen, code-review, bug-predict, security-audit, perf-audit, release-prep96- Auth mode tracking in all workflow outputs for telemetry9798**🧪 Comprehensive Testing** - 7 new integration tests for auth strategy:99100- All workflows tested with auth enabled/disabled101- API and subscription mode verification102- Cost tracking validation103104**📖 Documentation** - 950+ lines across 3 guides:105106- [AUTH_STRATEGY_GUIDE.md](docs/AUTH_STRATEGY_GUIDE.md) - User guide for configuration107- [AUTH_CLI_IMPLEMENTATION.md](docs/AUTH_CLI_IMPLEMENTATION.md) - CLI command reference108- [AUTH_WORKFLOW_INTEGRATIONS.md](docs/AUTH_WORKFLOW_INTEGRATIONS.md) - Integration patterns109110[See Full Changelog](CHANGELOG.md#510---2026-01-29)111112---113114## What's New in v5.0.2115116**💰 50% Cost Savings with Batch API** - Process non-urgent tasks asynchronously:117118```bash119empathy batch submit batch_requests.json # Submit batch job120empathy batch status msgbatch_abc123 # Check progress121empathy batch results msgbatch_abc123 output.json # Download results122```123124Perfect for: log analysis, report generation, bulk classification, test generation125126**📊 Precise Token Counting** - >98% accurate cost tracking:127128- Integrated Anthropic's `count_tokens()` API for billing-accurate measurements129- 3-tier fallback: API → tiktoken (local) → heuristic130- Cache-aware cost calculation (25% write markup, 90% read discount)131132**📈 Cache Performance Monitoring** - Track your 20-30% caching savings:133134```bash135empathy cache stats # Show hit rates and cost savings136empathy cache stats --verbose # Detailed token metrics137empathy cache stats --format json # Machine-readable output138```139140**🧭 Adaptive Routing Analytics** - Intelligent tier recommendations:141142```bash143empathy routing stats <workflow> # Performance metrics144empathy routing check --all # Tier upgrade recommendations145empathy routing models --provider anthropic # Compare models146```147148**🔧 Dashboard Fixes** - All 6 agent coordination patterns now operational:149- Agent heartbeats displaying correctly150- Event streaming functional151- Coordination signals working152- Approval gates operational153154[See Full Changelog](CHANGELOG.md#502---2026-01-28) | [Batch API Guide](docs/BATCH_API_GUIDE.md) | [User API Docs](docs/USER_API_DOCUMENTATION.md)155156---157158## What's New in v4.9.0159160**⚡ 18x Faster Performance** - Massive performance gains through Phase 2 optimizations:161162- **Redis Two-Tier Caching:** 2x faster memory operations (37,000x for cached keys)163- **Generator Expressions:** 99.9% memory reduction across 27 optimizations164- **Parallel Scanning:** Multi-core processing enabled by default (2-4x faster)165- **Incremental Scanning:** Git diff-based updates (10x faster)166167**🧭 Natural Language Workflows** - Use plain English instead of workflow names:168169```bash170/workflows "find security vulnerabilities" # → security-audit171/workflows "check code performance" # → perf-audit172/workflows "predict bugs" # → bug-predict173/plan "review my code" # → code-review174```175176**📊 Real-World Performance:**177178- Combined workflow: 3.59s → 0.2s (**18x faster**)179- Full scan: 3,472 files in 0.98s (was 3.59s)180- Redis cached operations: 37ms → 0.001ms181182**🎯 Improved Navigation:**183184- Split `/workflow` into `/workflows` (automated analysis) and `/plan` (planning/review)185- Clearer hub organization with better categorization186- Natural language routing matches intent to workflow187188[See CHANGELOG.md](CHANGELOG.md) | [Performance Docs](docs/REDIS_OPTIMIZATION_SUMMARY.md)189190---191192## What's New in v4.7.0193194**$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.195196**Socratic Workflows** - Interactive discovery through guided questions. Workflows ask what you need rather than requiring upfront configuration.197198**Security Hardened** - Fixed critical vulnerabilities (path traversal, JWT, SSRF).199200**Hub-Based Commands** - Organized workflows into intuitive command hubs.201202---203204## Quick Start205206### 1. Install207208```bash209pip install empathy-framework[developer]210```211212### 2. Configure213214```bash215# Auto-detect API keys216python -m empathy_os.models.cli provider217218# Or set explicitly219python -m empathy_os.models.cli provider --set anthropic220```221222### 3. Use223224**In Claude Code:**225226```bash227/dev # Developer tools (debug, commit, PR, review)228/testing # Run tests, coverage, benchmarks229/workflows # Automated analysis (security, bugs, perf)230/plan # Planning, TDD, code review231/docs # Documentation generation232/release # Release preparation233234# Natural language support:235/workflows "find security issues"236/plan "review my code"237238# Direct tool access via MCP (v5.1.1+):239# Claude Code automatically discovers Empathy tools through the MCP server240# Just describe what you need in natural language:241"Run a security audit on src/" → Invokes security_audit tool242"Generate tests for config.py" → Invokes test_generation tool243"Check my auth configuration" → Invokes auth_status tool244"Analyze performance bottlenecks" → Invokes performance_audit tool245```246247**MCP Server Integration (v5.1.1+):**248249Empathy Framework now includes a Model Context Protocol (MCP) server that exposes all workflows as native Claude Code tools:250251- **10 Tools Available:** security_audit, bug_predict, code_review, test_generation, performance_audit, release_prep, auth_status, auth_recommend, telemetry_stats, dashboard_status252- **Automatic Discovery:** No manual configuration needed - Claude Code finds tools via `.claude/mcp.json`253- **Natural Language Access:** Describe your need and Claude invokes the appropriate tool254- **Verification Hooks:** Automatic validation of Python/JSON files and workflow outputs255256To verify MCP integration:257258```bash259# Check server is running260echo '{"method":"tools/list","params":{}}' | PYTHONPATH=./src python -m empathy_os.mcp.server261262# Restart Claude Code to load the MCP server263# Tools will appear in Claude's tool list automatically264```265266See [.claude/MCP_TEST_RESULTS.md](.claude/MCP_TEST_RESULTS.md) for full integration details.267268**CLI:**269270```bash271empathy workflow run security-audit --path ./src272empathy workflow run test-coverage --target 90273empathy telemetry show # View cost savings274```275276**Python:**277278```python279from empathy_os import EmpathyOS280281async with EmpathyOS() as empathy:282 result = await empathy.level_2_guided(283 "Review this code for security issues"284 )285 print(result["response"])286```287288---289290## Command Hubs291292Workflows are organized into hubs for easy discovery:293294| Hub | Command | Description |295| ----------------- | ------------- | -------------------------------------------- |296| **Developer** | `/dev` | Debug, commit, PR, code review, quality |297| **Testing** | `/testing` | Run tests, coverage analysis, benchmarks |298| **Documentation** | `/docs` | Generate and manage documentation |299| **Release** | `/release` | Release prep, security scan, publishing |300| **Workflows** | `/workflows` | Automated analysis (security, bugs, perf) |301| **Plan** | `/plan` | Planning, TDD, code review, refactoring |302| **Utilities** | `/utilities` | Project init, dependencies, profiling |303| **Learning** | `/learning` | Pattern learning and session evaluation |304| **Context** | `/context` | State management and memory |305| **Agent** | `/agent` | Create and manage custom agents |306307**Natural Language Support:**308309```bash310# Use plain English - intelligent routing matches your intent311/workflows "find security vulnerabilities" # → security-audit312/workflows "check code performance" # → perf-audit313/workflows "predict bugs" # → bug-predict314/plan "review my code" # → code-review315/plan "help me plan this feature" # → planning316317# Or use traditional workflow names318/workflows security-audit319/plan code-review320```321322**Interactive menus:**323324```bash325/dev # Show interactive menu326/dev "debug auth error" # Jump directly to debugging327/testing "run coverage" # Run coverage analysis328/release # Start release preparation329```330331---332333## Socratic Method334335Workflows guide you through discovery instead of requiring upfront configuration:336337```text338You: /dev339340Claude: What development task do you need?341 1. Debug issue342 2. Create commit343 3. PR workflow344 4. Quality check345346You: 1347348Claude: What error or unexpected behavior are you seeing?349```350351**How it works:**3523531. **Discovery** - Workflow asks targeted questions to understand your needs3542. **Context gathering** - Collects relevant code, errors, and constraints3553. **Dynamic agent creation** - Assembles the right team based on your answers3564. **Execution** - Runs with appropriate tier selection357358**Create custom agents with Socratic guidance:**359360```bash361/agent create # Guided agent creation362/agent team # Build multi-agent teams interactively363```364365---366367## Cost Optimization368369### Skills = $0 (Claude Code)370371When using Claude Code, workflows run as skills through the Task tool - **no API costs**:372373```bash374/dev # $0 - uses your Claude subscription375/testing # $0376/release # $0377/agent create # $0378```379380### API Mode (CI/CD, Automation)381382For programmatic use, smart tier routing saves 34-86%:383384| Tier | Model | Use Case | Cost |385| ------- | ------------------- | --------------------------- | ----------- |386| CHEAP | Haiku / GPT-4o-mini | Formatting, simple tasks | ~$0.005 |387| CAPABLE | Sonnet / GPT-4o | Bug fixes, code review | ~$0.08 |388| PREMIUM | Opus / o1 | Architecture, complex design | ~$0.45 |389390```bash391# Track API usage and savings392empathy telemetry savings --days 30393```394395---396397## Key Features398399### Multi-Agent Workflows400401```bash402# 4 parallel agents check release readiness403empathy orchestrate release-prep404405# Sequential coverage improvement406empathy orchestrate test-coverage --target 90407```408409### Response Caching410411Up to 57% cache hit rate on similar prompts. Zero config needed.412413```python414from empathy_os.workflows import SecurityAuditWorkflow415416workflow = SecurityAuditWorkflow(enable_cache=True)417result = await workflow.execute(target_path="./src")418print(f"Cache hit rate: {result.cost_report.cache_hit_rate:.1f}%")419```420421### Pattern Learning422423Workflows learn from outcomes and improve over time:424425```python426from empathy_os.orchestration.config_store import ConfigurationStore427428store = ConfigurationStore()429best = store.get_best_for_task("release_prep")430print(f"Success rate: {best.success_rate:.1%}")431```432433### Multi-Provider Support434435```python436from empathy_llm_toolkit.providers import (437 AnthropicProvider, # Claude438 OpenAIProvider, # GPT-4439 GeminiProvider, # Gemini440 LocalProvider, # Ollama, LM Studio441)442```443444---445446## CLI Reference447448```bash449# Provider configuration450python -m empathy_os.models.cli provider451python -m empathy_os.models.cli provider --set hybrid452453# Workflows454empathy workflow list455empathy workflow run <workflow-name>456457# Cost tracking458empathy telemetry show459empathy telemetry savings --days 30460empathy telemetry export --format csv461462# Orchestration463empathy orchestrate release-prep464empathy orchestrate test-coverage --target 90465466# Meta-workflows467empathy meta-workflow list468empathy meta-workflow run release-prep --real469```470471---472473## Install Options474475```bash476# Individual developers (recommended)477pip install empathy-framework[developer]478479# All LLM providers480pip install empathy-framework[llm]481482# With caching (semantic similarity)483pip install empathy-framework[cache]484485# Enterprise (auth, rate limiting)486pip install empathy-framework[enterprise]487488# Healthcare (HIPAA compliance)489pip install empathy-framework[healthcare]490491# Development492git clone https://github.com/Smart-AI-Memory/empathy-framework.git493cd empathy-framework && pip install -e .[dev]494```495496---497498## Environment Setup499500```bash501# At least one provider required502export ANTHROPIC_API_KEY="sk-ant-..."503export OPENAI_API_KEY="sk-..."504export GOOGLE_API_KEY="..."505506# Optional (but required for Agent Dashboard): Redis for memory507export REDIS_URL="redis://localhost:6379"508```509510---511512## VSCode Extension513514Install the Empathy VSCode extension for:515516- **Dashboard** - Health score, costs, patterns517- **One-Click Workflows** - Run from command palette518- **Memory Panel** - Manage Redis and patterns519- **Cost Tracking** - Real-time savings display520521---522523## Documentation524525- [Quick Start Guide](docs/quickstart.md)526- [CLI Reference](docs/cli-reference.md)527- [Testing Guide](docs/testing-guide.md)528- [Keyboard Shortcuts](docs/keyboard-shortcuts.md)529- [Full Documentation](https://smartaimemory.com/framework-docs/)530531---532533## Security534535- Path traversal protection on all file operations536- JWT authentication with rate limiting537- PII scrubbing in telemetry538- HIPAA/GDPR compliance options539- **Automated security scanning** with 82% accuracy (Phase 3 AST-based detection)540541See [SECURITY.md](SECURITY.md) for vulnerability reporting.542543### Security Scanning544545**Automated security scanning in CI/CD** - 82% accuracy, blocks critical issues:546547```bash548# Run security audit locally549empathy workflow run security-audit550551# Scan specific directory552empathy workflow run security-audit --input '{"path":"./src"}'553```554555**Documentation:**556557- **[Developer Workflow Guide](docs/DEVELOPER_SECURITY_WORKFLOW.md)** - Quick reference for handling security findings (all developers)558- **[CI/CD Integration Guide](docs/CI_SECURITY_SCANNING.md)** - Complete setup and troubleshooting (DevOps, developers)559- **[Scanner Architecture](docs/SECURITY_SCANNER_ARCHITECTURE.md)** - Technical implementation details (engineers, architects)560- **[Remediation Process](docs/SECURITY_REMEDIATION_PROCESS.md)** - 3-phase methodology for improving scanners (security teams, leadership)561- **[API Reference](docs/api-reference/security-scanner.md)** - Complete API documentation (developers extending scanner)562563**Key achievements:**564565- 82.3% reduction in false positives (350 → 62 findings)566- 16x improvement in scanner accuracy567- <15 minute average fix time for critical issues568- Zero critical vulnerabilities in production code569570---571572## Contributing573574See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.575576---577578## License579580**Apache License 2.0** - Free and open source for everyone. Use it, modify it, build commercial products with it. [Details →](LICENSE)581582---583584## Acknowledgements585586This project stands on the shoulders of giants. We are deeply grateful to the open source community and all the amazing projects that make this framework possible.587588**[View Full Acknowledgements →](ACKNOWLEDGEMENTS.md)**589590Special thanks to:591592- **[Anthropic](https://www.anthropic.com/)** - For Claude AI and the Model Context Protocol593- **[LangChain](https://github.com/langchain-ai/langchain)** - Agent framework powering our meta-orchestration594- **[FastAPI](https://github.com/tiangolo/fastapi)** - Modern Python web framework595- **[pytest](https://github.com/pytest-dev/pytest)** - Testing framework making quality assurance effortless596597And to all 50+ open source projects we depend on. [See the complete list →](ACKNOWLEDGEMENTS.md)598599Want to contribute? See [CONTRIBUTORS.md](CONTRIBUTORS.md)600601---602603**Built by [Smart AI Memory](https://smartaimemory.com)** · [Docs](https://smartaimemory.com/framework-docs/) · [Examples](examples/) · [Issues](https://github.com/Smart-AI-Memory/empathy-framework/issues)604
Full transparency — inspect the skill content before installing.