Lumina Note: An Electron Markdown Vault With an opencode Agent Inside
Lumina Note - A modern Markdown note-taking app with live preview, bidirectional links, and AI assistant
At a glance
- What is it?
- Lumina Note pairs a plain-Markdown workspace with an embedded opencode agent that can act across your whole vault. The promise is human-editable notes plus AI that can actually touch them, and the cost is a build pipeline that depends on a second repository.
- Who is it for?
- Adopt Lumina Note if you want a plain-Markdown vault on disk and you are willing to configure a model provider yourself, and if you can live with the opencode bundle step when building from source. Do not adopt it if you need a stable plugin API today, since the README labels the plugin system developer preview, or if you expect the app to ship a model.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 33 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap Lumina Note is aimed at
Most Markdown editors treat AI as a sidebar that drafts text into the current buffer. The README frames Lumina Note against that: notes stay human-owned and human-editable, while an agent gets to work inside the same workspace. The project description calls it a Markdown note-taking app with live preview, bidirectional links and an AI assistant, and the topics list adds local-first, wikilinks, knowledge-graph and pdf-reader to the picture.
The intended user is someone who already keeps a folder of Markdown files and does not want to hand that folder to a service. The README's first bullet is explicit that the vault is plain Markdown on disk and can be opened, edited, moved and backed up without Lumina or any model provider. That is a stated design constraint, not a marketing line, and it shapes everything else: the agent has to operate on files the user can read, not on a proprietary store.
The secondary audience is people who want an agent that can act across many notes rather than one. The README lists drafting pages, reorganizing folders, summarizing PDFs, connecting related notes, generating flashcards and cleaning up messy knowledge as agent tasks. Those are multi-file operations, which is a different class of feature from autocomplete.
How the agent actually reaches your files
The architecture visible in the README is layered. The shell is Electron 41. The renderer is React 18 with TypeScript, and the editor is CodeMirror-based; the README credits codemirror-live-markdown as the editor core. On top of that sits an embedded opencode server, and the agent layer is built on that server plus the opencode SDK. Lumina's job, per the README, is mapping app settings, vault access and the permission flow into that runtime.
That mapping is the interesting part. The agent is not a thin HTTP call to a chat endpoint. It is a runtime that receives vault access through Lumina, which means the permission flow is the boundary between the model and your files. The README describes the agent as able to read, write, reorganize, summarize, connect and research notes across the vault when you ask it to, and the phrase with your permission appears in the project description.
What the README does not specify is the granularity of that permission flow: whether it is per-session, per-file, or per-tool-call is not stated in the supplied material. Anyone evaluating this for a sensitive vault should read docs/agent-runtime-setup.md, which the README points to for the opencode setup, before assuming a particular granularity.
The knowledge surfaces are separate from the agent. WikiLinks, backlinks, graph views, PDFs, annotations, images and flashcards are described as normal workspace surfaces rather than hidden AI-only state. That distinction matters if you want to inspect what the agent did without opening the agent.
Getting it running from a release versus from source
The release path is short. Download the build from Releases, choose a local folder as your vault, then open Settings -> AI and configure a provider. The README lists OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Moonshot Kimi, Zhipu GLM, MiMo, Groq, OpenRouter, Ollama, OpenAI-compatible endpoints, and optional Lumina Cloud. Packages are an .exe NSIS installer for Windows, .dmg or .zip for macOS on Apple Silicon and Intel, and an .AppImage for Linux x64.
The source path has a step that will trip people up. Requirements are Node.js 22 or newer, npm, and Bun, with Bun needed only for building the embedded opencode server bundle. The setup is a clone of Lumina-Note, npm install, then a second clone of the opencode repository into thirdparty/opencode, a bun install inside it, and npm run opencode:bundle. The README states plainly that this is required before npm run dev can resolve virtual:opencode-server. Skip it and the dev server will not start with a useful error.
Beyond that, the command list is conventional: npm run typecheck, npm run test:run, npm run build, then npm run stage:native and the platform packaging commands dist:mac, dist:win and dist:linux. Two of these are worth noting for CI work. typecheck and test:run are separate, so a pipeline that only runs tests is not checking types. And stage:native sits between build and packaging, which suggests native artifacts are staged rather than produced by the build itself.
Where the design gets in your way
The plugin system is the clearest limitation in the material. The README calls it a developer-preview plugin system, and lists agent skills and custom commands alongside it as extension points. Developer preview means the interface can change between releases, and the release cadence visible in the repository is fast: v1.4.9, v1.4.10 and v1.4.11 all landed within about three days at the end of May 2026. A plugin written against v1.4.9 has had two releases to survive by the time v1.4.11 shipped. That is not a reason to avoid the app, but it is a reason not to build a workflow that depends on plugin internals yet.
The second constraint is the opencode dependency. Building from source means cloning a second repository and running Bun inside it. If opencode's layout changes, the Lumina build breaks in a way that has nothing to do with Lumina's own code. The README treats this as a setup step rather than a vendored dependency, which keeps the two projects in sync but puts the coupling in your build environment.
The third is model dependence. The app ships no model. Every AI feature is gated on you configuring a provider or holding a Lumina Cloud license. If you want a note app that works the same on day one with no configuration, this is the wrong shape of tool: the editor works, the agent does not, until you finish Settings -> AI.
There is also a mobile surface the README mentions only in passing, pointing to mobile/README.md for native iOS and Android companions. Nothing in the supplied material describes what those companions can do, so treat them as unverified.
How this differs from Obsidian and from a plain editor
The topics list includes obsidian-alternative, so the comparison is invited. The meaningful difference is not the feature list, which overlaps heavily (Markdown files on disk, WikiLinks, backlinks, graph view). It is that Lumina embeds an agent runtime with vault write access as a first-class part of the app, built on opencode and its SDK, rather than leaving multi-file editing to a plugin or an external tool. Obsidian's model is a core app plus a large third-party plugin ecosystem; Lumina's is a smaller core with the agent inside it and a plugin system still in developer preview.
Against a plain editor like VS Code with a Markdown extension, the difference is the knowledge layer. Backlinks, a graph view, PDF annotations and flashcards are workspace surfaces here rather than separate tools glued together.
Against a hosted AI note service, the difference is where the files live. Lumina's stated position is that the vault is plain Markdown on disk and readable without Lumina or any provider. A hosted service cannot make that claim, because the note store is the service.
None of these comparisons establish that Lumina is better. They establish what you are choosing between: an integrated agent with vault access and a young extension API, versus a mature extension ecosystem with the agent outside it.
Maintenance, releases and the licence
The repository is not archived and the last push recorded is 2026-08-13, roughly two and a half months after the v1.4.11 release on 2026-06-01. The three most recent releases are patch-level bumps clustered at the end of May 2026, which is consistent with active maintenance rather than a rewrite in progress. Two GitHub Actions workflows are referenced in the README badges: ci.yml and security-audit.yml. The presence of a security audit workflow is a signal about process, not about the security of the agent permission flow, which is the thing that actually matters here and which the README does not detail.
The licence is Apache-2.0. That is a permissive licence with an explicit patent grant, and it is the same licence family used by many desktop applications. It permits commercial use and modification. It also means there is no copyleft obligation if you fork and redistribute. This is a description of the licence text, not legal advice; if you plan to redistribute a modified build, read the LICENSE file in the repository and, where it matters, get your own counsel.
The upgrade cost is the part to budget for. Fast patch releases plus a developer-preview plugin API plus a build that depends on a separately cloned opencode repository means version pinning matters more than usual. If you build from source, record the commit you cloned into thirdparty/opencode, because the README's instructions clone the default branch rather than a tag.
Who should install it, and what to check first
Install it if you already keep a Markdown folder and you want an agent that can act across that folder rather than inside one file, and if you are comfortable pointing the app at your own provider or running Ollama locally. The local-first framing is backed by a concrete claim in the README: the vault is plain Markdown you can read and back up without Lumina. That claim is checkable in an afternoon.
Do not install it if you need a frozen plugin API, if you want the AI features to work without configuring a provider, or if you are unwilling to read docs/agent-runtime-setup.md before granting an agent write access to a vault you care about. The developer-preview label on the plugin system and the three-releases-in-three-days cadence at the end of May 2026 are both reasons to wait if extension stability is your priority.
Before you move a real vault in, verify three things in this order. First, from a source checkout, confirm that npm run opencode:bundle followed by npm run dev actually resolves virtual:opencode-server; that single step is the most likely place for a fresh setup to fail. Second, configure one provider in Settings -> AI and confirm a single read-only agent request works before you let it write. Third, read docs/agent-runtime-setup.md and docs/plugin-ecosystem.md to find out how permissions are scoped, because the README does not say. If the permission model turns out to be coarser than your vault requires, the plain-Markdown guarantee still holds, but the agent is the part you would be switching off.
Editorial conclusion
Adopt Lumina Note if you want a plain-Markdown vault on disk and you are willing to configure a model provider yourself, and if you can live with the opencode bundle step when building from source. Do not adopt it if you need a stable plugin API today, since the README labels the plugin system developer preview, or if you expect the app to ship a model. Before committing a real vault, verify three things: that npm run dev resolves virtual:opencode-server after you run npm run opencode:bundle, that your chosen provider works from Settings -> AI, and that the permission flow gives you a chance to review agent writes before they land on disk.
Community notes