mex 0.8.5: checked state diagrams and setup that keeps its progress

Some code is hard to explain in prose. A retry loop with three exit paths, a session that can be paused, resumed or revoked, a setup flow that has to survive an interrupted agent. You can read the files, but what you actually want is the picture: which states exist, what moves between them, and where it can go wrong.

mex 0.8.5 gives your coding agent a way to draw that picture and check it. This release also makes setup parallel and resumable, so a large repository no longer has to finish in one sitting, and it cuts the cost of building and refreshing graphs on large TypeScript codebases.

npm install -g mex-agent@0.8.5

Ask your agent to "explain this using a statechart", or invoke the new mex-statechart skill in Claude Code or Codex. It can explain existing behavior, show a bug or a recovery path, compare a proposed fix, or start from a chart you have already agreed on or an existing TLA+ model.

The diagram uses human language for states and events, and it draws on what mex already knows: project knowledge, the code links behind it, and relevant history when that helps explain the behavior.

When you want more than a drawing, TLA+/TLC checking explores the modeled states and checks the rules you state. If a rule can break, you get numbered counterexample paths that show how. We are careful about what that means: a checked model is still an abstraction. Whether the model matches the source, whether the path reproduces against real code, and how fresh the evidence is are reported separately. Missing tooling or evidence stays visible instead of turning into a passing result.

• Read it where you work. Clients that render Mermaid get the diagram natively. Terminal clients that can't render it get readable text, and clients that display images can get an optional PNG.
• Explore it in Hub. An optional preview lets you select states, follow directed transitions, pan and zoom, and step through numbered paths, rules and evidence. The agent can offer to start and open it for you.
• Keep it, or don't. Previews are temporary unless you review and save a snapshot. Saved diagrams live as Markdown-owned bundles under .mex/diagrams/ and reopen without Java or a built code index. Saving never stages, commits or pushes; share it through Git when you want to.

Installing, upgrading and viewing diagrams in Hub never install or run Java. Explicit checking needs Java 11 or newer and the pinned, checksum-verified TLC 1.7.4 toolchain; the skill documents first-use setup.

Setting up a large repository used to be one long run. Now it is split into subsystem tasks, with up to three population tasks running in parallel by default. Background population can overlap with graph construction, and completed batches survive an interruption or an agent hitting its usage limit. The terminal and Hub both show progress and what to do next.

• More agents can run setup in the background. Cursor, GitHub Copilot and OpenCode CLI join Claude Code and Codex, as long as the agent is installed and signed in.
• Agents mex can't launch still work. mex setup next --start begins a resumable one-paste flow, and each later call applies completed batches and continues the plan.
• Rerunning is safe. A healthy checkout reports its setup status instead of starting over, and only one setup can run per checkout.
• Fewer surprises. Setup recognizes deeply nested sources, checks Git before the terminal tool picker, audits thin project knowledge, and keeps existing facts whose code has changed for explicit mex sync review instead of dropping them.

Here is the new flow, drawn as a statechart:

In a client that renders Mermaid, the same flow comes back as text you can read, diff and commit:

stateDiagram-v2
  [*] --> Plan
  Plan --> Populating: start
  state Populating {
    [*] --> AgentTasks
    --
    [*] --> GraphBuild
  }
  Populating --> Paused: interrupted / usage limit
  Paused --> Populating: rerun (saved batches skipped)
  Populating --> Failed: error
  Failed --> Paused: finish later
  Populating --> Review: all batches done
  Review --> Checkpoint: you commit
  Checkpoint --> [*]

Large TypeScript monorepos now build with less memory and in less time. On a 9,400-file benchmark that previously failed, the build now completes at Node's default heap, and its graph database is about 27% smaller. That is a measurement on one fixture, not a promise for every repository. Refresh also reuses unchanged compiler projects, and CLI maintenance uses the same memory-sized worker as Hub.

Results are easier to read, too:

• who-calls and impact put production callers first. Test results that were left out are counted, and --include-tests brings them back. Call locations and compact line counts make long declarations easier to navigate.
• Scope keeps the fingerprints you asked for, and no longer drops a compact answer when you give it a larger budget.
• Interrupted maintenance cleans up abandoned candidate databases safely, while keeping deliberate recovery copies.
• Wiki operations can be applied as atomic batches of up to 200, with scoped grounding checks.

Hub also recovers from expired or reused access links and shows the Wiki migration command in Health.

0.8.4 shipped two weeks earlier and is worth knowing about if you are upgrading from 0.8.3 or earlier. It made terminal setup the default, with a native handoff to Claude Code or Codex, and made mex check, Wiki queries and Hub share the same fact-aware verdicts, so comment-only and formatting-only edits no longer flag a fact. New grounding fingerprints use a compact mh2: encoding that substantially reduces committed Markdown size. Everyone sharing mh2: fingerprints needs 0.8.4 or newer. The 0.8.4 release notes have the details.

Install 0.8.5, then sync skills in each existing mex project. This installs mex-statechart through the same managed updater as Inbox and Relay. Upgrading the CLI alone does not update a project's skill copies.

npm install -g mex-agent@0.8.5
mex skills sync --dry-run
mex skills sync

Review the dry run, resolve any local conflicts it reports, then start a fresh Claude Code or Codex session. Keep your existing graph, then run:

mex graph refresh
mex check
mex sync

The updated TypeScript extractor causes a one-time rebuild, and some declaration IDs can change, so refreshing the existing graph (rather than deleting it) gives mex the chance to map old IDs before you review affected links. Graph schema v4 and Wiki index v5 are unchanged from 0.8.4. Projects coming from 0.8.3 or earlier also need the 0.8.4 maintenance steps, including an explicit Wiki index rebuild. Node.js 22.5 or newer with SQLite FTS5 is still required.

Completed setup does not need to run again just for this upgrade. When teammates should get the changes, review them and commit and push as usual.

Thanks to everyone who contributed since 0.8.4: @theDakshJaitly (checked state diagrams and Hub rendering), @theyashasvipandey (parallel and resumable setup, setup reliability and graph performance), @Akshtdhamija (setup recovery and validation, graph read fixes, managed skill portability and Hub access), @M4Y4NK-V3RM4, @Golden007-prog, @tarun5004, @arxh80, @iamcipherdev, @uzumakienes and @onuracar-dev.

Full details are in the 0.8.5 release notes, the changelog and the compatibility guide. Questions or feedback? Come say hi on Discord.