graphtty 0.1.0

Turn any directed graph into colored ASCII art for your terminal

graphtty

Turn any directed graph into colored ASCII art for your terminal.

Installation

pip install graphtty

Deep Agent (ocean theme)

Supervisor Agent (dracula theme)

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" }
  ]
}

Acknowledgements

Built with :heart: on top of grandalf, a Python library for graph layout using the Sugiyama algorithm.