> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flow Display

> Visual workflow tracking for agent executions

The `--flow-display` flag enables visual workflow tracking, showing the progress of agent executions in real-time.

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents.yaml --flow-display
```

<img src="https://mintcdn.com/praisonai/SX0Y8_-DRBjzOTnt/docs/cli/flow-display-flow-display-shows-workflow-di.gif?s=ce0602d851584ced464168aaddfef74c" alt="Flow Display Shows Workflow" width="1497" height="1104" data-path="docs/cli/flow-display-flow-display-shows-workflow-di.gif" />

## Usage

### Basic Flow Display

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "Multi-step task" --planning --flow-display
```

**Expected Output:**

```
🎬 Flow Display enabled

╭─ Workflow: Multi-step task ──────────────────────────────────────────────────╮
│                                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                      │
│  │   Start     │───▶│  Planning   │───▶│  Execute    │                      │
│  │             │    │   ⏳        │    │             │                      │
│  └─────────────┘    └─────────────┘    └─────────────┘                      │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

📋 PLANNING PHASE
Creating implementation plan...

╭─ Workflow: Multi-step task ──────────────────────────────────────────────────╮
│                                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                      │
│  │   Start     │───▶│  Planning   │───▶│  Execute    │                      │
│  │     ✅      │    │     ✅      │    │   ⏳        │                      │
│  └─────────────┘    └─────────────┘    └─────────────┘                      │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

🚀 EXECUTION PHASE
Executing plan steps...

[Response output...]

╭─ Workflow: Multi-step task ──────────────────────────────────────────────────╮
│                                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                      │
│  │   Start     │───▶│  Planning   │───▶│  Execute    │                      │
│  │     ✅      │    │     ✅      │    │     ✅      │                      │
│  └─────────────┘    └─────────────┘    └─────────────┘                      │
│                                                                              │
│  Duration: 12.5s | Status: ✅ Complete                                      │
╰──────────────────────────────────────────────────────────────────────────────╯
```

### With YAML Agents

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents.yaml --flow-display
```

**Expected Output:**

```
🎬 Flow Display enabled

╭─ Workflow: Research and Write ───────────────────────────────────────────────╮
│                                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │ Researcher  │───▶│   Writer    │───▶│   Editor    │───▶│   Output    │  │
│  │   ⏳        │    │             │    │             │    │             │  │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

━━━ Agent: Researcher ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Research output...]

╭─ Workflow: Research and Write ───────────────────────────────────────────────╮
│                                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │ Researcher  │───▶│   Writer    │───▶│   Editor    │───▶│   Output    │  │
│  │     ✅      │    │   ⏳        │    │             │    │             │  │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

━━━ Agent: Writer ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Writing output...]

[Continues through all agents...]

╭─ Workflow: Research and Write ───────────────────────────────────────────────╮
│                                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │ Researcher  │───▶│   Writer    │───▶│   Editor    │───▶│   Output    │  │
│  │     ✅      │    │     ✅      │    │     ✅      │    │     ✅      │  │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘  │
│                                                                              │
│  Duration: 45.2s | Agents: 3 | Status: ✅ Complete                          │
╰──────────────────────────────────────────────────────────────────────────────╯
```

### With Handoff

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "Research and write" --handoff "researcher,writer,editor" --flow-display
```

**Expected Output:**

```
🎬 Flow Display enabled
🤝 Handoff chain: researcher → writer → editor

╭─ Handoff Flow ───────────────────────────────────────────────────────────────╮
│                                                                              │
│  ┌─────────────┐         ┌─────────────┐         ┌─────────────┐           │
│  │ researcher  │────────▶│   writer    │────────▶│   editor    │           │
│  │   ⏳        │         │             │         │             │           │
│  └─────────────┘         └─────────────┘         └─────────────┘           │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

[Execution with visual updates...]
```

### Combine with Other Features

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Flow display with metrics
praisonai "Complex task" --planning --flow-display --metrics

# Flow display with handoff and guardrail
praisonai "Write code" --handoff "coder,reviewer" --flow-display --guardrail "Best practices"
```

## Visual Elements

### Status Icons

| Icon | Meaning                |
| ---- | ---------------------- |
| ⏳    | In progress            |
| ✅    | Completed successfully |
| ❌    | Failed                 |
| ⏸️   | Paused/Waiting         |
| 🔄   | Retrying               |

### Flow Indicators

```
┌─────────────┐    ┌─────────────┐
│   Agent 1   │───▶│   Agent 2   │
│     ✅      │    │   ⏳        │
└─────────────┘    └─────────────┘
```

* Boxes represent agents/steps
* Arrows show flow direction
* Status icons show current state

## Use Cases

### Debugging Workflows

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# See where a workflow fails
praisonai agents.yaml --flow-display -v
```

**Expected Output (with error):**

```
╭─ Workflow: Data Pipeline ────────────────────────────────────────────────────╮
│                                                                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                      │
│  │   Fetch     │───▶│  Transform  │───▶│    Load     │                      │
│  │     ✅      │    │     ❌      │    │             │                      │
│  └─────────────┘    └─────────────┘    └─────────────┘                      │
│                                                                              │
│  ❌ Error at: Transform                                                      │
│  Message: Invalid data format                                                │
╰──────────────────────────────────────────────────────────────────────────────╯
```

### Monitoring Long Tasks

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Track progress of complex research
praisonai "Comprehensive market analysis" --planning --flow-display
```

### Demo/Presentation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Visual workflow for demonstrations
praisonai agents.yaml --flow-display
```

## Flow Display Modes

### Sequential Flow

```
┌───────┐    ┌───────┐    ┌───────┐
│ Step1 │───▶│ Step2 │───▶│ Step3 │
└───────┘    └───────┘    └───────┘
```

### Parallel Flow

```
              ┌───────┐
         ┌───▶│ Task1 │───┐
┌───────┐│    └───────┘   │┌───────┐
│ Start │┤                ├▶│  End  │
└───────┘│    ┌───────┐   │└───────┘
         └───▶│ Task2 │───┘
              └───────┘
```

### Hierarchical Flow

```
┌─────────────────────────────────┐
│           Manager               │
│              │                  │
│    ┌─────────┼─────────┐       │
│    ▼         ▼         ▼       │
│ ┌─────┐  ┌─────┐  ┌─────┐     │
│ │ W1  │  │ W2  │  │ W3  │     │
│ └─────┘  └─────┘  └─────┘     │
└─────────────────────────────────┘
```

## Best Practices

<Tip>
  Use `--flow-display` with `--planning` to see the full workflow from planning to execution.
</Tip>

<CardGroup cols={2}>
  <Card title="Complex Workflows">
    Best for multi-agent or multi-step workflows
  </Card>

  <Card title="Debugging">
    Helps identify where workflows fail
  </Card>

  <Card title="Demonstrations">
    Great for showing workflow progress to stakeholders
  </Card>

  <Card title="Monitoring">
    Track long-running tasks visually
  </Card>
</CardGroup>

## Terminal Requirements

<Note>
  Flow display works best in terminals that support Unicode and ANSI colors. Most modern terminals (iTerm2, Windows Terminal, VS Code terminal) support these features.
</Note>

| Terminal         | Support    |
| ---------------- | ---------- |
| iTerm2           | ✅ Full     |
| Windows Terminal | ✅ Full     |
| VS Code Terminal | ✅ Full     |
| macOS Terminal   | ✅ Full     |
| Basic terminals  | ⚠️ Limited |

## Related

* [Workflows Feature](/features/workflows)
* [Handoff CLI](/docs/cli/handoff)
* [Planning Mode](/features/planning-mode)