Onyx Writer

The problem we hit

We write a lot of governed documents — assignments, reports, specifications, decisions — and we needed them to be three things at once: readable by a person, parseable by a machine, and still there in ten years.

Every tool we tried made us give up one of the three. Cloud editors put the content in someone else's database. Note apps invented their own formats. Plain Markdown was durable but had no structure worth validating.

So we built the editor we needed, and then we started running our own operations on it.

What it does

• Visual and raw editing for Open Knowledge Format Markdown — Tiptap for writing, CodeMirror when you want to see the actual document.
• Flat-file bundles. A bundle is just a folder. There is no document database, and there never will be.
• Validation as you write, with a panel that tells you what is wrong with a document rather than refusing to save it.
• An interactive bundle graph — folders, documents, internal links, broken links, hover focus, node selection. Broken links are visible instead of discovered later.
• Local Mermaid rendering with zoom, pan, fit and reset.
• JSONM theming, so the app itself is styled by the same portable design grammar the rest of our work uses.
• Governed agent access through the onyx CLI and an onyx-mcp stdio sidecar — which is how an AI agent can write into a bundle under audit rather than editing files behind your back.

How we use it

Every document in the Active Twist project-management bundle is written through Onyx Writer — assignments, reports, reservations, this site's own architecture documents. The onyx CLI is how our agents file work, and onyx bundle validate is what stops a malformed document from entering the record.

This page was planned in a bundle Onyx Writer manages.

Where it is

Onyx Writer is a public alpha, and the alpha label is doing real work. It is genuinely useful for local bundle editing now. It is also early: keep backups of anything you care about, and expect the Open Knowledge Format surface to keep moving while the format matures.

Desktop builds are published for macOS Apple Silicon, Linux (DEB and RPM) and Windows on x64 and ARM64, with SHA-256 checksums. The macOS app is not yet signed or notarized, so macOS will warn you on first launch — we would rather say that here than have you discover it.

It is MIT licensed, and it is free.