Lucid

Free and open source · local-first · macOS, Windows, Linux

A structured document, built while you think.

Say or type your thoughts. Lucid arranges them as headings, lists, tables and diagrams, and typesets them. The language model runs on your own computer, so nothing leaves it.

Download Lucid View the source

macOS · Windows · Linux · free, MIT licence

The Lucid window: a page of notes with a diagram, the list of changes on the right and the input box at the bottom The Lucid window in the dark theme

The idea

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 that document while you think out loud, so you never stop to format.

You say

The browser sends API calls to a load balancer, which forwards them to the order service. It reads from Redis and queries PostgreSQL on a cache miss. We’re not going with MongoDB, PostgreSQL it is.

Lucid builds

## The request flow

Browser Load balancer Order service Redis PostgreSQL

## The database

  • PostgreSQL
  • MongoDB

What a page is made of

Typed blocks, drawn the same way every time.

The model only chooses which block fits what you said and fills it in. It never writes LaTeX or drawing code; Lucid draws and typesets the blocks, so a page looks the same however it was dictated.

## High-level design### Data model

Headings

The outline: a title, sections and sub-sections. Numbered in the PDF.

  • PostgreSQL
  • MongoDB
  • DynamoDB

Lists

Options, steps, trade-offs. Each item stands alone, so one can be crossed out, never deleted.

Tables

A comparison: properties by options. Typeset as a real table.

Client API DB

Diagrams

How parts connect: architecture, flows, sequences. A database is drawn as a cylinder, a queue as a pipe.

DecisionPostgreSQL: joins and transactions.

Callouts

The takeaway, a decision, a trade-off, a warning or an open question.

Formulas

Back-of-the-envelope maths: KV-cache size, FLOPs, bandwidth. Typeset LaTeX.

Charts

Numbers you dictated, as bars or lines, using only the numbers you said.

SELECT * FROM urls WHERE short_code = $1;

Code

An API request, a query, a shell command.

How it works

Talk, refine, export. You stay in charge.

  1. Say or type

    One input box. Dictate with Wispr Flow on macOS or Windows (optional), or just type. Your words are never lost: if the model cannot use them, they are kept as written.

  2. Lucid structures it

    A local model in LM Studio turns notes into blocks and places them under the right section.

  3. Refine by number

    “In block 3, add a row for cost.” Every change is one undo step, and any earlier change can be reverted on its own.

  4. Export

    A typeset PDF, Markdown, or a .lucid file with its history. AI agents can edit the same blocks.

Diagrams by voice

Say the parts, then the connections.

A ten-part diagram is hard to say in one breath, so there is a guided builder.

  • Say the components: “client, server, DNS, database”.
  • Then the connections: “client to server”.
  • Fix by number: “rename 3 to Cache”, “reverse 2”.
  • Tables have the same builder.
The diagram builder: numbered components and connections beside the drawing The diagram builder in the dark theme
Block numbers in the page margin; block 4, a diagram, lists its numbered parts and connections

Block numbers

Say which block you mean.

Every block has a light number in the margin. Click one to see its parts, then talk about it.

  • “In block 3, add a row for cost.”
  • “Cross out item 2 of block 6.”
  • “Rename node 2 of block 4 to Cache.”

History you can trust

Take back one change, not just the last.

The panel lists what you said and every change to the page: by Lucid, by a builder, by an AI agent. Show scrolls to what a change touched. Revert takes back that one change and leaves later ones to other blocks alone.

Claude Code02:35
Added 2 blocks
Show
Lucid02:34
Crossed out MongoDB; marked PostgreSQL chosen
ShowRevert
Command · Donejust now
cross out MongoDB, we are choosing PostgreSQL
Edit and send again
A page of the exported PDF: a numbered section, a diagram and a footer

A real PDF

Typeset, not screenshotted.

Numbered sections, real tables, vector diagrams and formulas, in a fixed house style. The PDF engine (Tectonic) comes with the app. Or export Markdown, with diagrams as Mermaid.

Made for system design, open to other fields

Start from a format, or make your own.

A note format is the skeleton of a page: its sections, a hint for each, and which blocks suit it. Dictation is placed under the section it belongs to.

Concept note

One computer-science or system-design idea.

  1. Definition
  2. Intuition
  3. How it works
  4. Example
  5. Pitfalls and gotchas
  6. Related concepts

System design

Designing a system end to end.

  1. Requirements
  2. Capacity estimates
  3. API
  4. High-level design
  5. Data model
  6. Deep dives
  7. Trade-offs and decisions
  8. Open questions

Comparison

Choosing between technologies.

  1. Context
  2. Options
  3. Comparison
  4. Pros and cons
  5. Decision

Inference engineering

KV cache, FLOPs, bandwidth, batching.

  1. Intuition
  2. The math
  3. Numbers to remember
  4. Hardware implications
  5. Pitfalls

Benchmark

Recording an experiment.

  1. Goal and hypothesis
  2. Setup
  3. Method
  4. Results
  5. Observations
  6. Next experiments

