🤖 Agentic Flow

Production-Ready AI Agent Orchestration with Multi-Model Router, OpenRouter Integration & Free Local Inference

I built Agentic Flow to easily switch between alternative low-cost AI models in Claude Code/Agent SDK. For those comfortable using Claude agents and commands, it lets you take what you've created and deploy fully hosted agents for real business purposes. Use Claude Code to get the agent working, then deploy it in your favorite cloud.

Agentic Flow runs Claude Code agents at near zero cost without rewriting a thing. The built-in model optimizer automatically routes every task to the cheapest option that meets your quality requirements—free local models for privacy, OpenRouter for 99% cost savings, Gemini for speed, or Anthropic when quality matters most. It analyzes each task and selects the optimal model from 27+ options with a single flag, reducing API costs dramatically compared to using Claude exclusively.

The system spawns specialized agents on demand through Claude Code's Task tool and MCP coordination. It orchestrates swarms of 66+ pre-built agents (researchers, coders, reviewers, testers, architects) that work in parallel, coordinate through shared memory, and auto-scale based on workload. Transparent OpenRouter and Gemini proxies translate Anthropic API calls automatically—no code changes needed. Local models run direct without proxies for maximum privacy. Switch providers with environment variables, not refactoring.

Extending agent capabilities is effortless. Add custom tools and integrations through the CLI—weather data, databases, search engines, or any external service—without touching config files. Your agents instantly gain new abilities across all projects. Every tool you add becomes available to the entire agent ecosystem automatically, and all operations are logged with full traceability for auditing, debugging, and compliance. This means your agents can connect to proprietary systems, third-party APIs, or internal tools in seconds, not hours.

Define routing rules through flexible policy modes: Strict mode keeps sensitive data offline, Economy mode prefers free models (99% savings), Premium mode uses Anthropic for highest quality, or create custom cost/quality thresholds. The policy defines the rules; the swarm enforces them automatically. Runs local for development, Docker for CI/CD, or Flow Nexus cloud for production scale. Agentic Flow is the framework for autonomous efficiency—one unified runner for every Claude Code agent, self-tuning, self-routing, and built for real-world deployment.

Get Started:

# Run an agent with automatic cost optimization
npx agentic-flow --agent coder --task "Build a REST API" --optimize

# Add custom MCP tools instantly
npx agentic-flow mcp add weather 'npx @modelcontextprotocol/server-weather'

# Install globally for faster access
npm install -g agentic-flow

Built on Claude Agent SDK by Anthropic, powered by Claude Flow (101 MCP tools), Flow Nexus (96 cloud tools), OpenRouter (100+ LLM models), Google Gemini (fast, cost-effective inference), Agentic Payments (payment authorization), and ONNX Runtime (free local CPU or GPU inference).

Why Agentic Flow?

The Problem: You need agents that actually complete tasks, not chatbots that need constant supervision. Long-running workflows - migrating codebases, generating documentation, analyzing datasets - shouldn't require you to sit there clicking "continue."

What True Agentic Systems Need:

Autonomy - Agents that plan, execute, and recover from errors without hand-holding
Persistence - Tasks that run for hours, even when you're offline
Collaboration - Multiple agents coordinating on complex work
Tool Access - Real capabilities: file systems, APIs, databases, not just text generation
Cost Control - Run cheap models for grunt work, expensive ones only when needed

What You Get:

150+ Specialized Agents - Researcher, coder, reviewer, tester, architect - each with domain expertise and tool access
Multi-Agent Swarms - Deploy 3, 10, or 100 agents that collaborate via shared memory to complete complex projects
Long-Running Tasks - Agents persist through hours-long operations: full codebase refactors, comprehensive audits, dataset processing
213 MCP Tools - Agents have real capabilities: GitHub operations, neural network training, workflow automation, memory persistence
Auto Model Optimization - --optimize flag intelligently selects best model for each task. DeepSeek R1 costs 85% less than Claude with similar quality. Save $2,400/month on 100 daily reviews.
Deploy Anywhere - Same agentic capabilities locally, in Docker/Kubernetes, or cloud sandboxes

Real Agentic Use Cases:

Overnight Code Migration - Deploy a swarm to migrate a 50K line codebase from JavaScript to TypeScript while you sleep
Continuous Security Audits - Agents monitor repos, analyze PRs, and flag vulnerabilities 24/7
Automated API Development - One agent designs schema, another implements endpoints, a third writes tests - all coordinated
Data Pipeline Processing - Agents process TBs of data across distributed sandboxes, checkpoint progress, and recover from failures

True autonomy at commodity prices. Your agents work independently on long-running tasks, coordinate when needed, and cost pennies per hour instead of dollars.

Built on Industry Standards

Claude Agent SDK - Anthropic's official SDK for building AI agents
Claude Flow - 101 MCP tools for orchestration, memory, GitHub, neural networks
Flow Nexus - 96 cloud tools for sandboxes, distributed swarms, workflows
OpenRouter - Access to 100+ LLM models at 99% cost savings (Llama, DeepSeek, Gemini, etc.)
Agentic Payments - Multi-agent payment authorization with Ed25519 cryptography
ONNX Runtime - Free local CPU/GPU inference with Microsoft Phi-4

🚀 Quick Start

Local Installation (Recommended for Development)

# Global installation
npm install -g agentic-flow

# Or use directly with npx (no installation)
npx agentic-flow --help

# MCP server management
npx agentic-flow mcp start

# Set your API key
export ANTHROPIC_API_KEY=sk-ant-...

Your First Agent (Local Execution)

# Run locally with full 203 MCP tool access (Claude)
npx agentic-flow \
  --agent researcher \
  --task "Analyze microservices architecture trends in 2025"

# Run with OpenRouter for 99% cost savings
export OPENROUTER_API_KEY=sk-or-v1-...
npx agentic-flow \
  --agent coder \
  --task "Build a REST API with authentication" \
  --model "meta-llama/llama-3.1-8b-instruct"

# Enable real-time streaming to see output as it's generated
npx agentic-flow \
  --agent coder \
  --task "Build a web scraper" \
  --stream

# The agent executes on your machine, uses all MCP tools, and terminates

Multi-Agent Swarm (Local)

# 3 agents work in parallel on your machine
export TOPIC="API security best practices"
export DIFF="feat: add OAuth2 authentication"
export DATASET="API response times last 30 days"

npx agentic-flow  # Spawns: researcher + code-reviewer + data-analyst

Local Benefits:

✅ All 203 MCP tools work (full subprocess support)
✅ Fast iteration and debugging
✅ No cloud costs during development
✅ Full access to local filesystem and resources

Docker Deployment (Production)

# Build container
docker build -f deployment/Dockerfile -t agentic-flow .

# Run agent with Claude (Anthropic)
docker run --rm \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  agentic-flow \
  --agent researcher \
  --task "Analyze cloud patterns"

