Frequently Asked Questions (FAQ)

Table of Contents

• Getting Started
• Installation & Setup
• Usage
• Agents & Workflows
• Performance & Cost
• Troubleshooting
• Advanced Topics
• Contributing

Getting Started

What is Claude Force?

Claude Force is a production-ready multi-agent orchestration system for Claude. It provides:

• 19 specialized AI agents for different domains (frontend, backend, security, etc.)
• 10 pre-built workflows for common development tasks
• Cost optimization through hybrid model selection
• Response caching for 60-80% cost savings
• Marketplace integration for community plugins

Who should use Claude Force?

Claude Force is ideal for:

• Developers who want AI assistance across multiple domains
• Teams who need consistent, governed AI interactions
• Projects requiring specialized expertise (security, architecture, etc.)
• Organizations that need cost-effective, production-ready AI orchestration

How does it compare to using Claude directly?

Feature	Claude Direct	Claude Force
Specialized agents	No	19 agents
Workflows	Manual	10 pre-built
Cost optimization	Manual	Automatic (60-80% savings)
Response caching	No	Yes
Governance	No	6-layer system
Performance tracking	No	Built-in
Skills integration	Manual	11 integrated skills

Installation & Setup

How do I install Claude Force?

# Option 1: Install from PyPI (recommended)
pip install claude-force

# Option 2: Install from source (development)
git clone https://github.com/khanh-vu/claude-force.git
cd claude-force
pip install -e .

See INSTALLATION.md for detailed instructions.

What Python version do I need?

Python 3.8 or higher. We test on:

• Python 3.8
• Python 3.9
• Python 3.10
• Python 3.11
• Python 3.12

Do I need an Anthropic API key?

Yes. Get one at https://console.anthropic.com/

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

# Or add to .env file
echo "ANTHROPIC_API_KEY=your-api-key-here" >> .env

Can I use Claude Force without an API key?

Yes, in demo mode:

# Run in demo mode (no API calls, shows examples)
claude-force demo

What dependencies are required?

Core dependencies (automatically installed):

• anthropic
• click
• pathlib

Optional dependencies:

# For semantic agent selection
pip install -e ".[semantic]"

# For REST API server
pip install -e ".[api]"

# For development
pip install -e ".[dev]"

# All features
pip install -e ".[all]"

Usage

How do I run my first agent?

# 1. Initialize a project
claude-force init my-project --interactive

# 2. Create a task file
echo "Review the authentication code in src/auth.py" > task.txt

# 3. Run an agent
claude-force run agent security-specialist --task-file task.txt

How do I choose the right agent?

Option 1: Automatic recommendation (easiest)

claude-force recommend --task "Your task description"
# Shows best agents with confidence scores

Option 2: List all agents

claude-force list agents
# Shows all 19 agents with descriptions

Option 3: Check agent skills

claude-force info security-specialist
# Shows detailed capabilities and use cases

Can I integrate claude-force with an existing project?

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

# Navigate to your existing project
cd my-existing-project

# Initialize claude-force (preserves existing files)
claude-force init --description "My existing project"

What happens:

• ✅ Preserves existing files (task.md, README.md, commands/, hooks/, etc.)
• ✅ Adds claude-force configuration (claude.json, agents/, contracts/)
• ✅ Shows what was created vs. preserved

Example output:

📁 Detected existing .claude directory (Claude Code project)
   Preserving existing files and adding claude-force configuration

✅ Project initialized successfully!

📂 Created 2 files:
   ✓ .claude/claude.json
   ✓ .claude/examples/example-task.md

📌 Preserved 15 existing files:
   ⊙ .claude/task.md
   ⊙ .claude/README.md
   ⊙ .claude/commands/custom-command.md
   ...

If you already have claude.json:

# Use --force to reinitialize
claude-force init --force --description "Reinitialize project"

How do I run a workflow?