Your own

A format is a small data entry in the source: an id, a description, the sections. A lab notebook, a reading log or a study plan is one more entry.

How to add one →

Download

Install in a minute, on any of the three.

Lucid for macOS

latest

Apple Silicon · macOS 13 or newer · free and open source

Download .dmg .zip

Lucid for Windows

latest

64-bit · Windows 10 or newer · free and open source

Download installer Portable .zip

Lucid for Linux

latest

64-bit (x86-64) · Debian, Ubuntu and other distributions · free and open source

Download .deb .AppImage

SHA256SUMS · All releases · Changelog

  • Nothing else to install for PDFs: the PDF engine and diagram drawing come with the app.
  • LM Studio (for macOS, Windows and Linux) with the model qwen/qwen3.8-27b: a lot of memory; developed on 48 GB.
  • The first PDF needs the internet once, to fetch typesetting files (about five minutes).
First time you open it (macOS)

Lucid is free and not notarized by Apple, so macOS asks once:

  1. macOS 15: System Settings → Privacy & Security → Open Anyway.
  2. macOS 13 and 14: right-click the app → Open → Open.
  3. Or in Terminal:
xattr -dr com.apple.quarantine /Applications/Lucid.app
First time you open it (Windows)

Run the installer. It installs Lucid for you (no administrator needed) and starts it. Lucid is free and not signed, so Windows SmartScreen may say “Windows protected your PC”:

  1. Click More info.
  2. Click Run anyway.

To remove it later: Settings → Apps → Lucid. The portable .zip needs no install: unpack it and run Lucid.exe.

First time you open it (Linux)

Debian, Ubuntu and relatives, from the .deb:

sudo apt install ./Lucid-*-linux-amd64.deb

Any distribution, from the .AppImage:

chmod +x Lucid-*-linux-x86_64.AppImage
./Lucid-*-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.

Check the download

Each release lists SHA-256 checksums in SHA256SUMS. On macOS and Linux, in the folder with both files: 

shasum -a 256 --ignore-missing -c SHA256SUMS

On Windows, in PowerShell, then compare the result with the line for your file: 

Get-FileHash .\Lucid-*-win-x64.exe -Algorithm SHA256
Build it yourself

Needs Node 22.12 or newer and pnpm 9. Works on macOS (Apple Silicon), Windows and Linux (x64). 

git clone https://github.com/triggeredcode/lucid.git
cd lucid
pnpm install
node scripts/fetch-tectonic.mjs
pnpm dev

For AI agents

A toolbox, not just an app.

Lucid is also an MCP server. With the app running, Claude Code, or a model in LM Studio’s chat, can read and edit the same blocks with the same safe tools. Every agent change is one undo step and appears in the history as the agent’s.

The tools and the set-up →

macOS

claude mcp add lucid -e ELECTRON_RUN_AS_NODE=1 -- \
  /Applications/Lucid.app/Contents/MacOS/Lucid \
  /Applications/Lucid.app/Contents/Resources/lucid-mcp.mjs

Windows (PowerShell)

claude mcp add lucid -e ELECTRON_RUN_AS_NODE=1 -- `
  "$env:LOCALAPPDATA\Programs\Lucid\Lucid.exe" `
  "$env:LOCALAPPDATA\Programs\Lucid\resources\lucid-mcp.mjs"

Linux (.deb)

claude mcp add lucid -e ELECTRON_RUN_AS_NODE=1 -- \
  /opt/Lucid/lucid /opt/Lucid/resources/lucid-mcp.mjs

Privacy

Your notes stay on your Mac.

No account, no analytics

Lucid has no server and sends nothing about you anywhere.

A model you run

The language model runs in LM Studio on your computer. Settings refuses an address that is not local.

Plain files

Every page is one JSON file in ~/Lucid that you can back up or move. The code is MIT-licensed and open.

Questions

Good to know.

Why does macOS warn me when I open it?

Lucid is a free open-source app without an Apple developer certificate, so it is not notarized. macOS asks you to allow it once (see “First time you open it” above). The download’s checksum lets you verify what you got, and the source is public.

Do I need Wispr Flow?

No. Dictation is optional: Wispr Flow pastes your words and Lucid takes the paste. You can just type. Wispr Flow is a separate app with its own privacy terms.

Which model does it use?

Lucid is evaluated with qwen/qwen3.8-27b in LM Studio. Another model can be named in Settings, but expect more misses. A request takes 10 to 25 seconds on a laptop.

Is it only for system design?

It was made for system-design and engineering notes, but a page is just headings, lists, tables and diagrams, so it suits any subject that has that shape. Note formats are plain data you can extend.

Which systems does it run on?

macOS 13 or newer on Apple Silicon, Windows 10 or newer (64-bit) and Linux (64-bit; a .deb for Debian and Ubuntu, an AppImage for other distributions). Not yet: Intel Macs, and Windows or Linux on ARM.

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), but the Mac version has had the most everyday use. If something is off on Windows or Linux, please report it.