Lucid

Voice to structured notes and diagrams.
Talk, and Lucid builds the headings, lists, tables and diagrams while you think, then typesets a PDF.
Made to work hands-free or one-handed, and local-first: the language model runs on your own computer.

Website · Download · User guide · Changelog

Why I made it

For a while I couldn't type comfortably, so I built Lucid for myself: a productivity and accessibility tool for taking notes and
learning system design by voice, or with one hand.

I learn by thinking out loud and want to see it as I say it: the diagram when I explain a system, the notes taking shape, and a
way to cut what I got wrong. I couldn't find one open-source project that turns speech into something structured, so I built it.

This first version doesn't listen by itself. You dictate with an app that pastes text, like Wispr Flow,
OpenWhispr or VoiceNative (my own,
for macOS), and Lucid turns what lands in the box into the page.

How it works

flowchart LR
  you["You, by voice or keyboard"] --> box["The input box"]
  box --> model["A local model in LM Studio<br/>(for example Qwen 3.8)<br/>sees the page and its history"]
  model --> page["Blocks on your page:<br/>headings, lists, tables, diagrams"]
  page --> history["The history keeps what you said,<br/>what was understood, what changed"]

The model runs on your own computer, because you talk a lot and change a lot, and a local model keeps that cheap. It always has
the page in front of it, so it puts what you said under the right heading and builds the right kind of block. Every change is one
undo step, and your words are never lost.

Diagram mode: keywords, connections, editing

A diagram of ten parts is hard to say in one breath, so a guided builder has three phases: the keywords (the parts), the
connections (how they link, one at a time) and editing (everything is numbered, so a fix is one sentence: "rename 3 to
Cache"). Say "done" and the diagram goes onto your page. A database is drawn as a cylinder, a queue as a pipe, a CDN as a
cloud.

1. Keywords

2. Connections

3. Editing

Command mode: talk to the page

The model has the whole page in context, so you can talk about it: "add a cache in front of the database", "cross out
Memcached, we are choosing the local LRU", "add a row for cost to this table", "undo". A crossed-out idea stays on the page,
struck through. Hold the right ⌥ key and everything you say is one command, which works with one hand.

History, edit mode and how well it works

The history keeps what you said and what changed, so you can see why a page looks the way it does, take back any single change,
or edit what you said and send it again. When the model gets something wrong, Edit mode lets you type in the page.

I score the model on my own set of cases (docs/evals.md) with a bar of 90%; the latest run got 98 of 99. To get
the most from it, say things in short pieces, use diagram mode for diagrams and command mode to change the page.

Keep your notes

• PDF, typeset on your computer with real diagrams; Settings → PDF look sets paper, type, margins and accent colour, and you
  can edit the template.
• A whole note, with its history, to back up or move, and Markdown.
• Three note formats (concept note, system design, comparison) or a blank page; formats are plain data. See them.
• The page has its own light and dark, apart from the app's.

Start from a format, or a blank page	Export a whole note, with its history
A dark page in a light app (the first picture is the other way round)

Built-in MCP server

An AI agent such as Claude Code can read your pages and add to them. Each change is one undo step and shows in the history as the
agent's. Tools and set-up: docs/mcp.md.

Install

Get them from the latest release or the
website, which picks the right one for your computer. The apps are free and
not signed, so macOS and Windows ask once before opening them; the steps, the checksums and the model set-up are in
docs/install.md. You also need LM Studio with the model qwen/qwen3.8-27b.

Quick start

1. Click New page, or New from a format… to start from one of three note formats, or from a blank page.
2. Type or dictate notes in the box at the bottom: "A cache hit costs microseconds, a miss costs a database round trip.
   Options are Redis, Memcached and a local LRU." They appear on the page, structured, a few seconds later.
3. Switch to Command (⌘2) and talk about the page: "Cross out Memcached, we are choosing the local LRU."
4. Download PDF when it looks right.

To dictate, use any app that pastes text: Wispr Flow,
OpenWhispr (free, open source) or
VoiceNative (free, macOS). See docs/dictation.md.

Learn more

Contributing

Issues and pull requests are welcome. Set-up, the commands, the rules the code keeps, and how to add a note format or a block
type are in CONTRIBUTING.md; security problems go through SECURITY.md. Changes are listed in
the changelog.

git clone https://github.com/triggeredcode/lucid.git
cd lucid
pnpm install
node scripts/fetch-tectonic.mjs   # the PDF engine, checked against a pinned SHA-256
pnpm dev

Licence

MIT. Lucid is built on open-source software; the list of what it bundles and their licences comes with the app
(Help, Licences of the Software Lucid Uses). Special thanks to BlockNote,
Mermaid, Tectonic, Electron
and iA Writer Mono.