# Run agent with OpenRouter (99% cost savings)
docker run --rm \
  -e OPENROUTER_API_KEY=sk-or-v1-... \
  agentic-flow \
  --agent coder \
  --task "Build REST API" \
  --model "meta-llama/llama-3.1-8b-instruct"

Container Benefits:

✅ All 203 MCP tools work (full subprocess support)
✅ OpenRouter proxy auto-starts in container
✅ Reproducible builds and deployments
✅ Works on Kubernetes, ECS, Cloud Run, Fargate
✅ Isolated execution environment

✨ Key Features

🔄 Ephemeral Architecture

On-Demand Spawning - Agents created only when needed
Automatic Cleanup - Terminate after task completion
Stateless Execution - No persistent state between runs
Cost-Optimized - Pay only for actual compute time

🤖 Multi-Model Router with ONNX Local Inference

Intelligent Provider Routing - Automatic selection between Anthropic, OpenRouter, and ONNX based on task requirements
100% Free Local Inference - ONNX Runtime CPU/GPU execution with Microsoft Phi-4 (zero API costs)
Privacy-First Processing - GDPR/HIPAA-compliant local processing for sensitive workloads
Cost Optimization - Route privacy tasks to free ONNX, complex reasoning to cloud APIs
Rule-Based Routing - Automatic provider selection based on privacy, cost, and performance
GPU Acceleration Ready - CPU inference at 6 tokens/sec, GPU capable of 60-300 tokens/sec
Zero-Cost Agents - Run agents entirely offline with local ONNX models

💻 Local Development (Full Features)

Native Execution - Run directly on macOS, Linux, Windows
All 203 MCP Tools - Full subprocess support, no restrictions
Fast Iteration - Instant feedback, no cold starts
Persistent Memory - Claude Flow memory persists across runs
File System Access - Full access to local files and directories
Git Integration - Direct GitHub operations and repository management
Zero Cloud Costs - Free during development

🐳 Container Deployment (Production Ready)

Docker Support - Complete feature set for ECS, Cloud Run, Kubernetes
All 203 MCP Tools - Full subprocess support in containers
Reproducible Builds - Same environment across dev/staging/prod
Orchestration Ready - Works with Kubernetes Jobs, ECS Tasks, Cloud Run
Health Checks Built-in - /health endpoint for load balancers
Resource Controls - CPU/memory limits via container configs

☁️ Cloud Sandboxes (Scalable Execution)

Flow Nexus E2B Sandboxes - Fully isolated execution environments
All 203 MCP Tools - Complete tool access in cloud sandboxes
Multi-Language Templates - Node.js, Python, React, Next.js
Real-Time Streaming - Live output and monitoring
Auto-Scaling - Spin up 1 to 100+ sandboxes on demand
Pay-Per-Use - Only pay for actual sandbox runtime (≈$1/hour)

🤖 Intelligent Agents

150+ Pre-Built Specialists - Researchers, coders, testers, reviewers, architects
Swarm Coordination - Agents collaborate via shared memory
Tool Access - 200+ MCP tools for GitHub, neural networks, workflows
Custom Agents - Define your own in YAML with system prompts

📊 Observability

Real-Time Streaming - See agent output token-by-token as it's generated with --stream flag
Structured Logging - JSON logs for aggregation and analysis
Performance Metrics - Track agent duration, tool usage, token consumption
Health Checks - Built-in healthcheck endpoint for orchestrators

🚀 Deployment Options

💻 Local Execution (Best for Development)

Full-featured, all 203 MCP tools work:

# Install globally
npm install -g agentic-flow

# Set API key
export ANTHROPIC_API_KEY=sk-ant-...

# Run any agent locally
npx agentic-flow --agent coder --task "Build REST API"

# Multi-agent swarm (3 agents in parallel)
npx agentic-flow  # Uses TOPIC, DIFF, DATASET env vars

Why Local Development?

✅ All 203 MCP Tools: Full subprocess support (claude-flow, flow-nexus, agentic-payments)
✅ Fast Iteration: No cold starts, instant feedback
✅ Free: No cloud costs during development
✅ File Access: Direct access to local filesystem
✅ Git Integration: Full GitHub operations
✅ Memory Persistence: Claude Flow memory persists across runs
✅ Easy Debugging: Standard Node.js debugging tools work

System Requirements:

Node.js ≥18.0.0
npm or pnpm
2GB RAM minimum (4GB recommended for swarms)
macOS, Linux, or Windows

🎯 Flow Nexus Cloud Sandboxes (Best for Production Scale)

// Create isolated sandbox and execute agent with full MCP tool access
const { query } = require('@anthropic-ai/claude-agent-sdk');

// 1. Login to Flow Nexus
await flowNexus.login({ email: 'user@example.com', password: 'secure' });

// 2. Create E2B sandbox with Node.js template
const sandbox = await flowNexus.sandboxCreate({
  template: 'node',
  name: 'agent-execution',
  env_vars: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }
});

// 3. Execute agent in sandbox with all 203 MCP tools
const result = await flowNexus.sandboxExecute({
  sandbox_id: sandbox.id,
  code: `
    const { query } = require('@anthropic-ai/claude-agent-sdk');
    const result = await query({
      prompt: "Analyze API security patterns",
      options: {
        mcpServers: { /* all 3 MCP servers available */ }
      }
    });
    console.log(result);
  `
});

// 4. Automatic cleanup
await flowNexus.sandboxDelete({ sandbox_id: sandbox.id });

Why Flow Nexus?

✅ Full 203 MCP tool support (all subprocess servers work)
✅ Persistent memory across sandbox instances
✅ Multi-language templates (Node.js, Python, React, Next.js)
✅ Real-time output streaming
✅ Secure process isolation
✅ Pay-per-use pricing (10 credits/hour)

🐳 Docker Containers (Best for Production Deployments)

Full 203 MCP tool support in containers:

# Build image
docker build -t agentic-flow .

# Run single agent
docker run --rm \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  agentic-flow \
  --agent researcher \
  --task "Analyze microservices patterns"

# Multi-agent swarm in container
docker run --rm \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e TOPIC="API security" \
  -e DIFF="feat: auth" \
  -e DATASET="logs.json" \
  agentic-flow

Why Docker?

✅ All 203 MCP Tools: Full subprocess support
✅ Production Ready: Works on Kubernetes, ECS, Cloud Run, Fargate
✅ Reproducible: Same environment everywhere
✅ Isolated: Process isolation and security
✅ Orchestration: Integrates with container orchestrators
✅ CI/CD: Perfect for automated workflows

Container Orchestration Examples:

# Kubernetes Job
apiVersion: batch/v1
kind: Job
metadata:
  name: code-review
