Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (flow-nexus) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🚀 Flow Nexus - AI Agent Ecosystem & Gamified Development Platform

🌐 fnx.ruv.io

Deploy AI Swarms • Complete Challenges • Earn Credits • Build Faster

npx flow-nexus

✨ Free Start • 🎮 Gamified Experience • 🚀 Instant Deploy

🎯 Transform How You Build Software

Flow Nexus is your AI-powered development platform with 70+ MCP tools. Deploy swarms of specialized agents, complete coding challenges, and earn rUv credits while building real applications.

Why Developers Choose Flow Nexus

🚀 70+ MCP Tools	🎮 Earn While Building	🤖 AI Swarms	💰 Free Credits
Complete toolset for AI development	Gamified challenges & rewards	Multi-agent orchestration	2560 credits to start

⚡ Start in 60 Seconds

# 1. Initialize Flow Nexus (interactive setup)
npx flow-nexus init

# 2. Choose your setup:
#    → Select a template (Basic, Advanced, Enterprise)
#    → Create account or login
#    → Get your free rUv credits

# 3. Jump into challenges (earn rUv instantly!)
npx flow-nexus challenge

# 3. Select operation mode:
#    → 🎮 Gamer Mode - Challenges & tournaments
#    → 🛍️ Store Mode - Browse & deploy apps
#    → 🤖 Swarm Mode - Orchestrate AI agents
#    → 🛠️ MCP Mode - Direct tool access
#    → 👑 Queen Seraphina - AI mentor

🎁 New User Bonus: 2560 free rUv credits to start!

🛠️ Real Commands That Work

Authentication & Setup

# Register new account
npx flow-nexus auth register -e pilot@ruv.io -p your-password

# Login to existing account
npx flow-nexus auth login -e pilot@ruv.io -p your-password

# Initialize local config
npx flow-nexus auth init

# Check authentication status
npx flow-nexus auth status

MCP Server Modes

# Run as MCP server (for Claude Desktop)
npx flow-nexus mcp
# Note: MCP server runs silently waiting for Claude Desktop
# It won't show output unless there's an error

# Test if MCP server is working
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | npx flow-nexus mcp
# Should return: {"result":{"protocolVersion":"..."},"jsonrpc":"2.0","id":1}

# Start with specific mode
npx flow-nexus start swarm      # Swarm orchestration tools
npx flow-nexus start store      # App store & gamification
npx flow-nexus start gamer      # Challenges & achievements
npx flow-nexus start dev        # Development tools
npx flow-nexus start complete   # All 70+ tools (default)

# Start with HTTP server
npx flow-nexus start --http-port 3000

Interactive CLI Commands

# Main interactive menu
npx flow-nexus

# Swarm management
npx flow-nexus swarm

# Browse challenges
npx flow-nexus challenge

# Manage sandboxes
npx flow-nexus sandbox

# Check credit balance
npx flow-nexus credits

# View templates
npx flow-nexus template

# Browse app store
npx flow-nexus store

# View profile & stats
npx flow-nexus profile

# Check achievements
npx flow-nexus achievements

# View leaderboard
npx flow-nexus leaderboard

# Deploy distributed neural network (NEW)
npx flow-nexus neural deploy --topology mesh --nodes 4

💰 Credit System & Pricing

How Credits Work

Every MCP tool operation costs rUv credits. Here are the actual costs from the system:

Operation	Cost	Description
swarm_init	3 rUv	Initialize a new swarm
agent_spawn	2 rUv/agent	Create specialized agents
sandbox_create	1 rUv	Deploy cloud sandbox
task_orchestrate	5 rUv	Complex task coordination
template_deploy	1-8 rUv	Deploy app templates
challenge_submit	0 rUv	FREE - Submit solutions

Earn Credits

Activity	Reward	How To
Register	100 rUv	Sign up for free account
Complete Challenge	10-50 rUv	`npx flow-nexus challenge`
Publish App	25 rUv	Share your creations
5-Star Rating	50 rUv	Get high ratings on apps

Credit Packages

# Check your balance
npx flow-nexus credits balance

# View pricing tiers
npx flow-nexus credits pricing

🤖 77+ MCP Tools Available

Core Swarm Tools

// Initialize swarm
mcp__flow-nexus-npm__swarm_init
  - topology: "mesh" | "star" | "ring" | "hierarchical"
  - maxAgents: 1-100
  - strategy: "balanced" | "specialized" | "adaptive"

// Spawn agents
mcp__flow-nexus-npm__agent_spawn
  - type: "researcher" | "coder" | "analyst" | "optimizer" | "coordinator"
  - capabilities: ["custom", "skills"]

// Orchestrate tasks
mcp__flow-nexus-npm__task_orchestrate
  - task: "Your task description"
  - strategy: "parallel" | "sequential" | "adaptive"

