The journey
How OpenLucid gets built, step by step, including the wrong turns.
- 31 October 2026 · Done
Day 0: a name and a skeleton
- Open source (MIT), everything local, sound cues only, no medical claims.
- The name: OpenLucid.
- Four parts: backend (FastAPI), app (Flutter), web view (Vue), website (Hugo).
- Checkpoint 00: the app and the server wave at each other.
- 1 November 2026 · Connected
Day 1: the headband on the table
- The app works with any EEG source: the Muse first, Fake Moose for everyone without one.
- The Muse S connects over Bluetooth on Windows; Windows pairing is not needed.
- The first signal was chaos, and the headband was lying on the table.
- Lesson: check the simplest explanation first.
- 1 November 2026 · Solved: it was contact
Day 1, part 2: what bad contact looks like
- Our code was fine: every packet arrived and was decoded correctly.
- A sensor that doesn’t touch skin acts as an antenna and catches the 50 Hz hum from the walls.
- Our first explanation (the reference sensor) was wrong.
- Dampening only the forehead fixed only the forehead: contact, not code.
- 1 November 2026 · Built
Day 1, part 3: can the headband see my eyes?
- Contact score with a clear target: under 25 µV of wiggle is 100%.
- Eye check: an 18-second guided test for blinks and left/right eye movements.
- Tested with a Fake Moose that follows the prompts (passes) and one that ignores them (fails).
- 1 November 2026 · Open problem
Day 1, part 4: contact doesn't stay, and what research says about eyes
- Contact faded within about 15 minutes as the skin dried.
- The eye check now checks contact first and saves its recording.
- Research: the gold standard for eye signals is EOG, with electrodes beside the eyes.
- 1 November 2026 · Finding
Day 1, part 5: blinks yes, left and right no
- With good contact: blinks 3 of 3, left and right 0 of 4.
- Two wrong assumptions in our own code, found in the saved recording and fixed.
- A Muse S forehead barely sees sideways eye movements, so we need sensors beside the eyes.
- Checkpoint 01 is tagged.
- 1 November 2026 · Done
Day 2: the Diary Keeper grows up
- One backend, two ways to run it: SQLite on a laptop (nothing to install), PostgreSQL on a server (Docker).
- Accounts with consent, secure sign-in, export and delete; every user sees only their own data.
- Raw EEG goes into files, not into the database; the app can upload twice without creating duplicates.
- Built by 13 AI agents in six phases; 14 review findings, each proven with a failing test and fixed; 381 tests pass.
- 1 November 2026 · Tested
Day 3: testing everything
- Eight test agents ran 122 checks from outside: 105 passed, 4 failed and 13 could not be tested, each with a reason.
- 16 bugs, 2 of them medium: a broken link on the website, and a server error on deeply nested JSON. No data leaked between users.
- The server survives restarts without losing anything, but says ‘awake’ while its database is down.
- Each agent got its own tool, its own test accounts and its own evidence folder, and tests that disturb others ran last.
- Both medium bugs and five low ones were fixed the same evening, each with a test; seven small ones are listed as open.
- 2 November 2026 · Plan
Day 4: planning the first real night
- Everybody moves in their sleep, turns over and lies on their side. That’s normal, and the recording has to cope with it.
- The Muse S has an accelerometer and a gyroscope (52 samples per second). OpenLucid will record them next to the EEG.
- Movement is marked, not deleted: every 30-second epoch gets a movement score, a position-change flag and a quality label.
- The first night is recorded locally and saved in the research standard (BIDS-EEG with EDF+). Syncing to the server comes next.
- 2 November 2026 · Built, tested with Fake Moose; first real night tonight
Day 4b: building the night recorder
- Start night writes one EDF+ file as it goes: 4 EEG channels at 256 Hz, accelerometer and gyroscope at 52 Hz, and the events as annotations.
- Every 30 seconds: contact per sensor, movement, position change and a quality label, in epochs.tsv.
- A Bluetooth dropout becomes a marked gap, the app reconnects by itself, and the computer is kept awake.
- MNE, the tool most sleep research uses, opens the files exactly as intended. Tested end to end in the real Windows app.
- Four mistakes on the way, one of them a real bug that a flaky test found.