ASCII Diagrams

Generate clean, portable ASCII/Unicode diagrams that work in any markdown viewer.

Quick Start

Use the bundled script to generate diagrams programmatically:

python3 scripts/ascii_diagram.py <diagram_type> '<json_data>'

Or generate diagrams directly by understanding the user's requirements and creating appropriate ASCII art.

Supported Diagram Types

1. Vertical Flowcharts

Top-to-bottom process flows with labeled arrows.

Example input:

{
  "steps": [
    {"text": "User", "label": "request"},
    {"text": "Agent", "label": "activate"},
    {"text": "Skill", "label": "calls"},
    {"text": "MCP Tool"}
  ]
}

Example output:

┌─────────────┐
│    User     │
└──────┬──────┘
       │ request
       │
       ▼
┌─────────────┐
│    Agent    │
└──────┬──────┘
       │ activate
       │
       ▼
┌─────────────┐
│    Skill    │
└──────┬──────┘
       │ calls
       │
       ▼
┌─────────────┐
│  MCP Tool   │
└─────────────┘

2. Horizontal Flowcharts

Left-to-right process flows.

Example input:

{
  "steps": [
    {"text": "Start"},
    {"text": "Process", "label": "data"},
    {"text": "End"}
  ]
}

Example output:

┌──────────┐      ┌──────────┐      ┌──────────┐
│  Start   │ ────▶│ Process  │ ────▶│   End    │
└──────────┘      └──────────┘      └──────────┘

3. Decision Trees

Branching diagrams with diamond-shaped decision nodes.

Example input:

{
  "text": "Is logged in?",
  "yes": {
    "text": "Show Dashboard"
  },
  "no": {
    "text": "Redirect to Login"
  }
}

4. Sequence Diagrams

Show interactions between components over time.

Example input:

{
  "actors": ["User", "Agent", "Skill"],
  "interactions": [
    {"from": "User", "to": "Agent", "label": "request"},
    {"from": "Agent", "to": "Skill", "label": "activate", "return": true}
  ]
}

Script Usage

The scripts/ascii_diagram.py script provides a reliable, deterministic way to generate diagrams.

CLI Interface

# Vertical flowchart
python3 scripts/ascii_diagram.py vertical '{"steps": [{"text": "Step 1"}, {"text": "Step 2"}]}'

# Horizontal flowchart
python3 scripts/ascii_diagram.py horizontal '{"steps": [{"text": "A"}, {"text": "B"}]}'

# Decision tree
python3 scripts/ascii_diagram.py decision '{"tree": {"text": "Condition?", "yes": {"text": "Action A"}, "no": {"text": "Action B"}}}'

# Sequence diagram
python3 scripts/ascii_diagram.py sequence '{"actors": ["A", "B"], "interactions": [{"from": "A", "to": "B", "label": "message"}]}'

Data Structure Reference

Vertical/Horizontal Flows:

• •steps: Array of objects
  • •text (required): Content of the box
  • •label (optional): Text to display on the arrow

Decision Trees:

• •tree: Object (can be nested)
  • •text (required): Decision or action text
  • •yes (optional): Branch for true condition
  • •no (optional): Branch for false condition

Sequence Diagrams:

• •actors: Array of strings (actor names)
• •interactions: Array of objects
  • •from (required): Source actor name
  • •to (required): Target actor name
  • •label (optional): Message text
  • •return (optional): Boolean, add spacing for return message

Design Principles

1. •Portability: Pure Unicode box-drawing characters work everywhere
2. •Readability: Consistent spacing and alignment
3. •Flexibility: Support for common diagram types
4. •Simplicity: No external dependencies or rendering engines

Best Practices

• •Keep text in boxes concise (prefer short phrases)
• •Use clear, descriptive labels on arrows
• •For complex flows, consider breaking into multiple diagrams
• •Test diagrams in your target markdown viewer
• •Use monospace font for best alignment