Sandbox Tools

// Create sandbox
mcp__flow-nexus-npm__sandbox_create
  - template: "node" | "python" | "react" | "nextjs" | "claude-code"
  - env_vars: { ANTHROPIC_API_KEY: "..." }
  
// Execute code
mcp__flow-nexus-npm__sandbox_execute
  - sandbox_id: "sandbox-id"
  - code: "your code"
  - language: "javascript" | "python"

🧠 Distributed Neural Network Tools (NEW v0.1.38)

Deploy and manage distributed neural networks across E2B sandboxes with DAA-WASM acceleration:

// Initialize a distributed neural cluster
mcp__flow-nexus-npm__neural_cluster_init
  - name: "my-neural-cluster"
  - topology: "mesh" | "ring" | "star" | "hierarchical"
  - architecture: "transformer" | "cnn" | "rnn" | "gnn" | "hybrid"
  - wasmOptimization: true  // 3.2x performance boost
  - daaEnabled: true  // Autonomous coordination
  - consensus: "proof-of-learning" | "byzantine" | "raft" | "gossip"

// Deploy neural nodes in sandboxes
mcp__flow-nexus-npm__neural_node_deploy
  - cluster_id: "cluster-abc-123"
  - role: "worker" | "parameter_server" | "aggregator" | "validator"
  - model: "base" | "large" | "xl" | "custom"
  - capabilities: ["training", "inference"]
  - autonomy: 0.8  // DAA autonomy level (0-1)

// Connect nodes with network topology
mcp__flow-nexus-npm__neural_cluster_connect
  - cluster_id: "cluster-abc-123"
  - topology: "mesh"  // Override default if needed

// Start distributed training
mcp__flow-nexus-npm__neural_train_distributed
  - cluster_id: "cluster-abc-123"
  - dataset: '{"data": [[1,2], [3,4]], "labels": [0, 1]}'
  - epochs: 10
  - batch_size: 32
  - learning_rate: 0.001
  - federated: true  // Enable federated learning

// Monitor cluster and training status
mcp__flow-nexus-npm__neural_cluster_status
  - cluster_id: "cluster-abc-123"

// Run distributed inference
mcp__flow-nexus-npm__neural_predict_distributed
  - cluster_id: "cluster-abc-123"
  - input_data: '{"features": [1, 2, 3]}'
  - aggregation: "ensemble" | "mean" | "majority" | "weighted"

// Cleanup cluster and sandboxes
mcp__flow-nexus-npm__neural_cluster_terminate
  - cluster_id: "cluster-abc-123"

Key Features:

🚀 3.2x Performance with WASM acceleration
🤖 DAA Integration for autonomous agent coordination
🔒 Byzantine-Resistant consensus mechanisms
📊 Federated Learning for privacy-preserving ML
🌐 Multiple Topologies for different use cases
💾 Persistent State via Supabase MCP
👑 Queen Seraphina has full access to these capabilities

Gamification Tools

// List challenges
mcp__flow-nexus-npm__challenges_list
  - difficulty: "beginner" | "intermediate" | "advanced"
  
// Submit solution
mcp__flow-nexus-npm__challenge_submit
  - challenge_id: "challenge-id"
  - solution_code: "your solution"
  
// Check leaderboard
mcp__flow-nexus-npm__leaderboard_get
  - type: "global" | "weekly" | "monthly"

App Store Tools

// Browse templates
mcp__flow-nexus-npm__template_list
  - category: "quickstart" | "specialized" | "enterprise"
  
// Deploy template
mcp__flow-nexus-npm__template_deploy
  - template_name: "nextjs-saas"
  - variables: { project_name: "my-app" }
  
// Publish app
mcp__flow-nexus-npm__app_store_publish_app
  - name: "Your App"
  - category: "productivity"
  - source_code: "..."

Queen Seraphina AI

CLI Usage:

# Chat with default model (standard: 4 rUv)
npx flow-nexus seraphina "How do I create a swarm?"

# Select specific AI model
npx flow-nexus seraphina -m basic "Quick question"     # Haiku (2 rUv)
npx flow-nexus seraphina -m standard "Help me"         # Sonnet (4 rUv)
npx flow-nexus seraphina -m premium "Complex task"     # Opus (20 rUv)
npx flow-nexus seraphina -m advanced "Long analysis"   # Sonnet+ (8 rUv)

# Enable tool execution
npx flow-nexus seraphina --tools "Deploy a test"

# List models and pricing
npx flow-nexus seraphina --list-models

Model Tiers & Pricing (100% markup on all models):

Model	Name	Cost	Description
🟢 basic	Haiku	2 rUv	Fast responses for simple queries
🔵 standard	Sonnet	4 rUv	Balanced performance (default)
🟣 premium	Opus	20 rUv	Maximum intelligence
🟡 advanced	Sonnet+	8 rUv	Extended context