spec:
  template:
    spec:
      containers:
      - name: agent
        image: agentic-flow:latest
        args: ["--agent", "code-review", "--task", "Review PR #123"]
        env:
        - name: ANTHROPIC_API_KEY
          valueFrom:
            secretKeyRef:
              name: anthropic
              key: api-key
      restartPolicy: Never

# GitHub Actions
- name: AI Code Review
  run: |
    docker run -e ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }} \
      agentic-flow:latest \
      --agent code-review \
      --task "${{ github.event.pull_request.diff }}"

# AWS ECS Task Definition
{
  "family": "agentic-flow-task",
  "containerDefinitions": [{
    "name": "agent",
    "image": "agentic-flow:latest",
    "command": ["--agent", "researcher", "--task", "$(TASK)"],
    "environment": [
      {"name": "ANTHROPIC_API_KEY", "value": "from-secrets-manager"}
    ]
  }]
}

🔓 ONNX Local Inference (Free Offline AI)

Run agents completely offline with zero API costs:

# Auto-downloads Phi-4 model (~4.9GB one-time download)
npx agentic-flow \
  --agent coder \
  --task "Build a REST API" \
  --provider onnx

# Router auto-selects ONNX for privacy-sensitive tasks
npx agentic-flow \
  --agent researcher \
  --task "Analyze confidential medical records" \
  --privacy high \
  --local-only

ONNX Capabilities:

✅ 100% free local inference (Microsoft Phi-4 model)
✅ Privacy: All processing stays on your machine
✅ Offline: No internet required after model download
✅ Performance: ~6 tokens/sec CPU, 60-300 tokens/sec GPU
✅ Auto-download: Model fetches automatically on first use
✅ Quantized: INT4 optimization for efficiency (~4.9GB total)
⚠️ Limited to 6 in-SDK tools (no subprocess MCP servers)
📚 See docs for full capabilities

🎯 Use Cases & Costs

Use Case	Agent Type	Execution Time	Local Cost	Docker Cost	Flow Nexus Cost
Code Review	`code-review`	15-45s	Free*	Self-hosted	0.13-0.38 credits
API Testing	`tester`	10-30s	Free*	Self-hosted	0.08-0.25 credits
Documentation	`api-docs`	20-60s	Free*	Self-hosted	0.17-0.50 credits
Data Analysis	`data-analyst`	30-90s	Free*	Self-hosted	0.25-0.75 credits
Security Audit	`reviewer`	45-120s	Free*	Self-hosted	0.38-1.00 credits
Microservice Generation	`backend-dev`	60-180s	Free*	Self-hosted	0.50-1.50 credits
Performance Analysis	`perf-analyzer`	20-60s	Free*	Self-hosted	0.17-0.50 credits

Local: Free infrastructure, Claude API costs only ($0.003-0.015 per input 1K tokens, $0.015-0.075 per output 1K tokens) Flow Nexus: 10 credits/hour sandbox (≈$1/hour) + Claude API costs. 1 credit ≈ $0.10. Docker: Infrastructure costs (AWS/GCP/Azure) + Claude API costs.

Recommendation by Scenario:

Development/Testing: Use Local - free, fast, full tools
CI/CD Pipelines: Use Docker - reproducible, isolated
Production Scale: Use Flow Nexus - auto-scaling, cloud-native

🤖 Agent Types

Core Development Agents

coder - Implementation specialist for writing clean, efficient code
reviewer - Code review and quality assurance
tester - Comprehensive testing with 90%+ coverage
planner - Strategic planning and task decomposition
researcher - Deep research and information gathering

Specialized Agents

backend-dev - REST/GraphQL API development
mobile-dev - React Native mobile apps
ml-developer - Machine learning model creation
system-architect - System design and architecture
cicd-engineer - CI/CD pipeline creation
api-docs - OpenAPI/Swagger documentation

Swarm Coordinators

hierarchical-coordinator - Tree-based leadership
mesh-coordinator - Peer-to-peer coordination
adaptive-coordinator - Dynamic topology switching
swarm-memory-manager - Cross-agent memory sync

GitHub Integration

pr-manager - Pull request lifecycle management
code-review-swarm - Multi-agent code review
issue-tracker - Intelligent issue management
release-manager - Automated release coordination
workflow-automation - GitHub Actions specialist

Performance & Analysis

perf-analyzer - Performance bottleneck detection
production-validator - Deployment readiness checks
tdd-london-swarm - Test-driven development

Use npx agentic-flow --list to see all 150+ agents

🎯 Model Optimization (NEW!)

Automatically select the optimal model for any agent and task, balancing quality, cost, and speed based on your priorities.

Why Model Optimization?

Different tasks need different models:

Production code → Claude Sonnet 4.5 (highest quality)
Code reviews → DeepSeek R1 (85% cheaper, nearly same quality)
Simple functions → Llama 3.1 8B (99% cheaper)
Privacy-critical → ONNX Phi-4 (free, local, offline)

The optimizer analyzes your agent type + task complexity and recommends the best model automatically.

Quick Examples

# Let the optimizer choose (balanced quality vs cost)
npx agentic-flow --agent coder --task "Build REST API" --optimize

# Optimize for lowest cost
npx agentic-flow --agent coder --task "Simple function" --optimize --priority cost

# Optimize for highest quality
npx agentic-flow --agent reviewer --task "Security audit" --optimize --priority quality

# Optimize for speed
npx agentic-flow --agent researcher --task "Quick analysis" --optimize --priority speed

# Set maximum budget ($0.001 per task)
npx agentic-flow --agent coder --task "Code cleanup" --optimize --max-cost 0.001

Optimization Priorities

quality (70% quality, 20% speed, 10% cost) - Best results, production code
balanced (40% quality, 40% cost, 20% speed) - Default, good mix
cost (70% cost, 20% quality, 10% speed) - Cheapest, development/testing
speed (70% speed, 20% quality, 10% cost) - Fastest responses
privacy - Local-only models (ONNX), zero cloud API calls

Model Tier Examples

The optimizer chooses from 10+ models across 5 tiers:

Tier 1: Flagship (premium quality)

Claude Sonnet 4.5 - $3/$15 per 1M tokens
GPT-4o - $2.50/$10 per 1M tokens
Gemini 2.5 Pro - $0.00/$2.00 per 1M tokens

Tier 2: Cost-Effective (2025 breakthrough models)

DeepSeek R1 - $0.55/$2.19 per 1M tokens (85% cheaper, flagship quality)
DeepSeek Chat V3 - $0.14/$0.28 per 1M tokens (98% cheaper)

Tier 3: Balanced

Gemini 2.5 Flash - $0.07/$0.30 per 1M tokens (fastest)
Llama 3.3 70B - $0.30/$0.30 per 1M tokens (open-source)

Tier 4: Budget

Llama 3.1 8B - $0.055/$0.055 per 1M tokens (ultra-low cost)

Tier 5: Local/Privacy

