claude-force 1.3.1

Multi-Agent Orchestration System for Claude

Claude Force

Production-ready multi-agent orchestration system for Claude AI with governance, skills, and marketplace integration.

Overview

Claude Force is a comprehensive orchestration platform that enables building sophisticated AI workflows with specialized agents, automated governance, and cost optimization.

Key Features

• 19 Specialized Agents - Frontend, Backend, Database, DevOps, QA, Security, AI/ML, and more
• Marketplace Integration - Full compatibility with wshobson/agents ecosystem
• Cost Optimization - 40-60% savings via hybrid model orchestration (Haiku/Sonnet/Opus)
• Performance - 30-50% token reduction through progressive skills loading
• 6-Layer Governance - Quality gates, validation, and compliance enforcement
• 11 Skills - DOCX, XLSX, PDF, testing, code review, API design, Docker, Git
• 10 Workflows - Pre-built workflows for common development scenarios
• 9 Templates - Production-ready project templates
• 100% Test Coverage - 331 tests, all passing

🆕 Existing Project Support (v1.2.0)

Seamlessly integrate claude-force with your existing projects:

• 🔍 Review Command (/review) - Analyze existing projects for claude-force compatibility

  • Technology stack detection (12 languages, 9 frameworks, 5 databases)
  • Agent recommendations based on project analysis
  • Multiple output formats (markdown, JSON)

• 🔧 Restructure Command (/restructure) - Validate and fix .claude folder structure

  • Comprehensive validation rules
  • Automatic fix generation
  • Interactive and auto-approve modes

• 📦 Pick-Agent Command (/pick-agent) - Copy agent packs between projects

  • Browse and copy multiple agents
  • Automatic config updates
  • Validates agent definitions and contracts

See EXISTING_PROJECT_SUPPORT.md for full details.

Quick Start

Installation

# Install from PyPI
pip install claude-force

# Set API key
export ANTHROPIC_API_KEY='your-api-key-here'

# Verify
claude-force --help

See INSTALLATION.md for detailed setup.

First Steps

# List available agents
claude-force list agents

# Run an agent
claude-force run agent code-reviewer --task "Review authentication logic"

# Execute a workflow
claude-force run workflow full-stack-feature --task "Build user dashboard"

# Initialize new project
claude-force init my-project --interactive

See QUICK_START.md for the 5-minute getting started guide.

Interactive Shell 🎯

Run commands without typing claude-force each time:

# Start the shell
claude-force shell

# Now use commands directly with /
claude-force> /list agents
claude-force> /run agent code-reviewer --task "Review this code"
claude-force> /help

Features:

• ✅ Tab completion for commands, agents, and workflows
• ✅ Command history with arrow keys (↑/↓)
• ✅ Color-coded output - Green for success, red for errors
• ✅ Progress indicators for long-running commands
• ✅ Fuzzy suggestions - "Did you mean...?" for typos
• ✅ Smart aliases - /q for quit, /h for help, /ls for list
• ✅ Elapsed time display for slow commands
• ✅ Secure history - Command history saved with proper permissions

Quick Reference:

# Built-in commands
/help              # Show help
/quit, /q          # Exit (or Ctrl+D)
/clear, /cls       # Clear screen
/history           # Show recent commands
/reload            # Refresh agent lists
/version           # Show version

# Aliases save typing
/ls agents         # Same as /list agents
/h                 # Same as /help
/?                 # Same as /help

# Tab completion
/list <TAB>        # Shows: agents, workflows
/run agent <TAB>   # Shows all available agents
/info code-<TAB>   # Completes to code-reviewer

# Keyboard shortcuts
Tab                # Auto-complete
↑/↓                # Navigate history
Ctrl+C             # Cancel input
Ctrl+D             # Exit shell

Error Recovery: The shell provides helpful suggestions for common errors:

# Typo? Get suggestions
claude-force> /lst agents
✗ Unknown command. Try '/help' for available commands.

💡 Did you mean:
   • list agents
   • list workflows

# Missing API key? Get exact fix
✗ Error: API key not found

