RuFloUI

A React 19 web dashboard for claude-flow v3 multi-agent orchestration. RuFloUI wraps the claude-flow CLI behind an Express + WebSocket backend and presents a full visual interface for managing swarms, agents, tasks, and workflows.

Features

• Swarm Management — Initialize, configure, and shut down multi-agent swarms with visual topology controls
• Agent Monitoring — Real-time agent status cards with live output streaming, status-colored indicators, and working animations
• Agent Visualization — Tree view of agent hierarchies built from JSONL session logs in real-time
• Task Board — Kanban-style task management with create, assign, execute, and continue workflows
• Task Continuation — Follow-up on completed/failed tasks with automatic context injection from previous results
• Output History — All task output persisted to disk and viewable across page reloads and server restarts
• Multi-Agent Pipeline — Coordinator plans subtasks, workers execute in dependency waves, results synthesized
• Hive Mind — Consensus protocols, broadcast messaging, and shared memory across agents with automatic cross-task knowledge sharing
• Workflows — Create and manage multi-step execution workflows
• Performance — Benchmarking, latency/throughput charts, bottleneck analysis
• Memory Store — Key-value memory with namespace support and semantic search
• Neural Network — Training, optimization, and pattern monitoring
• Sessions — Save and restore orchestration state
• Hooks — Event-driven hook configuration
• Configuration — Runtime config editor with import/export
• State Persistence — Full backend state persisted to .ruflo/ with debounced writes and crash recovery

Tech Stack

Layer	Technology
Frontend	React 19, Vite 6, TypeScript, Zustand, Recharts, Lucide Icons
Backend	Express, WebSocket (ws), Node.js
CLI	claude-flow v3 (@claude-flow/cli local binary)
AI	Claude Code CLI for multi-agent execution

Quick Start

# Clone the repository
git clone https://github.com/Mario-PB/rufloui.git
cd rufloui

# Install dependencies
npm install

# Start both frontend and backend
npm run dev

This starts: - Frontend (Vite) on http://localhost:28588 - Backend (Express + WebSocket) on http://localhost:28580