ONNX Phi-4 - FREE (offline, private, no API)

Agent-Specific Recommendations

The optimizer knows what each agent needs:

# Coder agent → prefers high quality (min 85/100)
npx agentic-flow --agent coder --task "Production API" --optimize
# → Selects: DeepSeek R1 (quality 90, cost 85)

# Researcher agent → flexible, can use cheaper models
npx agentic-flow --agent researcher --task "Trend analysis" --optimize --priority cost
# → Selects: Gemini 2.5 Flash (quality 78, cost 98)

# Reviewer agent → needs reasoning (min 85/100)
npx agentic-flow --agent reviewer --task "Security review" --optimize
# → Selects: DeepSeek R1 (quality 90, reasoning-optimized)

# Tester agent → simple tasks, use budget models
npx agentic-flow --agent tester --task "Unit tests" --optimize --priority cost
# → Selects: Llama 3.1 8B (cost 95)

Cost Savings Examples

Without Optimization (always using Claude Sonnet 4.5):

100 code reviews/day × $0.08 each = $8/day = $240/month

With Optimization (DeepSeek R1 for reviews):

100 code reviews/day × $0.012 each = $1.20/day = $36/month
Savings: $204/month (85% reduction)

Comprehensive Model Guide

For detailed analysis of all 10 models, see: 📖 Model Capabilities Guide

Includes:

Full benchmark results across 6 task types
Cost comparison tables
Use case decision matrices
Performance characteristics
Best practices by model

MCP Tool for Optimization

// Get model recommendation via MCP tool
await query({
  mcp: {
    server: 'agentic-flow',
    tool: 'agentic_flow_optimize_model',
    params: {
      agent: 'coder',
      task: 'Build REST API with auth',
      priority: 'balanced',  // quality | balanced | cost | speed | privacy
      max_cost: 0.01         // optional budget cap in dollars
    }
  }
});

Learn More:

See benchmarks/README.md for quick results
Run your own tests: cd docs/agentic-flow/benchmarks && ./quick-benchmark.sh

📋 Commands

MCP Server Management (Direct Tool Access)

# Start all MCP servers (213 tools)
npx agentic-flow mcp start

# Start specific MCP server
npx agentic-flow mcp start claude-flow      # 101 tools
npx agentic-flow mcp start flow-nexus       # 96 cloud tools
npx agentic-flow mcp start agentic-payments # Payment tools

# List all available MCP tools (213 total)
npx agentic-flow mcp list

# Check MCP server status
npx agentic-flow mcp status

# Stop MCP servers
npx agentic-flow mcp stop [server]

MCP Servers Available:

claude-flow (101 tools): Neural networks, GitHub integration, workflows, DAA, performance
flow-nexus (96 tools): E2B sandboxes, distributed swarms, templates, cloud storage
agentic-payments (10 tools): Payment authorization, Ed25519 signatures, consensus
claude-flow-sdk (6 tools): In-process memory and swarm coordination

Add Custom MCP Servers (No Code Required) ✨ NEW in v1.2.1

Add your own MCP servers via CLI without editing code—extends agent capabilities in seconds:

# Add MCP server (Claude Desktop style JSON config)
npx agentic-flow mcp add weather '{"command":"npx","args":["-y","weather-mcp"],"env":{"API_KEY":"xxx"}}'

# Add MCP server (flag-based)
npx agentic-flow mcp add github --npm @modelcontextprotocol/server-github --env "GITHUB_TOKEN=ghp_xxx"

# Add local MCP server
npx agentic-flow mcp add my-tools --local /path/to/server.js

# List configured servers
npx agentic-flow mcp list

# Enable/disable servers
npx agentic-flow mcp enable weather
npx agentic-flow mcp disable weather

# Remove server
npx agentic-flow mcp remove weather

# Test server configuration
npx agentic-flow mcp test weather

# Export/import configurations
npx agentic-flow mcp export ./mcp-backup.json
npx agentic-flow mcp import ./mcp-backup.json

Configuration stored in: ~/.agentic-flow/mcp-config.json

Usage: Once configured, all enabled MCP servers automatically load in agents. No need to specify which server to use - tools are available by name (e.g., mcp__weather__get_forecast).

Example: After adding weather MCP:

npx agentic-flow --agent researcher --task "Get weather forecast for Tokyo"

Popular MCP Servers:

@modelcontextprotocol/server-filesystem - File system access
@modelcontextprotocol/server-github - GitHub operations
@modelcontextprotocol/server-brave-search - Web search
weather-mcp - Weather data
database-mcp - Database operations

v1.2.1 Improvements:

✅ CLI routing fixed - mcp add/list/remove commands now work correctly
✅ Model optimizer filters models without tool support automatically
✅ Full compatibility with Claude Desktop config format
✅ Test command for validating server configurations
✅ Export/import for backing up and sharing configurations

Documentation: See docs/guides/ADDING-MCP-SERVERS-CLI.md for complete guide.

Basic Operations (Works Locally, Docker, Cloud)

# List all available agents (150+ total)
npx agentic-flow --list

# Run specific agent (local execution)
npx agentic-flow --agent <name> --task "<description>"

# Enable real-time streaming output (see responses token-by-token)
npx agentic-flow --agent coder --task "Build API" --stream

# Run parallel mode (3 agents simultaneously)
npx agentic-flow  # Requires TOPIC, DIFF, DATASET env vars

Environment Configuration

# Required
export ANTHROPIC_API_KEY=sk-ant-...

# Agent mode (optional)
export AGENT=researcher
export TASK="Your task description"

# Parallel mode (optional)
export TOPIC="research topic"
export DIFF="code changes"
export DATASET="data to analyze"

# Options
export ENABLE_STREAMING=true
export HEALTH_PORT=8080

Docker Deployment

# Build image
docker build -t agentic-flow .

# Run agent in container
docker run --rm \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  agentic-flow \
  --agent researcher \
  --task "Analyze cloud patterns"

# Run with real-time streaming output
docker run --rm \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e ENABLE_STREAMING=true \
  agentic-flow \
  --agent coder --task "Build REST API" --stream

🎛️ Using the Multi-Model Router

Quick Start with Router

import { ModelRouter } from 'agentic-flow/router';

// Initialize router (auto-loads configuration)
const router = new ModelRouter();

// Use default provider (Anthropic)
const response = await router.chat({
  model: 'claude-3-5-sonnet-20241022',
  messages: [{ role: 'user', content: 'Your prompt here' }]
});

console.log(response.content[0].text);
console.log(`Cost: $${response.metadata.cost}`);

Available Providers

The router supports multiple LLM providers with automatic fallback:

Anthropic (Cloud)

Models: Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus
Cost: $0.003/1K input tokens, $0.015/1K output tokens
Best for: Complex reasoning, advanced coding, long conversations

OpenRouter (Multi-Model Gateway)

