JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.
JiuwenSwarm TUI SwarmFlow Guide
This document is for JiuwenSwarm TUI users. It covers the complete workflow of using SwarmFlow (Swarm Workflows) in the terminal interface, including configuration, triggering runs, real-time monitoring, and interactive inspection.
Overview
SwarmFlow is the workflow orchestration and execution capability provided by JiuwenSwarm in Team mode. When multiple Agents form a team to collaborate on complex tasks, SwarmFlow decomposes the entire task into ordered phases, with each phase containing several Agents that execute subtasks in parallel or sequentially. SwarmFlow provides full lifecycle management — from launch and progress tracking to result inspection.
Core Concepts
| Concept | Description |
|---|---|
| Workflow | A complete SwarmFlow run instance, containing multiple phases and agents |
| Phase | An execution stage within a workflow, e.g. "research", "analysis", "writing" |
| Agent | A team member executing a specific subtask within a phase |
| Run ID | A unique identifier for each workflow run, generated by SwarmflowTool at launch |
| Status | Workflows, phases, and agents each have independent statuses: running / completed / failed / stopped / planned / pending |
Workflow Lifecycle
workflow_started → phase → agent_started → agent_completed/failed → ... → workflow_completed/failed
- Launch: The Leader Agent analyzes the user's request, starts the workflow via
SwarmflowTool, and generates arun_id - Phase progression: The workflow advances through phases in order; agents within each phase execute in parallel
- State aggregation:
WorkflowMonitorHandleraggregates progress events in real time and pushes incremental updates - Completion / Failure: The workflow enters a terminal state once all phases have finished executing
Prerequisites
1. Install and Start the JiuwenSwarm Backend
# Install
pip install jiuwenswarm
# Initialize (first time)
jiuwenswarm-init
# Start the backend service
jiuwenswarm-start
2. Install and Start the TUI
# Install the TUI
pip install jiuwenswarm-tui
# Start the TUI (in a separate terminal)
jiuwenswarm-tui
The TUI connects to the local Gateway's TUI endpoint via WebSocket (default:
ws://127.0.0.1:19001/tui). Make sure the backend service is running.
3. Configure the Model API
On first use, you need to set up the model API in the configuration. You can do this through the Web frontend (http://localhost:5173) in the Configuration panel, or by using the /config command in the TUI.
Enabling SwarmFlow
SwarmFlow is enabled by default in the Team mode configuration. The configuration file is located at ~/.jiuwenswarm/config/config.yaml.
Configuration
In the modes.team section of config.yaml, the enable_swarmflow field controls whether SwarmFlow is enabled:
modes:
team:
jiuwen_team:
team_name: jiuwen_team
lifecycle: persistent
teammate_mode: build_mode
spawn_mode: inprocess
enable_swarmflow: true # Set to true to enable SwarmFlow, default is True
leader:
member_name: team-leader
display_name: Team Leader
persona: "Expert project manager, skilled at task decomposition and team coordination"
agents:
leader: $agent_leader
workspace:
enabled: true
transport:
type: inprocess
storage:
type: sqlite
Key Configuration Fields
| Field | Description | Default |
|---|---|---|
enable_swarmflow |
Whether to enable SwarmFlow workflows | true |
team_name |
Team name | jiuwen_team |
lifecycle |
Team lifecycle: persistent / temporary |
persistent |
teammate_mode |
Member build mode: build_mode |
build_mode |
spawn_mode |
Process mode: inprocess (single machine) / see Distributed Team for distributed |
inprocess |
Note: After modifying the configuration, restart the JiuwenSwarm backend service (
jiuwenswarm-start) for changes to take effect.
Using SwarmFlow
Step 1: Switch to Team Mode
In the TUI, enter the following command to switch to Team mode:
/mode team
After switching, the TUI displays the current mode as team, and the Leader Agent takes charge of coordinating team tasks.
Step 2: Submit a Task
In Team mode, simply type a task description. SwarmFlow starts automatically after the Leader analyzes the task:
In swarmflow mode, research the new energy vehicle industry and produce an analysis report
The Leader Agent will:
- Analyze the requirements and decompose the task into multiple phases (e.g., research → analysis → writing → review)
- Launch the workflow via
SwarmflowTool, generating arun_id - Assign team members to execute subtasks in each phase
Step 3: Monitor Workflow Progress
After a workflow starts, the TUI main view automatically displays a running workflow status banner:
◐ 1 workflow running
NEV Industry Research · 2m 15s
The banner includes:
- An animated spinner indicator (
◐◓◑◒) - The number of running workflows
- The workflow name and elapsed time
Step 4: Inspect Workflow Details
Use the /swarmflows command to open the SwarmFlow interactive viewer:
/swarmflows
You can also use the alias:
/swarmworkflows
SwarmFlow Interactive Viewer
Opening /swarmflows enters a full-screen interactive view with three levels of navigation: Workflow List → Phase Details → Agent Details.
Level 1: Workflow List
Displays an overview of all workflows in the current session:
Swarm workflows
2 running, 1 completed
● running NEV Industry Research 3/8 agents
● running Competitive Analysis 1/5 agents
✓ completed User Profiling 6 agents
up/down select - Enter view - r refresh - Esc close
| Information | Description |
|---|---|
| Status icon | ● running / ○ pending / ◎ planned / ✓ completed / ✗ failed / ■ stopped |
| Workflow name | Set by SwarmflowTool at launch |
| Agent progress | completed/total format |
Controls:
| Key | Action |
|---|---|
↑ / ↓ |
Move focus between workflows |
Enter |
Enter the selected workflow's phase details |
r |
Refresh the workflow list |
Esc |
Close the viewer, return to chat |
Level 2: Phase Details
After selecting a workflow, you enter the phase detail view. The left side shows the phase list, and the right side shows the agents in the current phase:
NEV Industry Research
Research the NEV industry and produce an analysis report
● running · 3/8 agents
2m 15s
Logs
[leader] Starting research phase...
[researcher] Searching industry data...
Phases Agents · Research
✓ Research 2/3 ● running Data Researcher · glm-5
● Analysis 1/3 ● running Market Analyst · glm-5
○ Writing 0/2 ✓ completed Info Collector · glm-5
press l to see full logs
up/down select phase · Enter show agents · Tab/Right agents · Esc back
Controls:
| Key | Action |
|---|---|
↑ / ↓ |
Move focus between phases |
Enter |
Switch focus to the agent list |
Tab / → |
Toggle focus between Phases and Agents lists |
← |
Return to the workflow list |
l |
View full workflow logs (enters the file viewer) |
r |
Refresh |
Esc |
Return to the workflow list |
Level 3: Agent Details
Select an agent in the agent list and press Enter to view details:
Data Researcher
NEV Industry Research · Research
● running · glm-5
duration 45s
Prompt
Research NEV industry market data for the past three years, including sales,...
Outcome
(Displayed after the agent completes execution)
press p to see full prompt - o outcome - e error
Esc/← back
Controls:
| Key | Action |
|---|---|
p |
View full Prompt (enters the file viewer) |
o |
View full Outcome (enters the file viewer) |
e |
View full Error message (enters the file viewer; only available on failure) |
← / Esc |
Return to phase details |
File Viewer
When viewing logs, Prompt, Outcome, or Error, a full-screen file viewer opens:
| Key | Action |
|---|---|
↑ / ↓ |
Scroll up / down |
PgUp / PgDn |
Page up / down |
Home / g |
Jump to the beginning |
End / Shift+g |
Jump to the end |
Esc / Ctrl+C |
Exit the viewer |
Workflow Status Reference
Workflow Statuses
| Status | Description |
|---|---|
running |
The workflow is currently executing |
pending |
The workflow has been created, awaiting execution |
planned |
The workflow has been planned, not yet started |
completed |
All phases in the workflow have finished executing |
failed |
An error occurred during workflow execution |
stopped |
The workflow was interrupted or stopped by the user |
Phase Statuses
| Status | Description |
|---|---|
running |
The phase is currently executing |
planned |
The phase has been planned, not yet started |
completed |
All agents in the phase have finished executing |
failed |
An error occurred during phase execution |
Agent Statuses
| Status | Description |
|---|---|
running |
The agent is currently executing a subtask |
completed |
The agent has completed its subtask |
failed |
The agent encountered an error |