graphtty

Turn any directed graph into colored ASCII art for your terminal. Pure Python, zero external dependencies.

Installation

pip install graphtty

Deep Agent (ocean theme)

Supervisor Agent (dracula theme)

More examples available in the screenshots/ directory.

Quick start

from graphtty import render

graph = {
    "nodes": [
        {"id": "start", "name": "User Input", "type": "entry"},
        {"id": "router", "name": "Router", "type": "condition"},
        {"id": "search", "name": "Web Search", "type": "tool"},
        {"id": "calc", "name": "Calculator", "type": "tool"},
        {"id": "respond", "name": "Respond", "type": "model"},
    ],
    "edges": [
        {"source": "start", "target": "router"},
        {"source": "router", "target": "search", "label": "search"},
        {"source": "router", "target": "calc", "label": "calc"},
        {"source": "search", "target": "respond"},
        {"source": "calc", "target": "respond"},
    ],
}

print(render(graph))

           ┌ entry ─────┐
           │ User Input │
           └─────┬──────┘
                 │
                 ▼
          ┌ condition ──┐
          │   Router    │
          └──────┬──────┘
         ┌search─└──calc───┐
         ▼                 ▼
  ┌ tool ──────┐    ┌ tool ──────┐
  │ Web Search │    │ Calculator │
  └──────┬─────┘    └──────┬─────┘
         └───────┌─────────┘
                 ▼
            ┌ model ──┐
            │ Respond │
            └─────────┘

Nodes support descriptions and nested subgraphs:

# Descriptions appear as extra lines inside the box
{"id": "a", "name": "LLM", "type": "model", "description": "gpt-4o"}

# Nested subgraphs render as boxes within boxes
{"id": "b", "name": "Pipeline", "type": "subgraph", "subgraph": {"nodes": [...], "edges": [...]}}

Apply a color theme:

from graphtty import render, RenderOptions, get_theme

print(render(graph, RenderOptions(theme=get_theme("monokai"))))

CLI

graphtty graph.json
graphtty graph.json --theme monokai
graphtty graph.json --ascii
graphtty graph.json --no-types

Themes

Ten built-in color themes:

default monokai ocean forest dracula solarized nord catppuccin gruvbox tokyo-night

graphtty --list-themes

JSON format

graphtty reads a simple JSON format:

{
  "nodes": [
    { "id": "a", "name": "Start", "type": "entry" },
    { "id": "b", "name": "Process", "type": "tool", "description": "optional detail" },
    { "id": "c", "name": "End", "type": "exit" }
  ],
  "edges": [
    { "source": "a", "target": "b", "label": "optional" },
    { "source": "b", "target": "c" }
  ]
}

Benchmarks

graphtty uses a custom Sugiyama-style layout engine and optimized canvas operations for fast rendering. Benchmarks across all 12 sample graphs (50 iterations each, Python 3.11):

Run python scripts/benchmark.py to reproduce on your machine.

Related Projects

• uipath-dev: Developer console for debugging and inspecting AI agents
• uipath-python: Python SDK and CLI to build, test, and deploy AI agents