Models: 100+ models from multiple providers
Cost: $0.002-0.10/1K tokens (varies by model)
Best for: Cost optimization, model diversity, fallback

Google Gemini (Cloud)

Models: Gemini 2.0 Flash Exp, Gemini 2.5 Flash, Gemini 2.5 Pro
Cost: $0.075/1M input tokens, $0.30/1M output tokens (Flash), Free up to rate limits
Best for: Speed-optimized tasks, cost-effective inference, rapid prototyping

ONNX Runtime (Free Local)

Models: Microsoft Phi-4-mini-instruct (INT4 quantized)
Cost: $0.00 (100% free)
Best for: Privacy-sensitive data, offline operation, zero-cost development

Ollama (Local Server - Coming Soon)

Models: Any Ollama-supported model
Cost: Free (requires local Ollama server)
Best for: Local development with larger models

LiteLLM (Gateway - Coming Soon)

Models: Unified API for 100+ providers
Cost: Varies by provider
Best for: Multi-cloud deployments

Configuration Example:

// router.config.json
{
  "defaultProvider": "anthropic",
  "fallbackChain": ["anthropic", "onnx", "openrouter"],
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-...",
      "models": { "default": "claude-3-5-sonnet-20241022" }
    },
    "openrouter": {
      "apiKey": "sk-or-...",
      "baseUrl": "https://openrouter.ai/api/v1",
      "models": { "default": "anthropic/claude-3.5-sonnet" }
    },
    "onnx": {
      "modelPath": "./models/phi-4/.../model.onnx",
      "executionProviders": ["cpu"],
      "localInference": true
    }
  }
}

OpenRouter Integration (99% Cost Savings)

Access 100+ LLM models through OpenRouter for dramatic cost savings while maintaining full functionality:

# Set OpenRouter API key
export OPENROUTER_API_KEY=sk-or-v1-...

# Use any OpenRouter model (proxy auto-starts)
npx agentic-flow \
  --agent coder \
  --task "Build REST API" \
  --model "meta-llama/llama-3.1-8b-instruct"

# Or force OpenRouter mode
export USE_OPENROUTER=true
npx agentic-flow --agent coder --task "Build REST API"

Popular OpenRouter Models:

meta-llama/llama-3.1-8b-instruct - 99% cost savings, excellent coding
deepseek/deepseek-chat-v3.1 - Superior code generation at 97% savings
google/gemini-2.5-flash-preview-09-2025 - Fastest responses, 95% savings
anthropic/claude-3.5-sonnet - Full Claude via OpenRouter

Cost Comparison:

Provider	Model	Input (1K tokens)	Output (1K tokens)	Savings
Anthropic Direct	Claude 3.5 Sonnet	$0.003	$0.015	Baseline
OpenRouter	Llama 3.1 8B	$0.00003	$0.00006	99%
OpenRouter	DeepSeek V3.1	$0.00014	$0.00028	97%
OpenRouter	Gemini 2.5 Flash	$0.000075	$0.0003	95%

How It Works:

Detects OpenRouter model (contains "/") or USE_OPENROUTER=true
Auto-starts integrated proxy server on port 3000
Translates Anthropic Messages API ↔ OpenAI Chat Completions API
Claude Agent SDK transparently uses OpenRouter via ANTHROPIC_BASE_URL
Full MCP tool support (all 203 tools work)

Environment Variables:

# Required for OpenRouter
export OPENROUTER_API_KEY=sk-or-v1-...

# Optional configuration
export USE_OPENROUTER=true              # Force OpenRouter usage
export COMPLETION_MODEL=meta-llama/...  # Default OpenRouter model
export PROXY_PORT=3000                  # Proxy server port

Google Gemini Integration (Speed & Cost Optimization)

Access Google's Gemini models for fast, cost-effective inference with native integration:

# Set Gemini API key
export GOOGLE_GEMINI_API_KEY=xxxxx

# Use Gemini directly (no proxy needed)
npx agentic-flow \
  --agent coder \
  --task "Build REST API" \
  --provider gemini \
  --model "gemini-2.0-flash-exp"

# Or force Gemini mode
export USE_GEMINI=true
npx agentic-flow --agent researcher --task "Analyze trends"

Available Gemini Models:

gemini-2.0-flash-exp - Experimental, fast responses, free up to rate limits
gemini-2.5-flash - Production-ready, 95% cost savings vs Claude
gemini-2.5-pro - Premium quality with competitive pricing

Cost Comparison (Gemini vs Others):

Provider	Model	Input (1M tokens)	Output (1M tokens)	Savings vs Claude
Anthropic	Claude Sonnet 4.5	$3.00	$15.00	Baseline
Google	Gemini 2.0 Flash Exp	FREE	FREE	100% (up to limits)
Google	Gemini 2.5 Flash	$0.075	$0.30	98%
Google	Gemini 2.5 Pro	$1.25	$5.00	70%

Performance Characteristics:

Latency: Gemini 2.5 Flash is fastest (avg 1.5s for 500 tokens)
Quality: Gemini 2.5 Pro comparable to Claude Sonnet 3.5
Streaming: Full support for real-time output
MCP Tools: All 213 tools work seamlessly

How It Works:

Detects --provider gemini or GOOGLE_GEMINI_API_KEY environment variable
Uses native Gemini API (no proxy needed, unlike OpenRouter)
Automatic message format conversion (Anthropic → Gemini)
Full MCP tool support (all 213 tools work)
Cost tracking and usage metrics built-in

Environment Variables:

# Required for Gemini
export GOOGLE_GEMINI_API_KEY=xxxxx

# Optional configuration
export USE_GEMINI=true          # Force Gemini usage
export PROVIDER=gemini          # Set default provider

Use Cases Where Gemini Excels:

✅ Speed-critical tasks - Fastest inference of all cloud providers
✅ Prototyping - Free tier excellent for development
✅ High-volume workloads - 98% cost savings at scale
✅ Real-time applications - Low latency streaming responses
✅ Cost-conscious production - Balance quality and price

Programmatic Usage:

import { ModelRouter } from 'agentic-flow/router';

const router = new ModelRouter();

// Direct Gemini usage
const response = await router.chat({
  model: 'gemini-2.5-flash',
  messages: [{ role: 'user', content: 'Analyze this code...' }],
  temperature: 0.7,
  maxTokens: 2048
});

console.log(response.content[0].text);
console.log(`Provider: ${response.metadata.provider}`);  // "gemini"
console.log(`Cost: $${response.metadata.cost}`);         // ~$0.0003 per request
console.log(`Latency: ${response.metadata.latency}ms`);  // ~1200ms avg

Free ONNX Local Inference

Run agents with zero API costs using local ONNX models:

// CPU Inference (6 tokens/sec, 100% free)
const router = new ModelRouter();
const onnxProvider = router.providers.get('onnx');

