The maintainer of MEX, an open-source project memory tool for Claude Code and Codex, shipped a skill that turns long agent explanations into state diagrams built from a project's own notes, and r/AI_Agents had thoughts.
You know the feeling. You ask Claude how some flow works, it gives you six tidy paragraphs, you read every word and you still can't picture what happens when step four fails.
That's the problem behind a post on r/AI_Agents this week from the person who maintains MEX. Their fix was a state diagram skill. The thread is small, 14 points and 13 comments, but the idea is worth copying.
The pitch is simple. As the post puts it, "You can already ask Claude for Mermaid." What they wanted on top of that was a diagram that pulls in the decisions and gotchas the project has already written down, with sources you can open and check.
What's actually new
MEX itself isn't new. Its README calls it "shared project memory for engineers and their coding agents." It keeps a team's architecture notes, decisions, requirements and handoffs as Markdown inside the repo, uses Git as the sharing layer and builds local SQLite indexes on each machine. There's no hosted MEX service, no MEX account and no model key of its own.
Version 0.8.5 is the new bit. The README says it "turns complicated agent explanations into checked state diagrams." You ask your agent to explain a flow, a bug or a recovery path as a statechart, then read it in chat or open it in the local Hub, which listens on 127.0.0.1. In Claude Code the skill is /mex-statechart and in Codex it's $mex-statechart. Cursor, Windsurf, Copilot and OpenCode get instruction files but no official skill command in 0.8.
The example in the post is MEX's own setup and recovery flow, and tbh it's a good one. The first pass over the code covered the normal stuff: pauses, retries and saved files. Then a project note surfaced an awkward case. If you rebuild the CLI while an old setup process is still running, the rebuild can remove a module that process still references. Hitting Retry doesn't help, because it doesn't replace the cached imports the old process is holding.
So the recovery path changes. You need a fresh CLI process, but you can still reuse the prepared setup files. The diagram spells out the conditions for that transition. The old process has exited, the current build is coherent and the prepared files still exist. The note and the supporting code references are attached right there on the transition.
The skill can also run TLA+/TLC checks on the modeled rules. The maintainer is careful about this and you should be too. Those checks apply to the model and its assumptions, not directly to your code.
Why it matters if you build agents
Agents are good at the happy path. They read the code, they see the retry loop and they explain the retry loop. What they miss is the stuff that lives in someone's head or in a postmortem nobody reads, like "Retry does nothing if the old process is still alive."
A state diagram drags that stuff into the open, since every state needs a way out and every transition needs a condition. If the agent can't fill in a condition you've found a gap before it bites you. Tying each transition to a recorded note and a code reference also means you can check the agent's work instead of trusting its prose.
Here's where it gets practical. Say your agent runs a nightly job that pulls new signups, enriches them and posts a summary to Slack. The happy path is three boxes. The real diagram has states for a rate-limited API, a half-written batch and an expired sign-in on one of the apps. That last one is the state people forget to draw. If the agent reaches its apps through MewCP, expired access is refreshed for you, and an app that isn't connected or was revoked comes back with a link to hand to the user instead of failing quietly. The gateway also records every call, so the "what actually happened at 3am" side of the diagram has a record behind it.
One caveat from the README is worth knowing. MEX tracks drift between notes and code, but it says drift is a review signal. It doesn't prove a note is wrong, or that the model actually reasoned from the context it pulled. A diagram built from stale notes is still a confident looking diagram.
What people are saying
The thread was small but practical. One commenter said it made them wish they'd kept better notes years ago. On one of their projects, recovering from a half-failed deploy depends on knowing which temp files the old process still holds, and that catches someone out every time.
Another said they mostly use diagrams for planning, especially before letting an agent touch anything with async jobs or webhooks. Their rule of thumb: "if it cant draw a clean state machine of what its about to build, the code is almost guaranteed to be a mess."
Others use diagrams to check whether the agent is doing things properly, and one person has the agent build a small HTML page showing database tables before and after a big model change. Someone also asked the sharpest question in the thread, whether the TLA+ check runs against the diagram or the code. We didn't see an answer. And ngl a couple of replies got called out as AI-written, which is just Reddit now.
Sources