# Run a pre-built workflow
claude-force run workflow full-stack-feature --task "Build user dashboard"

# List available workflows
claude-force list workflows

# Compose custom workflow from goal
claude-force compose --goal "Deploy ML model to production"

Can I use Claude Force programmatically?

Yes! Python API example:

from claude_force import AgentOrchestrator

# Initialize orchestrator
orchestrator = AgentOrchestrator()

# Run an agent
result = orchestrator.run_agent(
    agent_name='code-reviewer',
    task='Review this code for security issues'
)

if result.success:
    print(result.output)
else:
    print(f"Error: {result.errors}")

See examples/python/ for more examples.

How do I use the REST API?

# 1. Start the API server
cd examples/api-server
uvicorn api_server:app --reload

# 2. Use the API
curl -X POST http://localhost:8000/agent/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "agent_name": "code-reviewer",
    "task": "Review authentication code"
  }'

# 3. Or use the Python client
from api_client import ClaudeForceClient
client = ClaudeForceClient(base_url="http://localhost:8000", api_key="...")
result = client.run_agent_sync("code-reviewer", "Review this code")

See examples/api-server/README.md for full API documentation.

Agents & Workflows

What agents are available?

19 specialized agents across 7 categories:

Critical (P1):

• code-reviewer - Code quality & security review
• security-specialist - Security assessment & threat modeling
• bug-investigator - Root cause analysis & debugging
• frontend-architect - Frontend architecture design
• backend-architect - API and service architecture
• database-architect - Database schema design
• claude-code-expert - Claude Code system orchestration

High Priority (P2):

• python-expert - Python implementation
• ui-components-expert - React component library
• frontend-developer - Feature implementation
• devops-architect - Infrastructure and CI/CD
• google-cloud-expert - GCP architecture
• ai-engineer - AI/ML development & LLM integration
• prompt-engineer - Prompt design & optimization
• data-engineer - Data pipelines & ETL

Medium Priority (P3):

• deployment-integration-expert - Deployment configuration
• qc-automation-expert - Testing and QA
• document-writer-expert - Technical documentation
• api-documenter - API documentation

What workflows are available?

10 pre-built workflows:

1. full-stack-feature - Complete feature (10 agents)
2. frontend-only - Frontend development (5 agents)
3. backend-only - Backend API development (6 agents)
4. infrastructure - Infrastructure setup (4 agents)
5. bug-fix - Bug investigation and resolution (3 agents)
6. documentation - Documentation generation (2 agents)
7. ai-ml-development - AI/ML solution development (5 agents)
8. data-pipeline - Data engineering and ETL (4 agents)
9. llm-integration - LLM-powered features (5 agents)
10. claude-code-system - Claude Code system development (3 agents)

Can I create custom agents?

Yes! See CONTRIBUTING.md#adding-a-new-agent for the guide.

Quick steps:

1. Create agent definition in .claude/agents/
2. Create contract in .claude/contracts/
3. Register in claude.json
4. Add tests

Can I create custom workflows?

Yes! Edit claude.json:

{
  "workflows": {
    "my-custom-workflow": [
      "agent-1",
      "agent-2",
      "agent-3"
    ]
  }
}

Or use the workflow composer:

claude-force compose --goal "Your workflow goal" --save-as my-workflow

Performance & Cost

How much does it cost to use Claude Force?

API costs (Anthropic pricing):

• Haiku: ~$0.001 per simple task
• Sonnet: ~$0.01 per complex task
• Opus: ~$0.05 per critical task

Cost optimization features:

• Hybrid orchestration: 40-60% savings
• Response caching: 60-80% savings on repeated tasks
• Progressive skills loading: 30-50% token reduction

Example costs with optimization:

• Simple documentation task: $0.001 (Haiku, often cached)
• Code review: $0.01 (Sonnet, cached after first run)
• Security audit: $0.05 (Opus, requires fresh analysis)

How do I reduce costs?

