Awk! Awk! Add a diagram!: Greptile-style PR diagrams, minus the SaaS

I review a lot of pull requests with Claude Code and Codex these days. The /review command is genuinely good — it reads the diff, spots the sharp edges, writes it up. But the output is always a wall of prose. On a PR that touches a request path across three services, I'd find myself drawing the call flow on a napkin to convince myself the review was right.

Meanwhile, the hosted reviewers — Greptile, CodeRabbit — just draw it for you. Every PR gets a tidy Mermaid sequence or flow diagram at the top of the review. It's lovely. I wanted that.

So I looked at what it would take.

What's notable here?

The hosted tools render those diagrams server-side: your diff goes to a third party, runs through their LLM, on their subscription. That's a lot of machinery for "turn this diff into a picture" — especially when my /review is already being written by a perfectly capable LLM running on my machine. The model that just understood the change well enough to critique it can obviously draw it.

The diagram doesn't need a SaaS. It needs about thirty lines of glue.

The idea: let the agent draw, let gh post

That's the whole design of Iago 🦜 — a skill, not a service:

1. The host agent draws the diagram. Iago's SKILL.md tells your agent which diagram type fits the diff and how to write valid Mermaid. No provider SDK, no API key — it uses the LLM you're already paying for.
2. A tiny helper posts it. A single TypeScript file (post.ts, run by bun) finds your /review comment and appends the diagram via authenticated gh. That's the entire runtime: bun + gh.
3. It's idempotent. Re-run it and it replaces its own block instead of stacking duplicates, using a pair of HTML markers.

No server. No key. No diff leaves your machine except through the same gh you already trust.

What it actually posts

Iago auto-detects the diagram type from the diff — and you can always override it:

The diff looks like…	You get
migrations / *.sql / ORM models	an entity-relation diagram
new classes / interfaces across files	a class diagram
a request hopping handler → client → worker	a sequence diagram
branching / state-machine logic	a flowchart
a docs or dependency bump	nothing — it abstains

See an example:

GitHub renders that inline, right on top of the review. (dev.to may show the source above; paste it into a PR to see it drawn.)

Quick start

Runtime is just bun and an authenticated gh. Install the skill into whatever agent you use:

bunx @drakulavich/iago install --force

On Claude Code you can grab the plugin instead:

/plugin marketplace add drakulavich/iago
/plugin install iago@iago-marketplace

Then, on any PR:

/review        # your agent writes the review
/iago          # Iago perches on top of it and squawks a diagram

/squawk is an alias, because of course it is.

A gotcha I'll save you from

Here's the kind of thing that only bites you in production. My sequence-diagram example stopped rendering on GitHub one day, with no useful error. The culprit:

participant Loop

loop is a reserved keyword in Mermaid's sequence grammar — along with alt, opt, par, note, end, and activate. Name a participant Loop and GitHub's renderer silently chokes. Renaming it to Reader fixed it instantly.

So Iago's templates steer the agent away from those reserved ids, and the helper validates with mermaid.parse() before anything gets posted. You shouldn't ever hit it — but if you write Mermaid by hand, now you know where the body is buried. 💀

"Okay, but how do you know the diagrams are any good?"

Fair question, and I'll be honest: there's no benchmark. Diagram quality is the kind of thing a number doesn't capture well, so I validate it by dogfooding — running /iago on real PRs whenever I touch the selection rubric, and looking at what comes out. A formal eval harness felt like overkill for a tool whose whole pitch is "small and dependency-free." I'd rather keep it that way.

Try it on your next PR

If your /review workflow ends in a wall of text, this is a thirty-second add-on that puts a picture on top of it — without signing up for anything. It's MIT, it's on GitHub and npm.

What does your AI code-review setup look like these days — and what would you want drawn automatically on every PR? Would love to hear what you're running. 💎