const response = await onnxProvider.chat({
  model: 'phi-4',
  messages: [{ role: 'user', content: 'Analyze this sensitive data...' }],
  maxTokens: 100
});

console.log(response.content[0].text);
console.log(`Cost: $${response.metadata.cost}`);  // $0.00
console.log(`Latency: ${response.metadata.latency}ms`);
console.log(`Privacy: 100% local processing`);

Privacy-Based Routing

Automatically route privacy-sensitive workloads to free local ONNX inference:

// Configure privacy routing in router.config.json
{
  "routing": {
    "mode": "rule-based",
    "rules": [
      {
        "condition": { "privacy": "high", "localOnly": true },
        "action": { "provider": "onnx" },
        "reason": "Privacy-sensitive tasks use free ONNX local models"
      }
    ]
  }
}

// Router automatically uses ONNX for privacy workloads
const response = await router.chat({
  model: 'any-model',
  messages: [{ role: 'user', content: 'Process medical records...' }],
  metadata: { privacy: 'high', localOnly: true }
});

// Routed to ONNX automatically (zero cost, 100% local)
console.log(response.metadata.provider);  // "onnx-local"

GPU Acceleration

Enable GPU acceleration for 10-50x performance boost:

// router.config.json
{
  "providers": {
    "onnx": {
      "executionProviders": ["cuda"],  // or ["dml"] for Windows
      "gpuAcceleration": true,
      "modelPath": "./models/phi-4/...",
      "maxTokens": 100
    }
  }
}

Performance Comparison:

CPU: 6 tokens/sec (free)
GPU (CUDA): 60-300 tokens/sec (free)
Cloud API: Variable (costs $0.002-0.003/request)

Zero-Cost Agent Execution

Run agents entirely offline with local ONNX models:

# Use ONNX provider for free inference
npx agentic-flow \
  --agent researcher \
  --task "Analyze this privacy-sensitive data" \
  --provider onnx \
  --local-only

# Result: $0.00 cost, 100% local processing

Cost Comparison

Workload Type	Provider	Cost per Request	Privacy	Performance
Privacy-Sensitive	ONNX (CPU)	$0.00	100% local	6 tokens/sec
Privacy-Sensitive	ONNX (GPU)	$0.00	100% local	60-300 tokens/sec
Complex Reasoning	Anthropic Claude	$0.003	Cloud	Fast
General Tasks	OpenRouter	$0.002	Cloud	Variable

Example Monthly Costs (1000 requests/day):

100% ONNX: $0 (free local inference)
50% ONNX, 50% cloud: $30-45 (50% savings)
100% cloud APIs: $60-90

🔧 MCP Tools (213 Total)

Agentic Flow integrates with four MCP servers providing 213 tools total:

Direct MCP Access

You can now directly manage MCP servers via the CLI:

# Start all MCP servers
npx agentic-flow mcp start

# List all 213 available tools
npx agentic-flow mcp list

# Check server status
npx agentic-flow mcp status

# Start specific server
npx agentic-flow mcp start claude-flow

How It Works:

Automatic (Recommended): Agents automatically access all 213 tools when you run tasks
Manual: Use npx agentic-flow mcp <command> for direct server management
Integrated: All tools work seamlessly whether accessed automatically or manually

Tool Breakdown

Core Orchestration (claude-flow - 101 tools)

Category	Tools	Capabilities
Swarm Management	12	Initialize, spawn, coordinate multi-agent swarms
Memory & Storage	10	Persistent memory with TTL and namespaces
Neural Networks	12	Training, inference, WASM-accelerated computation
GitHub Integration	8	PR management, code review, repository analysis
Performance	11	Metrics, bottleneck detection, optimization
Workflow Automation	9	Task orchestration, CI/CD integration
Dynamic Agents	7	Runtime agent creation and coordination
System Utilities	8	Health checks, diagnostics, feature detection

Cloud Platform (flow-nexus - 96 tools)

Category	Tools	Capabilities
☁️ E2B Sandboxes	12	Isolated execution environments (Node, Python, React)
☁️ Distributed Swarms	8	Cloud-based multi-agent deployment
☁️ Neural Training	10	Distributed model training clusters
☁️ Workflows	9	Event-driven automation with message queues
☁️ Templates	8	Pre-built project templates and marketplace
☁️ Challenges	6	Coding challenges with leaderboards
☁️ User Management	7	Authentication, profiles, credit management
☁️ Storage	5	Cloud file storage with real-time sync

Payment Authorization (agentic-payments - MCP tools)

Multi-agent payment infrastructure for autonomous AI commerce:

Category	Tools	Capabilities
💳 Active Mandates	MCP	Create spending limits, time windows, merchant restrictions
🔐 Ed25519 Signatures	MCP	Cryptographic transaction signing (<1ms verification)
🤝 Multi-Agent Consensus	MCP	Byzantine fault-tolerant transaction approval
📊 Payment Tracking	MCP	Authorization to settlement lifecycle monitoring
🛡️ Security	MCP	Spend caps, revocation, audit trails

Use Cases:

E-commerce: AI shopping agents with weekly budgets
Finance: Robo-advisors executing trades within portfolios
Enterprise: Multi-agent procurement with consensus approval
Accounting: Automated AP/AR with policy-based workflows

Protocols:

AP2: Agent Payments Protocol with Ed25519 signatures
ACP: Agentic Commerce Protocol (Stripe-compatible)
MCP: Natural language interface for AI assistants

In-Process Tools (claude-flow-sdk - 6 tools)

Fast, zero-latency tools running in-process:

memory_store, memory_retrieve, memory_list
swarm_init, agent_spawn, coordination_sync

⚡ FastMCP Integration (New)

Agentic Flow now supports FastMCP, a modern TypeScript framework for building high-performance MCP servers with:

Dual Transport: stdio (local/subprocess) + HTTP streaming (cloud/network)
Type Safety: Full TypeScript + Zod schema validation
Progress Reporting: Real-time execution feedback
Authentication: JWT, API keys, OAuth 2.0 support
Rate Limiting: Built-in abuse prevention

POC Server (Phase 0 - Completed ✅)

Basic stdio server with 2 tools to validate fastmcp integration:

# Test the POC server
npm run test:fastmcp

# Or run directly
npm run mcp:fastmcp-poc

Using with Claude Code

Add to your MCP config (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "fastmcp-poc": {
      "command": "node",
      "args": ["/path/to/agentic-flow/dist/mcp/fastmcp/servers/poc-stdio.js"]
    }
  }
}

Available FastMCP Tools (POC)

Tool	Description	Status
`memory_store`	Store value in persistent memory	✅ Working
`memory_retrieve`	Retrieve value from memory	✅ Working

Coming Soon (Phase 1):

Migration of 6 claude-flow-sdk tools to fastmcp
HTTP streaming transport with authentication
Direct in-process execution (no execSync)
Comprehensive test suite