1. Enable auto model selection

claude-force run agent document-writer-expert \
  --task "Generate docs" \
  --auto-select-model
# Automatically uses cheaper Haiku for documentation

2. Use response caching

# Enabled by default
# Caches responses for 90 days
# 60-80% cost reduction on repeated tasks

3. Set cost thresholds

claude-force run agent code-reviewer \
  --task "Review codebase" \
  --cost-threshold 0.50
# Rejects tasks estimated to cost more than $0.50

4. Use progressive skills loading

# Automatically loads only relevant skills
# 30-50% token reduction (15K → 5-8K tokens)

How fast is Claude Force?

Performance benchmarks:

• Cache hit: 1ms (vs 800ms API call) = 800x faster
• Semantic agent selection: 30 seconds (vs 5 minutes manual) = 10x faster
• Concurrent workflows: 10x throughput with async orchestration

Response times (typical):

• Simple task (Haiku): 800ms (1ms if cached)
• Complex task (Sonnet): 2,500ms (1ms if cached)
• Full workflow (3 agents): 7,500ms (3ms if all cached)

Does response caching affect quality?

No. Caching is based on:

• Exact task match: Task description must be identical
• Same agent: Only caches per-agent responses
• Integrity verification: HMAC-SHA256 prevents tampering
• 90-day TTL: Cache expires after 90 days

If task or context changes, cache automatically misses and fresh response is generated.

How do I monitor performance?

# View performance summary
claude-force metrics summary

# View per-agent metrics
claude-force metrics agents

# View cost analysis
claude-force metrics costs

# Export for analysis
claude-force metrics export metrics.json --format json

Python API:

orchestrator = AgentOrchestrator(enable_tracking=True)

# Run agents (tracking is automatic)
result = orchestrator.run_agent("code-reviewer", task="...")

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

Troubleshooting

Error: "ANTHROPIC_API_KEY not found"

Solution:

# Set environment variable
export ANTHROPIC_API_KEY='your-api-key-here'

# Or add to .env file
echo "ANTHROPIC_API_KEY=your-api-key-here" >> .env

# Verify it's set
claude-force diagnose

Error: "Agent not found"

Solution:

# List available agents
claude-force list agents

# Check agent name spelling
claude-force info security-specialist  # correct
claude-force info security-expert      # incorrect

Error: "Module not found: sentence-transformers"

Cause: Semantic selection requires optional dependencies.

Solution:

# Install semantic dependencies
pip install -e ".[semantic]"

# Or disable semantic selection
claude-force run agent code-reviewer --task "..." --no-semantic

Performance is slow

Possible causes and solutions:

1. First-time semantic model loading (90-420MB)

   • Normal on first use
   • Subsequent uses are fast (lazy-loaded)

2. Large task description (>10K tokens)

   • Solution: Simplify task description
   • Use progressive skills loading

3. Network latency

   • Check internet connection
   • Try again or use cached responses

4. Too many concurrent requests

   • Use async orchestrator with rate limiting
   • Default: 3 concurrent requests max

Cache not working

Check:

# Verify cache is enabled
claude-force config show | grep cache

# Check cache size
du -sh .claude/cache

