Find the gaps a review cannot see.

What a finding looks like.

A takeaway app takes an order, charges the card, and shows the customer a tracking screen. The payment code is correct. The tracking screen is correct. And when a payment is refused, that fact reaches neither — so the customer waits for an order that is never coming.

Nothing in either file is wrong, which is why this survives review. It is only visible once both halves are in the same model: the event exists, and no edge leaves it.

✗ orders.payment-refused
  no read-model or policy consumes this event  [event-no-consumer]
  → Add a projects-to edge to a read-model, a triggers edge to a policy, or set data.terminal to a reason.
 
1 error(s), 0 warning(s) across 21 nodes

That output is not a mock-up. It is regenerated from site/demo every time this page is built, so a rule whose wording changes cannot leave a stale claim here.

A board is a view, not a data structure.

Event modelling is right about the shape of a flow — actor, command, event, read-model, screen — and wrong about the storage. A swimlane board holds that shape as a picture, which is why it fragments the moment a cross-cutting concern shows up: the flow you need to see spans four lanes that were laid out for a different question.

Here the graph is the storage and the board is one projection of it, rebuilt on demand around whatever you ask about. Ask for the swimlane around one event and you get exactly that, assembled from the same nodes that answer every other question.

context: app
nodes:
  customer:     { type: actor }
  place-order:  { type: command, src: src/orders/place.ts }
  order-placed: { type: event, src: src/orders/place.ts }
edges:
  issues:   { customer: [place-order] }
  produces: { place-order: [order-placed] }

Naming src is what makes a node implemented, so there is no separate status line to keep in sync — and eventgraph verify checks those pointers still resolve, so the graph cannot quietly describe code that was renamed away.

One file, no server.

The frame below is the unmodified output of eventgraph view for the same model the finding above came from. Click a node to dim everything outside its neighbourhood; press Escape to clear it.

Open it on its own — it is a single self-contained HTML file, which is what makes it reviewable in a pull request.

Don't render everything

A whole-graph picture stops being readable within a few dozen nodes — the same failure that kills a growing swimlane board. So ask for a part, and every view prints how much of the graph it is showing, so a narrowed picture is never mistaken for the whole one.

eventgraph view --slice order-placed     the flow around one event
eventgraph view --focus place-order -d 2  two hops around a node
eventgraph view --type command,event      one lane at a time

Every rule can be told it is wrong.

A rule with no way to disagree with it becomes noise you learn to skip. So each finding names a flag that silences it — terminal, immortal, headless, detail — and most of those flags demand a reason, which lands in the model where the next reader will find it rather than in someone's memory.

The list below is generated from eventgraph rules. Every one of these was hardened against a real application rather than derived on paper.

Start from code you already have.

scaffold reads real source and writes back the part of the model it can prove — screens from file-based routing, endpoints from route registrations, aggregates from table declarations, each node pointing at the file it came from. It never guesses at the parts only a person knows, which is what the rest of the loop is for.

npm install -g eventgraph-cli

eventgraph init --yes             scaffold a project, no prompts
eventgraph scaffold | eventgraph apply -
eventgraph check --next 3         the most pressing gaps, in order

Then the loop is check --next → fill one gap → check → repeat, until the only findings left are the ones you have deliberately answered.

Then hand it to an agent

The same model over MCP, so an agent can query, check and write it without shelling out. Whether writes apply directly or come back as a diff to approve is the project's call, via agent.write.

npm install -g eventgraph-mcp

The server has no configuration of its own — it finds the project by walking up from the directory it is started in, the same way the CLI does. So register it per project, from the repository root, and every client below launches it with the right model already loaded.

Claude Code

claude mcp add eventgraph -- eventgraph-mcp

That writes it to your own machine only. Add --scope project to write .mcp.json in the repository instead, so everyone working on it gets the same server. claude mcp list confirms it connected.

Codex CLI

[mcp_servers.eventgraph]
command = "eventgraph-mcp"

In ~/.codex/config.toml. Note the underscore — Codex spells the key differently from everyone else.

Cursor · Windsurf · Zed · Claude Desktop

The common mcpServers block — .cursor/mcp.json for one project, or the client's global config for all of them.

{
  "mcpServers": {
    "eventgraph": { "command": "eventgraph-mcp" }
  }
}

VS Code · GitHub Copilot

Same shape, different key, in .vscode/mcp.json:

{
  "servers": {
    "eventgraph": { "type": "stdio", "command": "eventgraph-mcp" }
  }
}

Anything else

Skip the global install and let the client fetch it: command npx, args ["-y", "eventgraph-mcp"]. It speaks stdio and needs no environment, no token and no port.

Once it is connected, eventgraph_check is the tool to loop on — it answers "what is missing", which is the question an agent can act on, rather than "is this legal".

Prefer eventgraph_slice over reading the whole graph. A large model does not fit a context window any better than it fits a screen.