Omaspec

The source in the middle, the live diagram on the right, in the colors of your Omarchy theme and the font omarchy font set picked. One binary with its own engines: no Java, no browser, no network, and it sends nothing anywhere.

Why Omaspec

It draws as you type

Omaspec draws with its own engines, in a few milliseconds: PlantUML sequence, activity, state, class, component, use case, deployment, object, timing and Gantt diagrams, C4-PlantUML, ArchiMate, network diagrams, Salt wireframes, EBNF and regex railroads, Ditaa drawings, mind maps, WBS, JSON, YAML and formulas, and Mermaid flowcharts, state and sequence diagrams. The other Mermaid types are drawn by mmdr, a Rust library, in the same process. A dense flowchart, 150 boxes and 476 lines between them, is laid out in under half a second. Lint findings are underlined while you type, and a Ctrl+click in the diagram jumps to its line in the source.

Large diagrams too: the delivery drone in examples/drone has 45 states up to four levels deep, two regions running side by side and 72 transitions, and Omaspec draws it in about 30 ms.

It reads your diagram as behavior

A state diagram is the state machine it specifies, and a sequence diagram is a scenario, in PlantUML and Mermaid alike. Omaspec checks them while you type: a state no path reaches, a state nothing leaves, one event leading two ways with no guard to choose. A scenario is checked against the state machines of its project: every message must be an event its receiver can take, in the order the scenario sends them.

Play it

F5 runs the diagram on screen. The states the machine is in light up, you pick what happens next, and a light runs along each transition. A scenario unfolds message by message. omaspec play door.puml -o door.gif --events open,close writes such a play as a GIF, for a presentation or a pull request.

Hold a recorded trace against it

omaspec trace run.jsonl plays what a running system logged through its state machines and says where it deviated, with the time. The editor plays the trace in the diagram, line by line, and the bar turns red where the system did what the specification does not allow. omaspec coverage door.puml --traces night.jsonl -o door-cov.svg draws how much of the machine the traces took: what was taken in green with how often, what never was dashed in red; --min 80 holds a share in CI.

It looks like your Omarchy

Omaspec follows omarchy theme and omarchy font set while it runs, and draws the diagrams in the theme's colors without touching the files. Every bundled theme is checked for legible colors, the gallery's diagrams in each of them too.

And more

• Projects. omaspec new shop, or New project in the editor, makes a folder with a first diagram and omaspec-project.toml. Every diagram below it is checked against the whole project, however it was opened.
• Diagrams that link. A state links to the diagram of its name: click it and the view zooms in, Alt+Left zooms back out. A project's map is made from its diagrams: each a tile with its picture, a folder a frame, and arrows for what plays, opens and includes what; a diagram stands above the one it leads to.

• Fold and focus. Fold a nested state, a package or a subgraph to its box, and Shift+click a box to see only it, its neighbors and the lines between them.
• A layout you can steer. Drag a line or a box with Alt; the shape goes into the file as a comment and holds in any theme. skinparam handwritten true or Mermaid's look: handDrawn draws the diagram by hand, the same picture every time.
• Compare a diagram with another tab or any git commit, as pictures side by side or as changed lines. omaspec diff says what changed in the behavior: states, transitions and messages, not layout.
• Convert a state machine or scenario between PlantUML and Mermaid, only when the result means the same.
• Images that remember. Exported PNGs and SVGs carry their source; drop one on the window and it opens as a diagram again.
• Next to Neovim. omaspec preview flow.puml is a window that renders again on every save.
• For scripts and AI agents. Every check is on the command line, with JSON output and exit codes. omaspec check DIR runs them for CI, and omaspec mcp is an MCP server with the same tools.
• The same picture everywhere. A diagram is drawn byte for byte the same whatever language the system is set to; a test draws every example under five locales.
• 28 examples to start from, as tiles drawn on the spot (Ctrl+Shift+E).

Install

On Omarchy (or any Arch Linux), build the package from this repository:

git clone https://github.com/enhapu-afk/omaspec
cd omaspec/packaging/aur/omaspec-bin   # the release, prebuilt
makepkg -si                            # or in ../omaspec: the release, built from source

The packages go to the AUR (omaspec, omaspec-bin, omaspec-git) as soon as it takes new accounts again; then yay -S omaspec-bin will do.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