The frontend proxies /api/* and /ws to the backend automatically.

Install via npm

npm install rufloui

Install via GitHub Packages

# Configure npm to use GitHub Packages for the @mario-pb scope
echo "@mario-pb:registry=https://npm.pkg.github.com" >> .npmrc

# Install the package
npm install @mario-pb/rufloui

Note: GitHub Packages requires a personal access token with read:packages scope. Add it to your ~/.npmrc: //npm.pkg.github.com/:_authToken=YOUR_TOKEN

Individual Services

npm run dev:frontend   # Vite dev server on port 28588
npm run dev:backend    # Express API on port 28580 (auto-reloads)

Production Build

npm run build          # TypeScript check + Vite production build -> dist/
npm run preview        # Preview the production build

Project Structure

src/
├── backend/
│   ├── server.ts          # Express API + WebSocket + multi-agent pipeline
│   └── jsonl-monitor.ts   # Real-time JSONL session file monitoring
└── frontend/
    ├── main.tsx            # Entry point
    ├── App.tsx             # Router, WebSocket handler, data fetching
    ├── api.ts              # API client (typed fetch wrapper)
    ├── store.ts            # Zustand global state with sessionStorage persistence
    ├── types.ts            # TypeScript interfaces
    ├── styles/
    │   └── global.css      # CSS variables, dark theme, animations
    ├── components/
    │   ├── Layout.tsx       # App shell with sidebar navigation
    │   ├── ErrorBoundary.tsx
    │   └── ui/              # Button, Card, StatusBadge
    └── pages/
        ├── Dashboard.tsx        # System health, agent overview
        ├── SwarmPanel.tsx       # Swarm init/shutdown/config
        ├── SwarmMonitorPanel.tsx # Real-time agent cards with output
        ├── AgentsPanel.tsx      # Agent lifecycle management
        ├── AgentVizPanel.tsx    # JSONL-based agent tree visualization
        ├── TasksPanel.tsx       # Kanban task board with continuation
        ├── WorkflowsPanel.tsx   # Workflow management
        ├── HiveMindPanel.tsx    # Consensus and broadcast
        ├── MemoryPanel.tsx      # Key-value memory store
        ├── NeuralPanel.tsx      # Neural network status
        ├── PerformancePanel.tsx # Benchmarks and charts
        ├── SessionsPanel.tsx    # Save/restore sessions
        ├── HooksPanel.tsx       # Hook configuration
        ├── ConfigPanel.tsx      # Configuration editor
        └── LogsPanel.tsx        # Live activity logs

Architecture

Browser (React 19)                    Express Backend
┌────────────────────┐               ┌────────────────────────┐
│  Vite :28588       │───REST /api──>│  Express :28580        │
│  Zustand Store     │<──WebSocket──>│  WebSocket Server      │
│  sessionStorage    │               │                        │
└────────────────────┘               │  ┌──────────────────┐  │
                                     │  │ claude-flow CLI   │  │
                                     │  │ (npx @claude-flow │  │
                                     │  │  /cli@latest)     │  │
                                     │  └──────────────────┘  │
                                     │  ┌──────────────────┐  │
                                     │  │ Claude Code CLI   │  │
                                     │  │ (claude -p)       │  │
                                     │  │ Multi-agent pipe  │  │
                                     │  └──────────────────┘  │
                                     │  ┌──────────────────┐  │
                                     │  │ .ruflo/           │  │
                                     │  │  state.json       │  │
                                     │  │  outputs/*.jsonl  │  │
                                     │  └──────────────────┘  │
                                     └────────────────────────┘

Multi-Agent Pipeline

When a task is assigned to the swarm:

1. Planning Phase — Coordinator agent receives the task with --max-turns 1 (no tool access), outputs a JSON plan breaking work into subtasks
2. Execution Phase — Each subtask dispatched to the matching specialist agent (researcher, coder, tester, reviewer) with full tool access, respecting dependency order
3. Parallel Waves — Independent subtasks run in parallel; dependent ones wait for prerequisites
4. Hive Mind Memory — Each subtask result stored to shared memory; subsequent tasks receive accumulated knowledge as context
5. Completion — Results synthesized, task marked complete, output persisted to disk

Getting Started: Your First Swarm Task

Once the app is running, here's how to go from zero to a working multi-agent swarm in under a minute:

1. Initialize a swarm — Go to Swarm in the sidebar, pick a topology (e.g. mesh), and click Initialize Swarm.
2. Spawn agents — Go to Agents, select a type (e.g. coder), give it a name, and click Spawn. Repeat for other roles you need (researcher, tester, etc.).
3. Create a task — Go to Tasks, click Create Task, fill in a title and description (e.g. "Write a fibonacci function in Python with tests").
4. Assign to swarm — On the task card, click Assign to Swarm. The multi-agent pipeline kicks in: a coordinator plans subtasks, specialist agents execute them in parallel waves.
5. Watch it live — Switch to Swarm Monitor to see agent cards light up with real-time output and the orange working glow animation.
6. Continue if needed — When a task completes, click Continue Task to send a follow-up instruction with full context from the previous run.

Prerequisites

• Node.js >= 18
• claude-flow CLI — installed locally via npm install (included as dependency)
• Claude Code CLI (optional) — required for multi-agent pipeline execution. Install guide

Telegram Bot (Optional)

Monitor and control RuFloUI from Telegram.

Setup

Option A: Via the Dashboard (recommended)

1. Message @BotFather on Telegram, send /newbot, and follow the prompts to get a bot token.
2. Message your new bot with /start to get your chat ID.
3. Open the RuFloUI dashboard, go to Config > Telegram Bot.
4. Paste the bot token and chat ID, click Save & Connect.
5. Click Send Test to verify.

Option B: Via environment variables

TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHAT_ID=123456789

Restart the backend. You should see [telegram] Bot connected as @YourBotName in logs.

Commands

Command	Description
/start	Shows your chat ID (works for any user)
/status	System health + swarm status + agent/task counts
/agents	List active agents with type and status
/tasks	Tasks grouped by status (with inline refresh)
/task <id>	Detailed info for one task (with cancel button)
/workflows	List workflows with status and step count
/swarm	Swarm topology and status
/run <description>	Create and assign a task to the swarm
/cancel <id>	Cancel a running or pending task
/help	List available commands

Notifications

Configurable per-type via the dashboard (Config > Telegram Bot > Notifications):

Notification	Default	Description
Task Completed	On	Task finishes successfully
Task Failed	On	Task fails with error
Swarm Initialized	On	Swarm starts up
Swarm Shutdown	On	Swarm stops
Agent Error	On	Agent encounters an error
Task Progress	Off	Progress updates (throttled to 1 per 30s per task)

Security

• Only the configured chat ID can execute commands. Other users see their chat ID via /start but cannot issue commands.
• Bot token is stored in .ruflo/telegram.json with restricted file permissions (0600).
• The dashboard masks the token, showing only the last 4 characters.

Disabling

Set TELEGRAM_ENABLED=false (or remove it) and restart. The bot is completely inert when disabled.

GitHub Webhooks (Optional)

Automatically create swarm tasks when GitHub issues are opened.

Setup

1. Open the RuFloUI dashboard, go to Webhooks in the sidebar.
2. Click Edit, enable GitHub Webhooks, paste your GitHub token (needs repo scope).
3. Optionally add a webhook secret and list repos to monitor.
4. Copy the Webhook URL shown on the page.
5. In your GitHub repo, go to Settings > Webhooks > Add webhook.
6. Paste the URL, set content type to application/json, select Issues events.

How It Works

When a new issue is opened in a monitored repo:

1. GitHub sends a POST to RuFloUI's webhook endpoint
2. RuFloUI validates the HMAC signature (if secret configured)
3. A high-priority task is created with the issue title and body
4. If a swarm is active, the task is auto-assigned to the multi-agent pipeline
5. Agents investigate, code, test, and produce a result
6. Event status updates in the Webhooks page as the task progresses

Environment Variables (alternative to dashboard)

Variable	Default	Description
GITHUB_WEBHOOK_ENABLED	false	Enable webhook receiver
GITHUB_TOKEN	—	GitHub PAT with repo scope
GITHUB_WEBHOOK_SECRET	—	HMAC secret for signature validation
GITHUB_WEBHOOK_REPOS	—	Comma-separated owner/repo list

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a branch for your feature or fix: git checkout -b feat/my-feature
3. Make your changes — follow the existing code style (TypeScript, inline CSS, Zustand for state)
4. Test — run npm run build to make sure everything compiles
5. Submit a PR — describe what you changed and why

Other ways to contribute

• Give us a star — It helps others discover the project and motivates us to keep improving it
• Spread the word — Share RuFloUI with your team, on social media, or in developer communities
• Report bugs — Open an issue with steps to reproduce
• Suggest features — We'd love to hear your ideas

Support the Project

If RuFloUI is useful to you, consider buying us a coffee:

Security Considerations

Autonomous Agent Execution

By default, RuFloUI runs Claude Code agents with --dangerously-skip-permissions, which allows agents to read, write, and execute commands without asking for confirmation. This is required for autonomous multi-agent orchestration — without it, every agent would block waiting for human approval on each action.

To disable autonomous mode, set the environment variable:

RUFLOUI_SKIP_PERMISSIONS=false

With this disabled, agents will require manual approval for each tool use, which effectively prevents autonomous swarm execution.

Local-Only by Default

RuFloUI is designed for local development use. The API server binds to localhost and restricts CORS to the frontend origin. Do not expose the API to untrusted networks without adding authentication.

Related Projects

• [claude-flow](https: