# Graph Agents

Graph agents are **declarative workflows** built from LLM "nodes" wired together by "edges".
Instead of one agent improvising, you define a repeatable pipeline — each node has its own
prompt and tools, and edges decide what runs next. Think flowchart, but every box is an agent
step.

Use them when you want a **structured, repeatable process** — triage → research → draft →
review, or fan a task out over a list and gather the results.

## What a graph can do

- **Conditional routing** — a node chooses which edge to follow next
- **Parallel fan‑out / fan‑in** — run several branches at once and join them back together
- **Map over a list** — run a node once per item in a collection and collect the outputs
- **Subgraphs** — reuse a whole saved graph as a single node
- **Shared state** — nodes read and write named state values, merged with rules you choose
  (replace, append, sum, …)
- **Human‑in‑the‑loop** — a node can pause to ask you a question and resume with your answer
- **Durable checkpoints** — a run saves its progress and can resume later, even after a restart
- **Per‑node retry, barriers, and caching** — for robustness and speed

## Creating a graph

You don't hand‑write graphs — you **describe them to Morphy** and it builds, validates, and
saves them for you. For example:

```
Build a graph called "triage" that classifies an incoming bug report, routes it to a
"frontend" or "backend" node, and drafts a reply.
```

Morphy authors the workflow, checks it for errors, and saves it. Graphs are stored as JSON
under `~/.morphy/graphs/`, one file per graph, so they persist and can be edited later (again,
just by asking).

## Using graphs in the terminal (TUI)

The terminal interface has full, interactive graph support:

| Command | What it does |
| --- | --- |
| `/graphs` | Open the graphs dialog (browse and delete saved graphs) |
| `/graph` | List your saved graphs |
| `/graph <name>` | Enter **graph mode** — talk directly to that graph |
| `/graph off` | Leave graph mode and return to the main agent |
| `/graph verbose [on\|off\|toggle]` | Show/hide node, tool, and edge details during a run |

In graph mode, each message you send is fed into the graph. It runs until it finishes, asks
you a question (human‑in‑the‑loop), or hits its step limit. Use `/graph off` to exit.

## Graphs in channels

You can put a channel (Telegram, Discord, Slack, X) permanently behind a graph, so every
incoming message goes straight to it:

```
/channels set-graph <channel> <graph>     # bind a graph to a channel
/channels set-graph <channel> none        # unbind
```

To route **every** channel and session through one graph, start the server with it:

```bash
morphy --server --graph <name>
```

A per‑channel binding overrides the global one. While a graph is bound, it can't be edited or
bypassed from inside that channel — useful for locked‑down support bots.

## Graphs in the Desktop app and VS Code

In the desktop app and the VS Code extension you can today:

- **Review and rewind** a running graph's checkpoints with `/graph` (and `/graph rewind <index>`)
- **Bind a graph to a channel** from the Channels settings screen

Full interactive graph mode (talking to a named graph as in `/graph <name>`) currently lives
in the [terminal interface](tui.md). You can always author and run graphs there, and any
channel binding applies everywhere.