Flow Builder

Status: Implemented — Available in the web UI at http://localhost:3584 (Flows tab, 🔄 icon)

Overview

The Flow Builder is a visual editor for .armaflow.json workflow definitions. It renders workflow DAGs as interactive node graphs using React Flow (@xyflow/react), allowing drag-and-drop composition of multi-agent pipelines. Flows are stored as JSON with nodes and edges matching React Flow’s native format, while also regenerating the text .armaflow format for TUI compatibility.

Supported Node Types

Agents

Node	Directive	Description
🤖 Spawn Agent	`/spawn`	Launch an AI agent with a task
⏳ Join	`/join`, `/collect`	Wait for agents to complete, collect results

Control Flow

Node	Directive	Description
⇉ Parallel	`/parallel ... /end`	Execute agents concurrently
🔀 Condition	`/if`, `/elif`, `/else`	Branch based on expression (true/false handles)
✅ Approve	`/approve`, `/gate`	Human approval gate
⏸️ Wait	`/wait`	Wait for agent completion or event
💻 Run Script	`/pipe`	Execute shell script between agents

Injectors (pill-shaped, output-only)

Node	Directive	Description
🌱 Seed Context	`/seed` (role=system)	Inject system prompts, .md files, notes
🎭 Fake Context	`/seed` (role=user/assistant)	Inject fake conversation history. Multi-node chaining supports ordered multi-message injection.
📂 Allow Paths	`/allow`	Grant workspace directory permissions
📋 Complete Schema	`/complete` + `/field`	Define structured output schema agents must report

Output

Node	Directive	Description
📝 Log Output	`/log`	Write to flow log
💬 Send Message	`/msg`	Send message to agent channel
💤 Sleep/Delay	`/sleep`	Pause execution
💀 Kill Agent	`/kill`	Terminate an agent

Edge Types

Edges use distinct colors and patterns to convey relationship type:

Edge	Color	Pattern	Meaning
chain	green	solid, animated	Sequential agent handoff
collect	amber	solid	Gather results from multiple agents
join	blue	solid	Parallel convergence
seed	purple	dashed	Context/fake history injection
pipe	cyan	solid, animated	Shell script data transformation
allow	gray	dotted	Workspace permission grant
wait	blue	dotted	Agent completion dependency

Features

Drag-and-drop from palette onto canvas
Connect nodes by dragging between handles
Auto Format using dagre DAG layout algorithm
Snap-to-grid at 20px intervals
Canvas pan and zoom via React Flow controls
Delete nodes/edges with Backspace/Delete
Properties panel — click any node to edit agent settings (model, provider, timeout, budget), injector content, condition expressions
Provider/Model dropdowns populated from your configured providers
Save persists to .armaflow.json and regenerates .armaflow for TUI
Run executes the flow against live agents

File Format

Flows are stored as JSON alongside the text format:

.arma/flows/
  code-review-pipeline.armaflow      # Text format (TUI compatible)
  code-review-pipeline.armaflow.json # JSON format (web UI native)

The JSON schema matches FlowDefinition:

{
  "name": "my-flow",
  "description": "...",
  "trigger": "manual",
  "nodes": [
    { "id": "agent-1", "type": "spawn", "config": { "agentName": "reviewer", "task": "Review the code", "model": "claude-sonnet-4", "_position": { "x": 50, "y": 0 } } }
  ],
  "edges": [
    { "from": "start", "to": "agent-1", "label": "chain" }
  ]
}