💡 Recovery suggestions:
   • Set your API key: export ANTHROPIC_API_KEY='your-key-here'
   • Or run: /setup to configure interactively

Core Concepts

Agents

Specialized AI agents with defined roles, skills, and contracts:

# List all agents with their capabilities
claude-force list agents

# Get detailed agent info
claude-force info security-specialist

# Run specific agent
claude-force run agent backend-architect --task "Design REST API"

Available Agents:

• Architecture: frontend-architect, backend-architect, database-architect, devops-architect
• Development: frontend-developer, python-expert, ui-components-expert
• Quality: code-reviewer, qc-automation-expert, security-specialist
• Support: bug-investigator, document-writer-expert, api-documenter
• Specialized: ai-engineer, data-engineer, prompt-engineer, deployment-integration-expert, google-cloud-expert, claude-code-expert

Workflows

Multi-agent workflows for complex tasks:

# Execute pre-built workflow
claude-force run workflow full-stack-feature --task "User authentication"

Available Workflows:

• full-stack-feature - Complete feature (8 agents: architecture → development → QA → deployment)
• frontend-feature - Frontend-only (5 agents)
• backend-api - Backend API (4 agents)
• infrastructure-setup - DevOps setup (3 agents)
• bug-investigation - Debug and fix (3 agents)
• documentation-suite - Full documentation (3 agents)
• ai-ml-development - AI/ML pipeline (4 agents)
• data-pipeline-development - Data engineering (3 agents)
• llm-integration - LLM integration (4 agents)
• claude-code-system - Meta workflow (5 agents)

Python API

from claude_force import AgentOrchestrator, HybridOrchestrator

# Standard orchestrator
orchestrator = AgentOrchestrator()
result = orchestrator.run_agent(
    agent_name='code-reviewer',
    task='Review the authentication logic'
)

# Hybrid orchestrator (cost optimization)
hybrid = HybridOrchestrator(auto_select_model=True)
result = hybrid.run_agent(
    agent_name='document-writer-expert',
    task='Generate API documentation'
)  # Auto-selects Haiku for 60-80% cost savings

# Run workflow
results = orchestrator.run_workflow(
    workflow_name='full-stack-feature',
    task='Build user profile page'
)

# Performance tracking
summary = orchestrator.get_performance_summary()
print(f"Total cost: ${summary['total_cost']:.4f}")
print(f"Avg time: {summary['avg_execution_time_ms']:.0f}ms")

See examples/python/ for more examples.

Advanced Features

Hybrid Model Orchestration

Automatically select optimal model (Haiku/Sonnet/Opus) based on task complexity:

# Auto-select best model
claude-force run agent document-writer-expert \
  --task "Generate docs" \
  --auto-select-model
# → Uses Haiku (60-80% savings)

# Force specific model
claude-force run agent frontend-architect \
  --task "Design architecture" \
  --model sonnet

Model Selection:

• Haiku - Documentation, simple code review, formatting (60-80% savings)
• Sonnet - Architecture, complex development, analysis (balanced)
• Opus - Critical security, complex debugging (highest quality)

Progressive Skills Loading

Load only required skills to reduce token usage:

from claude_force import ProgressiveSkillsLoader

loader = ProgressiveSkillsLoader()
savings = loader.calculate_savings(
    task="Review Python code",
    loaded_skills=["code-review"],
    total_skills=11
)
print(f"Token reduction: {savings['reduction_percentage']}%")
# → 72.7% reduction

Marketplace Integration

# Search marketplace
claude-force marketplace search "kubernetes"

# Install plugin
claude-force marketplace install wshobson-devops-toolkit

# Recommend agents for task
claude-force recommend --task "Review auth code for SQL injection"
# → security-specialist: 95.2% confidence
# → code-reviewer: 78.4% confidence

Performance Analytics

# View performance metrics
claude-force analytics summary

# Export metrics
claude-force analytics export --format json --output metrics.json

# View cost breakdown
claude-force analytics cost-breakdown --agent code-reviewer

Project Structure

Initialized Project

my-project/
├── .claude/
│   ├── claude.json          # Configuration
│   ├── task.md              # Current task
│   ├── work.md              # Agent output
│   ├── scorecard.md         # Quality metrics
│   ├── agents/              # Agent definitions
│   ├── contracts/           # Agent contracts
│   ├── hooks/               # Governance hooks
│   ├── skills/              # Custom skills
│   ├── workflows/           # Custom workflows
│   ├── tasks/               # Task history
│   └── metrics/             # Performance data
└── ...

Templates

Initialize projects with pre-configured templates:

claude-force init my-project --template llm-app

Smart Integration with Existing Projects:

Claude Force can seamlessly integrate with existing .claude directories (e.g., from Claude Code):

# Integrate with existing Claude Code project
cd my-existing-project  # Has .claude/ directory but no claude.json
claude-force init --description "My existing project"
# ✓ Preserves existing files (commands/, hooks/, task.md, etc.)
# ✓ Adds claude-force configuration (claude.json, agents/, contracts/)
# ✓ Shows what was created vs. preserved

If you already have claude.json, use --force to reinitialize:

claude-force init --force --description "Reinitialize project"

Available Templates:

• fullstack-web - Full-stack (React, FastAPI, PostgreSQL)
• llm-app - LLM application (RAG, chatbots)
• ml-project - Machine learning
• data-pipeline - ETL pipeline
• api-service - REST API
• frontend-spa - SPA (React/Vue)
• mobile-app - Mobile (React Native/Flutter)
• infrastructure - DevOps (Docker, K8s)
• claude-code-system - Multi-agent system

Documentation

Quick Links

• QUICK_START.md - 5-minute getting started
• INSTALLATION.md - Installation guide
• ARCHITECTURE.md - System architecture
• PROJECT_OVERVIEW.md - Project overview
• FAQ.md - Frequently asked questions
• TROUBLESHOOTING.md - Common issues
• CONTRIBUTING.md - Contribution guidelines
• CHANGELOG.md - Version history

Comprehensive Documentation

• Documentation Index - Complete documentation map
• Performance Guide - Performance optimization
• API Reference - API documentation
• Examples - Code examples and templates
• Guides - Feature guides
• Architecture - Technical details
• Reviews - Code reviews and audits

Use Cases

Code Review

claude-force run agent code-reviewer \
  --task "Review src/auth.py for security issues"

Architecture Design

claude-force run agent backend-architect \
  --task "Design microservices architecture for e-commerce platform"

Bug Investigation

claude-force run workflow bug-investigation \
  --task "Users can't login after password reset"

Documentation

claude-force run agent document-writer-expert \
  --task "Create API documentation" \
  --skill docx

Full Feature Development

claude-force run workflow full-stack-feature \
  --task "Build user profile management with avatar upload"

REST API Server

Run as a service:

# Start server
claude-force serve --port 8000

# Or use uvicorn
cd examples/api-server
uvicorn main:app --reload

from api_client import ClaudeForceClient

client = ClaudeForceClient(base_url="http://localhost:8000")

# Run agent
result = client.run_agent_sync(
    agent_name="code-reviewer",
    task="Review this code"
)

# Async execution
task_id = client.run_agent_async(agent_name="bug-investigator", task="...")
result = client.wait_for_task(task_id, timeout=60.0)

See examples/api-server/ for details.

CI/CD Integration

GitHub Actions

# .github/workflows/code-review.yml
name: Automated Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Code Review
        run: |
          pip install claude-force
          claude-force run agent code-reviewer \
            --task "Review changes in this PR" \
            --output review.md
      - name: Comment PR
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });

See examples/github-actions/ for more examples.

Performance & Costs

Token Optimization

• Progressive Skills Loading: 30-50% token reduction
• Smart Context Management: Only load relevant context
• Efficient Prompting: Optimized agent prompts

Cost Savings

• Hybrid Orchestration: 40-60% cost reduction
• Model Selection: Right model for each task
• Batch Processing: Efficient multi-task execution

Benchmarks