# Clear cache if corrupted
rm -rf .claude/cache/*.db

Enable caching:

orchestrator = AgentOrchestrator(enable_cache=True)

Tests failing

# See detailed output
python3 -m pytest tests/ -v --tb=short

# Run specific test
python3 -m pytest tests/test_orchestrator.py::test_run_agent -v

# Check test coverage
python3 -m pytest tests/ --cov=claude_force --cov-report=html

For more troubleshooting, see TROUBLESHOOTING.md.

Advanced Topics

How do I integrate with GitHub Actions?

See examples/github-actions/ for:

• Automated code review on PRs
• Security scanning
• Documentation generation

Example:

name: Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Claude Force
        run: pip install claude-force
      - name: Run Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude-force run agent code-reviewer \
            --task "Review PR changes" \
            --output review.md

Can I use Claude Force in CI/CD?

Yes! Claude Force has a quiet mode for scripting:

# Quiet mode (minimal output)
claude-force run agent code-reviewer --task "..." --quiet

# JSON output for parsing
claude-force run agent security-specialist --task "..." --format json

# Exit codes for CI/CD
if claude-force run agent code-reviewer --task "..." --quiet; then
  echo "Review passed"
else
  echo "Review failed"
  exit 1
fi

How do I use the MCP server?

The MCP (Model Context Protocol) server enables integration with Claude Code:

# Start MCP server
python -m claude_force.mcp_server --port 8080

# Configure in Claude Code
# Add to MCP servers list: http://localhost:8080

See examples/mcp/README.md for full setup.

How do I use the marketplace?

# Search for plugins
claude-force marketplace search "kubernetes"

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

# List installed plugins
claude-force marketplace list --installed

# Uninstall plugin
claude-force marketplace uninstall wshobson-devops-toolkit

Can I import agents from other repositories?

Yes! Claude Force supports agent import/export:

# Import from wshobson/agents
claude-force import wshobson kubernetes-engineer.md

# Export for sharing
claude-force export ai-engineer --format wshobson

# Bulk import
claude-force import wshobson *.md

How do I contribute to the marketplace?

See CONTRIBUTING.md and:

# Validate your agent
claude-force contribute validate my-agent.md

# Prepare for submission
claude-force contribute prepare my-agent.md
# Generates PR template and validation report

What security measures are in place?

Multiple security layers:

• ✅ Path traversal prevention
• ✅ Input validation and sanitization
• ✅ HMAC-SHA256 cache verification
• ✅ Secure API key handling (never logged)
• ✅ Secret scanning (prevents commits with keys)
• ✅ SQL injection prevention (parameterized queries)
• ✅ Rate limiting

Security Grade: A- (Excellent)

See SECURITY_REVIEW.md for full audit.

How do I configure logging?

# Set log level
export CLAUDE_LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR

# Log to file
export CLAUDE_LOG_FILE=claude-force.log

# Or use config
claude-force config set log_level DEBUG
claude-force config set log_file claude-force.log

Python API:

import logging

logging.basicConfig(level=logging.DEBUG)
orchestrator = AgentOrchestrator()

Contributing

How can I contribute?

See CONTRIBUTING.md for:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process

Ways to contribute:

• 🐛 Report bugs
• 💡 Suggest features
• 📝 Improve documentation
• 🧪 Add tests
• 🤖 Create new agents
• ⚙️ Create new skills
• 🔧 Fix issues

Where do I report bugs?

GitHub Issues: https://github.com/khanh-vu/claude-force/issues

Include:

• Claude Force version (claude-force --version)
• Python version (python --version)
• Error message and stack trace
• Steps to reproduce
• Expected vs actual behavior

How do I request features?

GitHub Issues with label enhancement: https://github.com/khanh-vu/claude-force/issues/new?labels=enhancement

Include:

• Clear description of feature
• Use cases and benefits
• Proposed implementation (if applicable)
• Examples of similar features elsewhere

Can I use Claude Force commercially?

Yes! Claude Force is MIT licensed. You can:

• ✅ Use commercially
• ✅ Modify
• ✅ Distribute
• ✅ Sublicense

Requirements:

• Include MIT license and copyright notice
• Comply with Anthropic's API terms of service

---

Still have questions?

• 📖 Read the documentation
• 🔍 Search existing issues
• 💬 Start a discussion
• 📧 Contact the maintainers

Quick Links:

• README.md - Project overview
• QUICK_START.md - 5-minute guide
• INSTALLATION.md - Detailed setup
• TROUBLESHOOTING.md - Common issues
• CONTRIBUTING.md - How to contribute
• ARCHITECTURE.md - System design