Documentation:

FastMCP Implementation Plan - 10-week migration strategy
FastMCP POC Integration - Usage and testing guide

🔍 Deployment Comparison

Feature	Local	Docker	Flow Nexus Sandboxes	ONNX Local
MCP Tools Available	203 (100%)	203 (100%)	203 (100%)	6 (3%)
Setup Complexity	Low	Medium	Medium	Low
Cold Start Time	<500ms	<2s	<2s	~2s (first load)
Cost (Development)	Free*	Free*	$1/hour	$0 (100% free)
Cost (Production)	Free*	Infra costs	$1/hour	$0 (100% free)
Privacy	Local	Local	Cloud	100% Offline
Scaling	Manual	Orchestrator	Automatic	Manual
Best For	Dev/Testing	CI/CD/Prod	Cloud-Scale	Privacy/Offline

*Free infrastructure, Claude API costs only

📦 Advanced Deployment Patterns

☁️ Flow Nexus Cloud Sandboxes (Scalable Production)

Best for cloud-native, auto-scaling workloads:

// Full-featured agent execution in isolated E2B sandboxes
import { flowNexus } from 'flow-nexus';

// Setup: One-time authentication
await flowNexus.login({
  email: process.env.FLOW_NEXUS_EMAIL,
  password: process.env.FLOW_NEXUS_PASSWORD
});

// Deploy: Create sandbox and execute
async function deployAgent(task) {
  // 1. Create isolated sandbox
  const sandbox = await flowNexus.sandboxCreate({
    template: 'node', // or 'python', 'react', 'nextjs'
    name: `agent-${Date.now()}`,
    env_vars: {
      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY
    },
    install_packages: ['@anthropic-ai/claude-agent-sdk'],
    timeout: 3600 // 1 hour max
  });

  // 2. Execute agent with ALL 203 MCP tools
  const result = await flowNexus.sandboxExecute({
    sandbox_id: sandbox.id,
    code: `
      const { query } = require('@anthropic-ai/claude-agent-sdk');
      const result = await query({
        prompt: "${task}",
        options: {
          permissionMode: 'bypassPermissions',
          mcpServers: {
            'claude-flow-sdk': /* 6 tools */,
            'claude-flow': /* 101 tools */,
            'flow-nexus': /* 96 tools */
          }
        }
      });
      console.log(JSON.stringify(result));
    `,
    language: 'javascript',
    capture_output: true
  });

  // 3. Cleanup (automatic after timeout)
  await flowNexus.sandboxDelete({ sandbox_id: sandbox.id });

  return result;
}

Why Flow Nexus is Recommended:

✅ Full MCP Support: All 203 tools work (subprocess servers supported)
✅ Persistent Memory: Claude Flow memory persists across sandboxes
✅ Security: Complete process isolation per sandbox
✅ Multi-Language: Node.js, Python, React, Next.js templates
✅ Real-Time: Live output streaming and monitoring
✅ Cost-Effective: Pay per use (10 credits/hour ≈ $1/hour)

Flow Nexus Pricing:

Resource	Cost	Notes
Sandbox (hourly)	10 credits	≈ $1/hour per sandbox
Storage	1 credit/GB/month	Files and environment data
Credits Package	$10 = 100 credits	10+ hours of sandbox time

🐳 Container Platforms (Production Orchestration)

Docker (ECS, Cloud Run, Fargate, Kubernetes)

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
CMD ["npm", "start", "--", "--agent", "${AGENT}", "--task", "${TASK}"]

Best Practices:

Use multi-stage builds for smaller images
Enable health checks for orchestrators
Set resource limits (CPU/memory)
All 203 MCP tools available (subprocess servers work)
Use secrets managers for API keys

Kubernetes

apiVersion: batch/v1
kind: Job
metadata:
  name: agentic-flow-job
spec:
  template:
    spec:
      containers:
      - name: agent
        image: agentic-flow:latest
        args: ["--agent", "researcher", "--task", "$(TASK)"]
        env:
        - name: ANTHROPIC_API_KEY
          valueFrom:
            secretKeyRef:
              name: anthropic-secret
              key: api-key
      restartPolicy: Never

Best Practices:

Use Jobs for ephemeral executions
Set activeDeadlineSeconds for timeouts
Use node selectors for cost optimization
Implement PodDisruptionBudgets
All 203 MCP tools available

💡 ONNX Local Inference - Extended Configuration

Advanced ONNX setup with router integration:

// router.config.json - Auto-route privacy tasks to ONNX
{
  "routing": {
    "rules": [
      {
        "condition": { "privacy": "high", "localOnly": true },
        "action": { "provider": "onnx" }
      },
      {
        "condition": { "cost": "free" },
        "action": { "provider": "onnx" }
      }
    ]
  },
  "providers": {
    "onnx": {
      "modelPath": "./models/phi-4/model.onnx",
      "maxTokens": 2048,
      "temperature": 0.7
    }
  }
}

Performance Benchmarks:

Metric	CPU (Intel i7)	GPU (NVIDIA RTX 3060)
Tokens/sec	~6	60-300
First Token	~2s	~500ms
Model Load	~3s	~2s
Memory Usage	~2GB	~3GB
Cost	$0	$0

Use Cases:

✅ Privacy-sensitive data processing
✅ Offline/air-gapped environments
✅ Cost-conscious development
✅ Compliance requirements (HIPAA, GDPR)
✅ Prototype/testing without API costs

Documentation:

ONNX Integration Guide
ONNX CLI Usage
ONNX vs Claude Quality Analysis const sandbox = await flowNexus.sandboxCreate({ template: 'node', env_vars: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY } });

const result = await flowNexus.sandboxExecute({ sandbox_id: sandbox.id, code: /* Full agent code with all 203 tools */ });

await flowNexus.sandboxDelete({ sandbox_id: sandbox.id });

return { statusCode: 200, body: JSON.stringify(result) }; };


---

## 📊 Architecture

### Ephemeral Agent Lifecycle

REQUEST → Agent definition loaded from YAML
SPAWN → Agent initialized with system prompt + tools
EXECUTE → Task processed using Claude SDK + MCP tools
STREAM → Real-time output (optional)
COMPLETE → Result returned to caller
TERMINATE → Agent process exits, memory released


**Key Characteristics:**
- **Cold Start**: <2s (includes MCP server initialization)
- **Warm Start**: <500ms (MCP servers cached)
- **Memory Usage**: 100-200MB per agent
- **Concurrent Agents**: Limited only by host resources

### Multi-Agent Coordination

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Researcher │────▶│ Memory │◀────│ Code Review │ │ Agent │ │ Storage │ │ Agent │ └─────────────┘ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────┐ │ Data │ │ Analyst │ └─────────────┘