MCP Usage:

// Chat with AI mentor
mcp__flow-nexus-npm__seraphina_chat
  - message: "How do I deploy to AWS?"
  - enable_tools: true  // Let her execute commands
  - model_tier: "standard"  // Optional: basic, standard, premium, advanced

Configuration:

# Set default model in .env
SERAPHINA_DEFAULT_MODEL=standard

👑 Queen Seraphina Automated Judge System

How Challenge Judging Works

When you submit a challenge solution, Queen Seraphina's AI Judge System automatically:

🚀 Executes Your Code - Runs in secure E2B sandbox environment
✅ Validates Tests - Checks if your solution passes all test cases
⚡ Measures Performance - Times execution speed and memory usage
📊 Calculates Score - Weighted evaluation across multiple criteria
🏆 Determines Winners - Ranks all submissions automatically
💰 Awards Credits - Distributes rUv rewards based on performance

Scoring Criteria

Coding Challenges (REST APIs, Algorithms)

Criteria	Weight	What's Evaluated
Correctness	40%	Tests passed, expected output
Efficiency	20%	Execution time, memory usage
Code Quality	20%	Clean code, best practices
Innovation	20%	Creative solutions, clever approaches

Swarm Challenges (Multi-Agent Coordination)

Criteria	Weight	What's Evaluated
Coordination	30%	Agent teamwork effectiveness
Task Completion	30%	Success rate of objectives
Resource Usage	20%	Cost optimization
Scalability	20%	Architecture quality

Automatic Rewards

The Judge System automatically awards credits when challenges end:

Rank	Base Reward	Bonus	Total
🥇 1st Place	100 rUv	+50	150 rUv
🥈 2nd Place	75 rUv	+30	105 rUv
🥉 3rd Place	50 rUv	+20	70 rUv
Top 10	25 rUv	-	25 rUv
Score ≥ 70	10 rUv	-	10 rUv
Participation	5 rUv	-	5 rUv

Excellence Bonuses:

⚡ Fastest Execution: +20 rUv
🎯 Perfect Score (100): +25 rUv
💡 Most Innovative: +15 rUv

Submit to Challenges

# Browse available challenges
npx flow-nexus challenge

# Submit your solution
npx flow-nexus challenge submit

# Example submission flow:
1. Select challenge: "REST API with Swarm Integration"
2. Write your solution
3. Submit for judging
4. Queen Seraphina evaluates automatically
5. Receive score and ranking
6. Credits awarded instantly!

Real Example: Combat Training Challenge

// Alice's submission - Score: 85/100 - Rank: #3 - Won: 50 rUv
const express = require('express');
const app = express();
// Basic but functional API

// Bob's submission - Score: 88/100 - Rank: #2 - Won: 75 rUv  
import express from 'express';
import { z } from 'zod';
// Enhanced with validation

// Charlie's submission - Score: 92/100 - Rank: #1 - Won: 100 rUv 🏆
const express = require('express');
const { WebSocketServer } = require('ws');
// Production-ready with WebSocket support
// Fastest execution: 800ms

Check Leaderboards

# Global rankings
npx flow-nexus leaderboard

# Challenge-specific
npx flow-nexus leaderboard --challenge "combat_training"

# Your stats
npx flow-nexus stats

Tips for Winning

🎯 Correctness First - Make sure all tests pass (40% of score!)
⚡ Optimize Performance - Faster execution = higher efficiency score
📝 Write Clean Code - Queen Seraphina values readability
💡 Be Creative - Innovative solutions earn bonus points
🚀 Use Advanced Features - WebSockets, caching, error handling
📊 Monitor Resources - Efficient memory/CPU usage matters

Judge System Features

🔒 Secure Execution - Isolated E2B sandboxes for each submission
⚡ Real-Time Results - Instant feedback and scoring
📊 Detailed Analytics - See exactly how you scored in each area
🏆 Fair Competition - Consistent, unbiased AI evaluation
💰 Instant Rewards - Credits awarded automatically
📈 Progress Tracking - Watch your skills improve over time

🎮 Interactive Modes

npx flow-nexus

# You'll see:
╔════════════════════════════════════════╗
║     🚀 FLOW NEXUS MAIN MENU           ║
╠════════════════════════════════════════╣
║                                        ║
║  [1] 🎮 Gamer Mode                    ║
║  [2] 🛍️ Store Mode                    ║
║  [3] 🤖 Swarm Mode                    ║
║  [4] 🛠️ MCP Mode                      ║
║  [5] 👑 Queen Seraphina               ║
║                                        ║
╚════════════════════════════════════════╝

Gamer Mode Features

Daily challenges with rUv rewards
Weekly tournaments
Leaderboards
Achievement system
Skill progression

