# Lumina Note: a Markdown vault where an opencode agent does the editing > Lumina Note is an Electron 41 desktop Markdown app that pairs a CodeMirror editor with an embedded opencode agent. It is for people who want plain files on disk and an AI that can act across the whole vault. **blueberrycongee/Lumina-Note** — Lumina Note - A modern Markdown note-taking app with live preview, bidirectional links, and AI assistant - Repository: https://github.com/blueberrycongee/Lumina-Note - Stars: 918 · Forks: 94 - Language: TypeScript - License: Apache-2.0 - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/blueberrycongee-lumina-note ## The problem Lumina Note solves, and who it is for Most Markdown editors treat AI as a sidebar that rewrites the paragraph under your cursor. Lumina Note takes the opposite position. The README describes a vault that stays "human-owned and human-editable" while an embedded agent, built on the opencode SDK, can "read, write, reorganize, summarize, connect, and research notes across the vault" once you grant permission. The unit of work is the vault, not the selection. That distinction decides who the app is for. If your notes are already a folder of .md files with `[[WikiLinks]]` between them, and the tedious part is not typing but maintenance (renaming a concept across forty files, turning a folder of PDFs into linked summaries, finding the two notes that should have been one), the agent model matches the job. If you mostly want fast text entry and a preview pane, the agent layer is machinery you will pay for in setup time and model configuration. The README is explicit that the vault is plain Markdown on disk and readable, editable, movable and backable-up "without depending on Lumina or any model provider." That is the strongest claim in the document, and it is a design commitment rather than a feature: no proprietary database sits between you and the files. ## How the agent layer is wired into an Electron app The architecture is visible in the repository layout and the README's developer section. Lumina Note is an Electron 41 desktop application with a React 18 and TypeScript renderer, and the editor is CodeMirror-based. The README names the editor core as a separate project, codemirror-live-markdown, and the agent runtime foundation as opencode. Lumina's own contribution is the mapping layer: it translates app settings, vault access and the permission flow into the opencode runtime. That last sentence is the part worth reading twice. The agent is not a chat window bolted onto the editor. It runs as an embedded opencode server, which is why the build instructions require cloning opencode into `thirdparty/opencode`, installing its dependencies with Bun, and bundling it before `npm run dev` can resolve the `virtual:opencode-server` module. A note-taking app that needs a separate agent server bundle is a different class of software from a text editor. Model routing is deliberately open. The README lists OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Moonshot Kimi, Zhipu GLM, MiMo, Groq, OpenRouter, Ollama, OpenAI-compatible endpoints, and an optional Lumina Cloud if you hold a licence. Knowledge surfaces stay in the workspace rather than inside the model: WikiLinks, backlinks, graph views, PDFs, annotations, images and flashcards are all described as normal app surfaces. There is also a self-hosted relay documented in `docs/self-host.md`, and the repository ships `docker-compose.selfhost.yml` and `docker-compose.hosted.yml` alongside a `cloud/` directory and a Rust server under `server/`. ## Installing Lumina Note and running a first agent task The README's Download section points to GitHub Releases rather than a package registry, so installation is a download, not a package-manager command. Windows gets an `.exe` NSIS installer, macOS Apple Silicon and Intel get `.dmg` or `.zip`, and Linux x64 gets an `.AppImage`. There is no Homebrew, winget or apt line documented, and the README does not describe an auto-update mechanism. The Quick Start is five steps: install from Releases, choose a local folder as your vault, open Settings -> AI and configure a provider, create a note with a `[[WikiLink]]` and open the graph, then open the AI panel and ask the agent to work on a note or folder. The provider step is the one that will stop you if you skip it. The README lists Ollama as a supported route, which keeps the model on your machine: ```bash ollama serve ollama pull llama3 ``` After that, point Settings -> AI at the Ollama endpoint instead of a hosted API key. The README does not print the exact base URL the app expects, so check the field in the settings panel rather than copying a value from elsewhere. Building from source is heavier. Node.js 22+ and npm are required, and Bun is required specifically for the embedded opencode server bundle: ```bash git clone https://github.com/blueberrycongee/Lumina-Note.git cd Lumina-Note npm install # Required before npm run dev can resolve virtual:opencode-server. git clone https://github.com/anomalyco/opencode thirdparty/opencode (cd thirdparty/opencode && bun install) npm run opencode:bundle npm run dev ``` If you only want to use the app, the release build avoids all of this. The source route exists mainly for plugin and agent-runtime work, and the README points to `docs/agent-runtime-setup.md` for the runtime details. ## Where Lumina Note gets in your way The permission model is the honest constraint. An agent that can "read, write, reorganize" across a vault is an agent that can rename your files and rewrite your notes. The README frames this as operating "with your permission," but it does not document an undo history for agent actions, a dry-run mode, or a way to diff a batch of proposed edits before they land. If your vault is not under version control, the first thing to do is put it under Git, because that is the rollback mechanism the documentation does not provide. The plugin system is labelled developer preview in the README. Anyone choosing Lumina Note for its extensibility should treat that as a moving target, not a contract. The same caution applies to the mobile story: the repository contains a `mobile/` directory and `mobile/README.md`, and the README links it, but the download table lists only Windows, macOS and Linux. Android and iOS companions are not presented as shipped artifacts in the same way. Finally, the hosted path is not free of setup. Lumina Cloud is described as requiring a licence, and the self-hosted relay has its own documentation and Compose files. If you want zero infrastructure, the local-model route through Ollama is the shorter path, at the cost of running inference on your own hardware. ## Lumina Note versus Obsidian, and what actually differs The repository tags include `obsidian-alternative`, so the comparison is invited. The overlap is real: both are local Markdown vaults with WikiLinks, backlinks and a graph view, and both keep files readable outside the app. The difference is what sits on top. Obsidian's extension model is a large plugin ecosystem with a documented API, and its AI features arrive through third-party plugins. Lumina Note ships the agent in the box, running on an embedded opencode server, with the app itself responsible for mapping vault access and permissions into that runtime. That is a deeper integration and a narrower one: you get an agent that knows the vault as a first-class object, and you depend on one project's agent runtime rather than on a plugin you can swap out. The README's own developer-preview label on the plugin system underlines the trade. A second difference is the built-in surface area. PDFs, annotations, images and flashcards are described as workspace features rather than plugins. If your workflow is mostly Markdown plus a couple of community plugins, Obsidian's maturity is the safer bet. If the thing you keep wanting is an assistant that can act on the whole vault, Lumina Note is built around that and Obsidian is not. ## Licence, maintenance and the cost of upgrading Lumina Note is Apache-2.0, which permits commercial and private use, modification and redistribution, and includes an explicit patent grant. The practical consequence for a note-taking app is that you can fork it, ship it internally, or vendor parts of it without a copyleft obligation on your own code. Apache-2.0 also requires that you keep the licence and notice files and state significant changes when you redistribute. That is a summary of the licence text, not legal advice. The licence covers the application. It does not automatically cover the components the README lists as separate open source projects, codemirror-live-markdown and opencode, which carry their own terms. Nor does it cover model providers: your API keys, your Ollama setup, and any Lumina Cloud licence are separate arrangements. On maintenance, the last push to the repository was on 2026-08-13, and the most recent release listed is v1.4.11 on 2026-06-01. The version in `package.json` matches at 1.4.11. Upgrades follow the release channel: download the new build from Releases, or rebuild from source. The repository carries `CHANGELOG.md`, and the `prebuild` script runs `scripts/sync_version.mjs`, which keeps the app version in step with the package version. Because the vault is plain Markdown, upgrading the app does not migrate your data, which is the main reason the upgrade cost stays low. ## Conclusion Adopt Lumina Note if you want plain Markdown on disk and an agent that can reorganise, summarise and link across the vault, and if you are willing to configure a provider yourself. Skip it if you need a stable plugin API, since the README labels the plugin system developer preview, or if you do not want a model to hold write access to your notes. Before committing a real vault, install the build from Releases, point Settings -> AI at Ollama or an OpenAI-compatible endpoint, and confirm the permission prompt appears before the agent writes to a file. ## FAQ ### What is Lumina Note used for? It is a local-first Markdown note-taking app with live preview, WikiLinks, backlinks and graph views, plus an embedded opencode agent that can read, write, reorganize, summarize and connect notes across the vault when you ask it to. ### Is Lumina Note a company, or just an app? The material describes Lumina Note as an open source desktop application under the Apache-2.0 licence, built by the blueberrycongee project. It does not describe a company behind it. ### What is the Lumina AI app? The README presents Lumina Note as a Markdown workspace with an agent built on the opencode SDK layered on top for vault-wide work, while the vault itself stays plain Markdown on disk. ### What is Lumina AI in Lumina Note? It is the embedded agent runtime. The README says Lumina maps app settings, vault access and the permission flow into opencode, and that you can route it to OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Moonshot Kimi, Zhipu GLM, MiMo, Groq, OpenRouter, Ollama, OpenAI-compatible endpoints, or an optional Lumina Cloud licence. ## Sources - [blueberrycongee/Lumina-Note on GitHub](https://github.com/blueberrycongee/Lumina-Note) - [Issues](https://github.com/blueberrycongee/Lumina-Note/issues) - [License: Apache-2.0](https://github.com/blueberrycongee/Lumina-Note/blob/main/LICENSE) - [README](https://github.com/blueberrycongee/Lumina-Note/blob/main/README.md) - [Releases](https://github.com/blueberrycongee/Lumina-Note/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/blueberrycongee-lumina-note