• Simple tasks (health endpoint): 1.2s, $0.0024
• Medium tasks (auth feature): 5.8s, $0.0312
• Complex tasks (full architecture): 12.4s, $0.0856

See benchmarks/ for detailed metrics.

Statistics

• Agents: 19 specialized agents
• Contracts: 19 formal contracts
• Skills: 11 integrated skills
• Workflows: 10 pre-built workflows
• Templates: 9 production templates
• Tests: 331 (100% passing)
• CLI Commands: 35+
• Code: ~30,000 lines (20K production + 8K tests + 2K docs)

Troubleshooting

Interactive Shell Issues

Q: Tab completion not working

# Solution: Reload agent/workflow lists
claude-force> /reload
✓ Cache cleared. Tab completion will refresh on next use.

Q: Command history lost between sessions

# History is stored in .claude/.shell-history
# Check permissions:
ls -la .claude/.shell-history

# Should show: -rw------- (owner read/write only)
# If not, the shell will fix it automatically on next run

Q: Colors not showing up

# Some terminals don't support ANSI colors
# Colors work in: iTerm2, Terminal.app, GNOME Terminal, Konsole, Windows Terminal
# Try updating your terminal or use --no-color flag (if available)

Q: Spinner animation looks broken

# Unicode spinners require UTF-8 support
# Check terminal encoding:
echo $LANG  # Should show something with UTF-8

# If needed, set encoding:
export LANG=en_US.UTF-8

API Key Issues

Q: "API key not found" error

# Set your API key:
export ANTHROPIC_API_KEY='your-api-key-here'

# Or use .env file:
echo 'ANTHROPIC_API_KEY=your-api-key-here' > .env

# Or run setup wizard:
claude-force setup

Q: "Invalid API key" error

# Verify your key:
echo $ANTHROPIC_API_KEY

# Get a new key from: https://console.anthropic.com/

Agent/Workflow Issues

Q: Agent not found

# List available agents:
claude-force list agents

# Search marketplace:
claude-force marketplace search <query>

# Refresh cache in shell:
claude-force> /reload

Q: Workflow fails partway through

# Check individual agent status:
claude-force metrics agents

# View detailed logs:
claude-force --verbose run workflow <name> --task "..."

# Try running agents individually:
claude-force run agent <agent-name> --task "..."

Performance Issues

Q: Commands are slow

# Enable cost optimization:
claude-force run agent <name> --task "..." --auto-select-model

# Use faster model:
claude-force run agent <name> --task "..." --model claude-3-haiku-20240307

# Check network:
ping api.anthropic.com

Q: High API costs

# View cost breakdown:
claude-force metrics costs --breakdown

# Enable cost threshold:
claude-force run agent <name> --task "..." --cost-threshold 0.50

# Use Haiku for simple tasks:
claude-force run agent <name> --task "..." --model claude-3-haiku-20240307

Installation Issues

Q: Command not found after installation

# Ensure pip installed to correct location:
pip install --user claude-force

# Add to PATH (Linux/Mac):
export PATH="$HOME/.local/bin:$PATH"

# Add to PATH (Windows):
# Add %USERPROFILE%\AppData\Local\Programs\Python\Python3X\Scripts to PATH

Q: Import errors

# Reinstall with dependencies:
pip install --force-reinstall claude-force

# Check Python version (requires 3.8+):
python --version

Getting Help

Still having issues?

1. Check verbose output: claude-force --verbose <command>
2. Run diagnostics: claude-force diagnose
3. Search issues: https://github.com/khanh-vu/claude-force/issues
4. Ask for help: Create a new GitHub issue with:
   • Your command
   • Error message
   • Output of claude-force diagnose --verbose
   • Python version (python --version)

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

See CONTRIBUTING.md for guidelines.

License

MIT License - See LICENSE file for details.

Support

• Documentation: See docs/
• Examples: See examples/
• Issues: GitHub Issues
• Tests: pytest test_claude_system.py -v

---

Version: 1.3.1 Status: Production-Ready ✅ Tests: 331/331 Passing ✅ Marketplace: Integrated ✅

Built with ❤️ for Claude by Anthropic