Store Mode Features

Browse app templates
Deploy with one command
Earn royalties from your apps
Rate and review apps
Featured collections

Swarm Mode Features

Visual swarm management
Real-time agent monitoring
Task orchestration
Performance metrics
Topology optimization

📦 Template Marketplace

Available Templates

Template	Cost	Description
SaaS Starter	1 rUv	Complete SaaS boilerplate
AI Chatbot	1 rUv	ChatGPT-like interface
E-Commerce	2 rUv	Full shopping platform
Admin Panel	1 rUv	Dashboard with analytics
Multi-Tenant	5 rUv	Enterprise SaaS platform
Marketplace	5 rUv	Two-sided marketplace
CRM System	8 rUv	Customer management

# List all templates
npx flow-nexus template

# Deploy a template
npx flow-nexus template deploy

🚀 MCP Integration with Claude Desktop

Setup for Claude Desktop

Install Flow Nexus globally OR use npx:

# Option 1: Install globally
npm install -g flow-nexus

# Option 2: Use npx (no install needed)
# Just configure Claude Desktop as shown below

Add to Claude Desktop config:

For macOS/Linux: Edit: ~/Library/Application Support/Claude/claude_desktop_config.json

For Windows: Edit: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "flow-nexus": {
      "command": "npx",
      "args": ["-y", "flow-nexus@latest", "mcp"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "NODE_PATH": "/usr/local/lib/node_modules"
      }
    }
  }
}

Alternative if you installed globally:

{
  "mcpServers": {
    "flow-nexus": {
      "command": "/usr/local/bin/flow-nexus",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop

Troubleshooting macOS Issues

If you get spawn flow-nexus ENOENT:

Find where npm installs global packages:

npm config get prefix
# Usually returns: /usr/local or ~/.npm-global

Find the exact path to flow-nexus:

which flow-nexus
# Should return something like: /usr/local/bin/flow-nexus

Use the full path in Claude config:

{
  "mcpServers": {
    "flow-nexus": {
      "command": "/full/path/to/flow-nexus",
      "args": ["mcp"]
    }
  }
}

Or use npx with -y flag (recommended):

{
  "mcpServers": {
    "flow-nexus": {
      "command": "npx",
      "args": ["-y", "flow-nexus@latest", "mcp"]
    }
  }
}

Available MCP Tools in Claude

Once configured, you can use all 70+ tools directly in Claude:

- swarm_init, agent_spawn, task_orchestrate
- sandbox_create, sandbox_execute, sandbox_list
- challenge_list, challenge_submit, leaderboard_get
- template_list, template_deploy, app_store_publish
- seraphina_chat (AI mentor)
- And 60+ more tools...

🎯 Common Workflows

Create and Deploy a Swarm

# Using MCP tools in Claude Desktop:
1. Initialize swarm: swarm_init with topology "mesh"
2. Spawn agents: agent_spawn type "coder", "tester", "reviewer"
3. Orchestrate task: task_orchestrate "Build REST API"
4. Monitor progress: swarm_status

Complete a Challenge

# Interactive CLI:
npx flow-nexus challenge

# Select a challenge, write solution, earn credits

Deploy a Template

# Browse available templates
npx flow-nexus template

# Deploy your choice
# Costs 1-8 rUv depending on template

📊 Your Progress & Stats

Check Your Profile

npx flow-nexus profile

# Shows:
- Developer level
- rUv credit balance
- Challenges completed
- Apps published
- Achievement badges
- Global ranking

View Achievements

npx flow-nexus achievements

# Unlock badges for:
- First swarm deployed
- 10 challenges completed
- App with 5-star rating
- 1000 rUv earned
- Top 10 leaderboard

🆘 Getting Help

Built-in Help

# General help
npx flow-nexus help

# Command-specific help
npx flow-nexus swarm --help
npx flow-nexus challenge --help

Queen Seraphina AI Assistant

# Ask the AI mentor anything
npx flow-nexus chat

# Or use in MCP:
seraphina_chat with message "How do I create a swarm?"

Common Issues

Not enough credits?

# Check balance
npx flow-nexus credits balance

# Complete daily challenge for free credits
npx flow-nexus challenge

MCP not working in Claude?

# Test MCP server
npx flow-nexus mcp

# Should show: "MCP server running on stdio transport"

Authentication issues?

# Check auth status
npx flow-nexus auth status

# Re-login if needed
npx flow-nexus auth login -e your@email.com -p password

🌟 Join the Community

Get Started Now

npx flow-nexus

One Command. Real Tools. Actual Results.

Resources

📚 Documentation: fnx.ruv.io
🐛 Issues: GitHub
📧 Support: support@flow-nexus.com

Built with ❤️ by rUv

flow-nexus