A structured document, built while you think.
Say or type your thoughts. Lucid arranges them as headings, lists, tables and diagrams, and typesets them.
A local-first note editor for macOS, Windows and Linux: the language model runs on your own computer.
Website · Download · User guide · Changelog
Engineers think in structure. A system design is an outline of sections and sub-sections, a list of options with the rejected ones crossed out, a table that compares them and a diagram of how the parts connect. Lucid builds exactly that document while you think out loud, so you never stop to format. It was made for system-design notes, and it is open to any subject that fits the same shapes: the note formats are plain data you can change or extend.
flowchart LR
say["You say or type<br/>'Options are Redis and Memcached…'"] --> model["A local model<br/>(LM Studio)"]
model --> page
subgraph page["A Lucid page"]
direction TB
H["Heading<br/>## High-level design"] --> SH["Subheading<br/>### Data model"]
H --> D["Diagram<br/>components and connections"]
SH --> L["List<br/>options, rejected ones crossed out"]
SH --> T["Table<br/>option against option"]
end
page --> out["PDF · Markdown<br/>.lucid file · AI agents"]
Everything on a page is a typed block. The model only chooses which block fits what you said and fills it in; Lucid draws and typesets it, so the result looks the same every time.
| Block | What it holds | How it is drawn |
|---|---|---|
| Heading, subheading | the outline: title, sections, sub-sections | numbered sections in the PDF |
| List | options, steps, trade-offs; bullets, numbered steps and checklists, each item on its own so one can be crossed out | bullets, struck-through when rejected |
| Table | a comparison: properties by options | a typeset table |
| Diagram | how parts connect: architecture, request flow, sequence, entities | drawn from components and connections, a database as a cylinder, a queue as a pipe |
| Callout | the key takeaway, a decision, a trade-off, a warning, an open question | a highlighted box |
| Formula | back-of-the-envelope maths (KV-cache size, FLOPs, bandwidth) | typeset LaTeX maths |
| Chart | numbers you dictated: bars or lines | a labelled chart |
| Code | an API request, a query, a shell command | a code listing |
What stays true whatever you say:
- The model never writes LaTeX or drawing code. It fills blocks; a fixed house style does the typography.
- You stay in charge. Every change by the model is exactly one undo step, any earlier change can be reverted on its own, and your words are never lost: if the model cannot use them, they are kept as written.
- One view. The page, one input box under it, an optional history panel. It scales to a full-screen window.
- Voice or keyboard. Dictate with Wispr Flow (optional) or just type. Lucid takes the text from there.
- A toolbox for AI agents. An MCP server lets Claude Code, or a model in LM Studio's chat, read and edit the same blocks.
Lucid runs on macOS (Apple Silicon, macOS 13 or newer), Windows (Windows 10 or newer, 64-bit) and Linux (64-bit). The website offers the right download for your computer; they are all on the latest release:
| System | Download | Notes |
|---|---|---|
| macOS | Lucid-<version>-mac-arm64.dmg (or .zip) |
Apple Silicon, macOS 13 or newer |
| Windows | Lucid-<version>-win-x64.exe installer (or the portable .zip) |
Windows 10 or newer, 64-bit |
| Linux | Lucid-<version>-linux-amd64.deb, or Lucid-<version>-linux-x86_64.AppImage |
64-bit; the .deb is for Debian and Ubuntu |
- Install it.
- macOS: open the
.dmgand drag Lucid to Applications. macOS will say it cannot check the app for malicious software, because Lucid is a free open-source app that is not notarized by Apple. Allow it once: on macOS 15 and newer, open System Settings → Privacy & Security, scroll to the message about Lucid and click Open Anyway; on macOS 13 and 14, right-click Lucid in Applications, choose Open, then Open again. Or in Terminal:xattr -dr com.apple.quarantine /Applications/Lucid.app - Windows: run the installer. It installs Lucid for you (no administrator needed) and starts it. Lucid is not signed, so Windows SmartScreen may say "Windows protected your PC": click More info, then Run anyway. To remove it: Settings → Apps → Lucid.
- Linux:
sudo apt install ./Lucid-<version>-linux-amd64.deb(then start Lucid from the menu, orlucid), or with the AppImage:chmod +x Lucid-<version>-linux-x86_64.AppImage && ./Lucid-<version>-linux-x86_64.AppImage. On Ubuntu 24.04 and newer an AppImage can stop with a sandbox message: use the.deb, or start the AppImage with--no-sandbox.
- macOS: open the
- Install LM Studio (it runs on all three systems), download the model
qwen/qwen3.8-27b, and start its local server (Developer tab). Lucid's pill at the top says what is missing and can load the model for you.
Each release lists SHA-256 checksums (SHA256SUMS). To check a download, run shasum -a 256 --ignore-missing -c SHA256SUMS in
the folder with both files (macOS, Linux), or Get-FileHash .\Lucid-<version>-win-x64.exe -Algorithm SHA256 in PowerShell and
compare. The source is here; you can build the app yourself.
Good to know
- Nothing else needs installing: the PDF engine (Tectonic) and the diagram drawing come with the app, on every system.
- The first PDF needs the internet, once. Tectonic downloads its typesetting files the first time it runs (several hundred small ones, about five minutes). Lucid does it in the background after the first start and shows the progress next to Download PDF. After that PDFs take a second or two and work offline.
- Every build is tested on GitHub's own macOS, Windows and Ubuntu machines before a release (it starts, makes a PDF with a diagram, and connects an AI agent). The Mac version has had the most everyday use: please report what is off on Windows or Linux.
- Lucid is evaluated with
qwen/qwen3.8-27bonly. Another model can be named in Settings, but expect more misses. A 27B model needs a lot of memory; Lucid was developed on a Mac with 48 GB. - On Windows and Linux the shortcuts use Ctrl where this page says ⌘ (⌘1 is Ctrl+1), and Alt where it says ⌥.
- Click New page, or New from a format… to start from one of five note formats.
- 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.
- Switch to Command (⌘2) and talk about the page: "Cross out Memcached, we are choosing the local LRU." "Add a row for cost to this table."
- Download PDF when it looks right. Edit (⌘3) is there for the few things the model gets wrong.
The full walkthrough is the user guide: Help → Lucid Guide in the app, or docs/guide.html.
| Mode | Your words are | Switch |
|---|---|---|
| Input | notes, written into the page and structured | ⌘1 |
| Command | instructions about the page: "add a CDN in front of the web server", "undo" | ⌘2, or hold the right ⌥ key for one command |
| Edit | typing in the page itself | ⌘3 |
⌘4 opens the diagram builder and ⌘5 the table builder. Changes that would throw something away wait for a yes; when Lucid is unsure which thing you mean, it asks.
A diagram of ten parts is hard to say in one breath, so there is a guided builder: say the components, then the connections ("client to server"), then fix them by number ("rename 3 to Cache", "reverse 2"). A database is drawn as a cylinder, a queue as a pipe, a CDN as a cloud, a load balancer as a hexagon. Big diagrams stay readable in the page and in the PDF.
Every block has a light number in the margin (B1, B2, …). Click one to see its parts, then say "in block 3, add a row for cost" or "cross out item 2 of block 6". The numbers can be hidden in Settings.
The panel on the right lists what you said and every change to the page: by Lucid, by a builder, by an AI agent, or a revert. Show scrolls to what a change touched. Revert takes back one earlier change, not just the last, and leaves later changes to other blocks alone.
Dictation is placed under the section it belongs to ("the options are Kafka and SQS" goes under Options). Export as:
- PDF, typeset with Tectonic in a fixed house style (numbered sections, real tables and figures, formulas);
- Markdown (diagrams as Mermaid blocks);
- A
.lucidfile, the whole note with its history, to back up, move to another computer or share.
Light and dark themes, three typefaces, and a zoom for the page (⌘+, ⌘−, ⌘0) are in the app. Pages are plain files in
~/Lucid (one JSON file per page).
A note format is the skeleton of a page: its sections, a hint for each saying what belongs there, and which blocks suit it. Start a page from one with New from a format…; Lucid suggests one from what you say, and you always choose.
| Format | For | Sections |
|---|---|---|
| Concept note | one computer-science or system-design idea | Definition · Intuition · How it works · Example · Pitfalls and gotchas · Related concepts |
| System design | designing a system end to end | Requirements · Capacity estimates · API · High-level design · Data model · Deep dives · Trade-offs and decisions · Open questions |
| Comparison | choosing between technologies | Context · Options · Comparison · Pros and cons · Decision |
| Inference engineering | KV cache, FLOPs, bandwidth, batching | Intuition · The math · Numbers to remember · Hardware implications · Pitfalls |
| Benchmark | recording an experiment | Goal and hypothesis · Setup · Method · Results · Observations · Next experiments |
The formats lean towards engineering because that is what Lucid was made for, but nothing else in Lucid does. A format is a
small data entry in packages/kit/src/formats/index.ts: an id, a description, keywords
for the suggestion, the sections and the blocks that suit them. A lab notebook, a reading log or a study plan is one more
entry. New block types (one folder each) work the same way. See CONTRIBUTING.md.
Lucid is also an MCP server. With the app running, Claude Code can read and edit your pages:
claude mcp add lucid -e ELECTRON_RUN_AS_NODE=1 -- /Applications/Lucid.app/Contents/MacOS/Lucid /Applications/Lucid.app/Contents/Resources/lucid-mcp.mjsEvery agent change is one undo step and appears in the history as the agent's. The tools, the LM Studio set-up and what can go
wrong are in docs/mcp.md.
Lucid has no account, no analytics and no cloud service. Your notes are files on your disk, and the language model runs in LM Studio on your computer. The only time Lucid's own PDF engine uses the internet is the one-time download of typesetting files described above. If you dictate with Wispr Flow, that is a separate app with its own privacy terms; Lucid only sees the text it pastes.
You need macOS (Apple Silicon), Windows or Linux (x64), Node 22.12 or newer, and pnpm 9.
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| Command | |
|---|---|
pnpm test |
unit tests (all packages) |
pnpm e2e |
Electron end-to-end tests with a fake LM Studio, in a maximized window (written and run on a Mac) |
pnpm run ci |
typecheck, lint, formatting and unit tests |
pnpm eval |
74 cases (and their variants) against the real model in LM Studio; see docs/evals.md |
pnpm dist |
builds the installers for the system it runs on into apps/desktop/release/: a .dmg and .zip (macOS), an installer and .zip (Windows), an .AppImage and .deb (Linux) |
pnpm e2e:packaged |
runs the end-to-end tests against the built app, on any of the three systems (after pnpm dist:dir) |
The repository is a pnpm workspace:
packages/core |
pure TypeScript: the document model, the op language, the guided builders, persistence. No DOM, no network. |
packages/kit |
the block kit: block types, note formats, Markdown and LaTeX output, diagram layout |
packages/llm |
the LM Studio client and the prompts |
packages/mcp |
the MCP server for agents |
packages/evals |
the eval cases and runner |
packages/mock-lmstudio |
a scripted LM Studio for tests |
apps/desktop |
the Electron app (React and BlockNote) |
Unit, integration and end-to-end tests never need LM Studio: they use the scripted server. More in
CONTRIBUTING.md and docs/architecture.md.
| You see | Do |
|---|---|
| LM Studio isn't running | Start LM Studio and its local server, then click Check again. |
| No model loaded | Click Load … in the pill, or lms load qwen/qwen3.8-27b --context-length 32768 --parallel 1 -y. |
| A request takes 10 to 25 seconds | Normal for a 27B model on a laptop; the first request after a change is the slowest. |
| Getting the PDF engine ready… | Normal on the first start: wait, it counts the files. A PDF you ask for meanwhile waits for it. |
| Words were kept as unprocessed | The model could not use them; they are kept as written. Say them again, or fix them in Edit mode. |
| Dictation does nothing | Is Lucid the focused window? A paste goes to the input box wherever the focus is in the window. |
More in the guide. Something else? Open an issue.
Issues and pull requests are welcome; read CONTRIBUTING.md first. Report security problems privately, as
described in SECURITY.md. Changes are listed in CHANGELOG.md.
MIT. Lucid is built on open-source software; see THIRD_PARTY_NOTICES.md. Special thanks
to BlockNote, Mermaid, Tectonic,
Electron and iA Writer Mono.