Gridwillow is a text language for software architecture. Point your coding agent at your codebase and it writes the file — services, databases, queues and the data between them. The compiler draws an isometric blueprint you can pan, hover and click through.
examples/payments.bp;
this page is what bp export made of it.
Every construct is one line beginning with a keyword. Indentation is decorative,
so a mis-indented file still parses. A group
scopes the blocks under it; an arrow is a connection.
# the ledger, and what writes to it db orders "Orders" x1.5 is the ledger — every authorisation and refund why > Postgres, single writer, two read replicas. The only store permitted to be a source of truth. fact Engine = Postgres 16 fact Backups = PITR, 7 days list Tables = orders, captures, refunds link Runbook = https://wiki/runbooks/orders env DATABASE_URL PGBOUNCER_HOST checkout -write-> orders "the authorisation" carry INSERT INTO orders (id, state, amount_cents) why Written before the processor is called, never after. A crash between the two leaves a recoverable row rather than a mystery. vol 0.8
There are eight shapes, but many words for each. Write db,
topic, bucket, lb, worker,
cron — whatever it actually is. They alias onto the same small
visual vocabulary, so the drawing stays learnable in about a minute.
A connection must name something concrete in carry — a type, a
function, a table, a route. If you can't name what crosses it, the line isn't
real and the checker says so. This is the rule that stops generated diagrams
becoming boxes joined by vibes.
fact, list, link and env
fill an inspector panel that opens when you click a block. Table names, env
vars, runbook links, source paths — the things you'd otherwise go hunting
through four repos for.
A diagram is only worth keeping if it answers questions. Gridwillow puts three layers of depth behind the same picture, so one blueprint serves the person skimming and the person on call.
A laminated slab is a store. A ribbed stack is a queue. A ghost box is something you don't own. Because the vocabulary is closed, two blueprints of two unrelated systems can be read side by side.
Hovering a block says what it does and what backs it. Hovering a hairline says exactly what crosses it, when it fires, and what failure looks like — with its packets speeding up so you can see which line you're reading.
Selecting a block opens an inspector: facts, table names, indexes, environment variables, source paths, runbooks, and every connection in and out — each one clickable, so you can walk the system without touching the drawing.
Gridwillow ships two skills for OMP
— and, because the format is the same, for Claude Code. Install them once and
"map this repo out for me" produces a .bp
that compiles, instead of a fourth invented diagram format this week.
Manifest, entrypoints, migrations, deployment config, the tree two levels deep. Nothing is written during this pass — starting early is the reliable way to get a diagram full of plausible, wrong connections.
Subsystems become blocks; the call graph becomes connections. Every line has to name a concrete function, table or route — if the agent can't, the rule says delete the line rather than draw a guess.
The compiler is the grader. Dangling connections, undeclared blocks and missing prose are errors with line numbers; vague payloads and unwired blocks are warnings the agent is told to act on.
Both skills are plain SKILL.md files with name and
description frontmatter — the format OMP and Claude Code both
discover. One folder, symlinked, serves either.
./skills/install.sh → ~/.omp/agent/skills/
· ./skills/install.sh claude → ~/.claude/skills/
gridwillow-blueprint writes one from scratch and bundles its own grammar and prose references, so it works installed globally with no copy of the repo nearby. gridwillow-refresh takes an existing blueprint and checks every claim in it against the code — paths that moved, functions that were deleted, tables that were added — because a diagram that is quietly wrong is worse than none.
Gridwillow is meant to be written by an agent, so the documentation is served the
way an agent wants to read it: every reference page is HTML at its URL and raw
markdown at the same URL with .md
on the end. Nothing here is behind JavaScript, and nothing needs an account.
Every document on this site, concatenated into one file: the language
reference, the procedure for writing a blueprint from a codebase, the prose
guide, the EBNF grammar and a complete worked example. One fetch and a model
can write a .bp that compiles. Start here.
The index — every page, with a sentence on what question it answers, in the llms.txt format. Fetch this first if you would rather choose than read everything.
The same documents as pages, for reading with your eyes. Each one links to its markdown twin at the foot.
The formal grammar, and the JSON Schema for the compiled form the renderer consumes. The normative answer when the prose and your parser disagree.
The worked example — the file drawn at the top of this page — and Gridwillow's own architecture written in its own language. The fastest way to show a model what good looks like.
# nothing to install, in any agent that can fetch a URL > read https://gridwillow.com/llms-full.txt, then map this repo out as a gridwillow blueprint and run bp check until it passes