**Coordination via:**
- Shared memory (in-process or external)
- Claude Flow MCP tools
- File system (for batch jobs)
- Message queues (for async workflows)

---

## 🔍 Advanced Usage

### Custom Agent Definition

Create `.claude/agents/custom/my-agent.md`:

```markdown
---
name: my-agent
description: Custom agent for specific tasks
---

# System Prompt

You are a specialized agent for [your use case].

## Capabilities
- [List capabilities]

## Guidelines
- [Execution guidelines]

Programmatic API

import { query } from '@anthropic-ai/claude-agent-sdk';
import { getAgent } from 'agentic-flow/utils';

const agent = getAgent('researcher');
const result = await query({
  prompt: 'Analyze AI trends',
  options: {
    systemPrompt: agent.systemPrompt,
    permissionMode: 'bypassPermissions'
  }
});

console.log(result.output);

Flow Nexus Integration

Requires registration for cloud features:

# Register account
npx agentic-flow --agent flow-nexus-auth \
  --task "Register with email: user@example.com"

# Login
npx agentic-flow --agent flow-nexus-auth \
  --task "Login with email: user@example.com, password: ***"

# Create cloud sandbox
npx agentic-flow --agent flow-nexus-sandbox \
  --task "Create Node.js sandbox and execute: console.log('Hello')"

📈 Performance & Scaling

Benchmarks

Metric	Result
Cold Start	<2s (including MCP initialization)
Warm Start	<500ms (cached MCP servers)
Agent Spawn	75 agents loaded in <2s
Tool Discovery	203 tools accessible in <1s
Memory Footprint	100-200MB per agent process
Concurrent Agents	10+ on t3.small, 100+ on c6a.xlarge
Token Efficiency	32% reduction via swarm coordination

Cost Analysis - ONNX vs Cloud APIs

Provider	Model	Tokens/sec	Cost per 1M tokens	Monthly (100K tasks)
ONNX Local	Phi-4	6-300	$0	$0
OpenRouter	Llama 3.1 8B	API	$0.06	$6
OpenRouter	DeepSeek	API	$0.14	$14
Claude	Sonnet 3.5	API	$3.00	$300

ONNX Savings: Up to $3,600/year for typical development workloads

🛠️ Development

Build from Source

# Clone repository
git clone https://github.com/ruvnet/agentic-flow.git
cd agentic-flow

# Install dependencies
npm install

# Build TypeScript
npm run build

# Test locally
node dist/cli.js --help

Testing

# Run all tests
npm test

# Test specific agent
node dist/cli.js --agent researcher --task "Test task"

# Validate MCP tools
npm run validate

Adding Custom Agents

Create agent definition: .claude/agents/custom/my-agent.md
Define system prompt and capabilities
Test: npx agentic-flow --agent my-agent --task "Test"
Deploy: npm run build && docker build -t my-agents .

🔗 Links

Documentation: docs/
GitHub: github.com/ruvnet/agentic-flow
npm Package: npmjs.com/package/agentic-flow
Claude Agent SDK: docs.claude.com/en/api/agent-sdk
Flow Nexus Platform: github.com/ruvnet/flow-nexus

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Make changes and add tests
Ensure tests pass: npm test
Commit: git commit -m "feat: add amazing feature"
Push: git push origin feature/amazing-feature
Open Pull Request

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with:

Claude Agent SDK by Anthropic
Claude Flow - 101 MCP tools
Flow Nexus - 96 cloud tools
Model Context Protocol by Anthropic

💬 Support

Documentation: See docs/ folder
Issues: GitHub Issues
Discussions: GitHub Discussions

Deploy ephemeral AI agents in seconds. Scale to thousands. Pay only for what you use. 🚀

npx agentic-flow --agent researcher --task "Your task here"

Name		Name	Last commit message	Last commit date
Latest commit History 224 Commits
.claude		.claude
agent-booster		agent-booster
agentic-flow		agentic-flow
agentic-llm		agentic-llm
docker		docker
examples		examples
open-lovable		open-lovable
releases		releases
scripts		scripts
.gitignore		.gitignore
README.md		README.md
docs		docs

ruvnet/agentic-flow

Folders and files

Latest commit

History

Repository files navigation

🤖 Agentic Flow

Why Agentic Flow?

Built on Industry Standards

🚀 Quick Start

Local Installation (Recommended for Development)

Your First Agent (Local Execution)

Multi-Agent Swarm (Local)

Docker Deployment (Production)

✨ Key Features

🔄 Ephemeral Architecture

🤖 Multi-Model Router with ONNX Local Inference

💻 Local Development (Full Features)

🐳 Container Deployment (Production Ready)

☁️ Cloud Sandboxes (Scalable Execution)

🤖 Intelligent Agents

📊 Observability

🚀 Deployment Options

💻 Local Execution (Best for Development)

🎯 Flow Nexus Cloud Sandboxes (Best for Production Scale)

🐳 Docker Containers (Best for Production Deployments)

🔓 ONNX Local Inference (Free Offline AI)

🎯 Use Cases & Costs

🤖 Agent Types

Core Development Agents

Specialized Agents

Swarm Coordinators

GitHub Integration

Performance & Analysis

🎯 Model Optimization (NEW!)

Why Model Optimization?

Quick Examples

Optimization Priorities

Model Tier Examples

Agent-Specific Recommendations

Cost Savings Examples

Comprehensive Model Guide

MCP Tool for Optimization

📋 Commands

MCP Server Management (Direct Tool Access)

Add Custom MCP Servers (No Code Required) ✨ NEW in v1.2.1

Basic Operations (Works Locally, Docker, Cloud)

Environment Configuration

Docker Deployment

🎛️ Using the Multi-Model Router

Quick Start with Router

Available Providers

OpenRouter Integration (99% Cost Savings)

Google Gemini Integration (Speed & Cost Optimization)

Free ONNX Local Inference

Privacy-Based Routing

GPU Acceleration

Zero-Cost Agent Execution

Cost Comparison

🔧 MCP Tools (213 Total)

Direct MCP Access

Tool Breakdown

Core Orchestration (claude-flow - 101 tools)

Cloud Platform (flow-nexus - 96 tools)

Payment Authorization (agentic-payments - MCP tools)

In-Process Tools (claude-flow-sdk - 6 tools)

⚡ FastMCP Integration (New)

POC Server (Phase 0 - Completed ✅)

Using with Claude Code

Available FastMCP Tools (POC)

🔍 Deployment Comparison

📦 Advanced Deployment Patterns

☁️ Flow Nexus Cloud Sandboxes (Scalable Production)

🐳 Container Platforms (Production Orchestration)

Docker (ECS, Cloud Run, Fargate, Kubernetes)

Kubernetes

💡 ONNX Local Inference - Extended Configuration

Programmatic API

Flow Nexus Integration

📈 Performance & Scaling

Benchmarks

Packages