lumi

A local-first, Markdown-based note-taking system with a Go TUI client, Go HTTP/WebSocket server, and Svelte 5 web client. The filesystem is the single source of truth — no database, just markdown files with YAML frontmatter.

Documentation: lumi-note.vercel.app/#/docs

Architecture

┌─────────────────┐          ┌──────────────┐
│   TUI Client    │          │  Web Client  │
│ (Go + Bubbletea)│          │  (Svelte 5)  │
└────────┬────────┘          └──────┬───────┘
         │                          │
         │ direct R/W               │ HTTP + WebSocket
         │ + optional WS            │
         │                          │
         │        ┌─────────────────┘
         │        │
         │  ┌─────▼───────────┐     ┌─────────────┐
         │  │   Go Server     │◄───►│ Peer Servers │
         │  │  REST + WS Hub  │     │  (optional)  │
         │  └─────────┬───────┘     └─────────────┘
         │            │
         └──────┬─────┘
                │
       ┌────────▼──────────┐
       │    Filesystem     │
       │  Markdown + YAML  │
       │   frontmatter     │
       └───────────────────┘

Features

• Local-first: Notes are plain markdown files on disk — yours forever
• TUI client: Vim keybindings, inline image rendering, 12 built-in themes, external editor integration
• Web client: CodeMirror editor with vim mode, real-time sync, media embeds (video, PDF, YouTube, Vimeo)
• Real-time sync: WebSocket-based live updates between server and clients
• Peer federation: Multiple server instances can sync via LUMI_PEERS
• Wiki-links: [[note-id]] linking between notes
• Media support: Images, video thumbnails (ffmpeg), PDF, and embed rendering

Repository Structure

Each component lives in its own repo, linked here as git submodules:

Clone

git clone --recurse-submodules [email protected]:ViniZap4/lumi.git

If you already cloned without --recurse-submodules:

git submodule update --init --recursive

Prerequisites

Optional (TUI media rendering):

The TUI tries renderers in order: Kitty protocol > iTerm2 protocol > timg > chafa > viu. Install at least one for inline image previews.

Quick Start

Docker Compose (recommended)

cp .env.example .env    # edit LUMI_PASSWORD before starting
docker compose up -d

# Web UI: http://localhost:3000
# API:    http://localhost:8080

VITE_LUMI_SERVER_URL is baked at build time. After changing it, rebuild: docker compose build web

TUI Client (standalone)

cd tui-client
go build -o lumi
./lumi ../notes          # pass notes dir as arg, or set LUMI_NOTES_DIR

Server (standalone)

cd server
LUMI_ROOT=../notes LUMI_PASSWORD=secret go run main.go

Web Client (standalone)

cd web-client
npm install
npm run dev              # http://localhost:5173

Environment Variables

Server

Web Client

Docker Compose

Note Format

---
id: my-note-id
title: My Note Title
created_at: 2026-02-16T10:00:00Z
updated_at: 2026-02-16T10:00:00Z
tags:
  - example
---

# My Note Title

Your content here with **markdown** formatting.

Link to other notes: [[other-note-id]]

Notes are auto-generated with an id derived from the title (lowercase, non-alphanumeric chars replaced with hyphens).

API Overview

All REST endpoints require X-Lumi-Token header (or ?token= query param). WebSocket uses ?token= query param.

License

MIT

Credits

Built with Bubbletea, Svelte, CodeMirror, and Go.