Vela: an Electron novel-writing IDE that keeps your manuscript and your API keys on your own machine

The problem Vela targets: retrieval drift across a long serial

Serialized fiction fails in a specific way. By chapter two hundred, a character's eye colour has changed twice, a magic system rule introduced in chapter forty is contradicted in chapter ninety, and the author cannot hold the whole corpus in working memory. Chat-based writing assistants make this worse rather than better, because each session starts from a context window that is too small to hold the setting bible and too expensive to fill with it on every request. Vela's answer is a local retrieval layer: the README describes bulk import of reference novels, worldbuilding documents and character sheets, and semantic vector search that recalls the most relevant setting chunks for the chapter currently being written. The stated goal is to avoid what the README calls character collapse and forgotten settings. The audience is named explicitly: web fiction authors, indie writers and creative professionals working on long novels, with the Chinese-language README addressing 网文 authors first. That ordering matters. A tool built around a million-word corpus and chapter-by-chapter pipeline stages is not aimed at someone writing a short story in an afternoon.

The pipeline: outline, draft, rewrite, refine, review

Vela is structured as a sequence of stages rather than a single chat box. The README lists worldbuilding and setting management with cross-chapter dynamic state tracking, automatic outline generation that produces a structural skeleton, then chapter-level detailed outlines, then scene, emotion and pacing requirements for paragraphs, with support for three-act and hero's journey structures. Drafting is streaming and can be aborted mid-generation. Rewrite works either on a selected passage or across a whole chapter while preserving character and plot consistency. Refine checks grammar, typos and logical holes. Review has the model read the chapter as a reader or editor and report on pacing, character arcs and foreshadowing. The README describes these last three as a chained post-process loop: Rewrite, then Refine, then Review, run to close out each chapter. That chaining is the most interesting design decision in the project, because it means a chapter passes through three separate model calls with different prompts and different success criteria. The cost implication is direct: a chapter run through the full loop consumes roughly three times the tokens of a single draft, and the usage analytics panel described in the README is presumably where you watch that accumulate. The docs do not state whether the loop can be configured to skip a stage or run stages in parallel, so treat that as unverified.

Local RAG on SQLite: what is confirmed and what is not

The storage layer is better-sqlite3 for relational data plus what the README calls a lightweight vector engine, with all data held on the local machine and the app usable offline. The tech stack table lists OpenAI-compatible and Gemini protocols for AI integration and type-safe IPC channels between the Electron main process and the React renderer. What the README does not specify is which vector engine, what embedding model is used by default, what chunk size the importer applies, or whether the index is rebuilt from scratch on re-import. Those are the questions that determine whether a million-word import is a ten-minute operation or an overnight one, and the material does not answer them. The BYOK configuration does hint at the shape: the settings page asks you to assign different models to different tasks, listing writing, polishing and Embedding retrieval as separate slots. So the embedding model is user-supplied, which means retrieval quality is your choice and your problem. If you point the embedding slot at a model that handles Chinese poorly while your corpus is Chinese, the recall will be poor and nothing in the app will tell you why.

Getting it running: downloads, source build and model setup

Two installation paths are documented. The first is a direct download from the Releases page: a .dmg for macOS, an NSIS .exe installer for Windows, and an AppImage for Linux, which is what the cross-platform row of the feature table states. The second is a source build requiring Node.js 18 or later and pnpm 8 or later. The README gives four commands: git clone https://github.com/heider-x/vela.git, cd vela, pnpm install, pnpm dev for a hot-reloading development server, and pnpm build to package. There is a note attached to that path that matters more than it looks: building SQLite natively requires Xcode Command Line Tools on macOS and windows-build-tools on Windows. If that native build fails, nothing else works, because the RAG store and the relational store both sit on better-sqlite3. Model configuration is done in the app rather than in a config file. You open settings from the lower-left corner, go to the model configuration page, click add model, choose a provider (OpenAI, DeepSeek, Gemini, Ollama, Zhipu or custom), enter an API key and a Base URL for proxying, then assign models to the writing, polishing and embedding roles. The supported provider list also includes Anthropic Claude, MiniMax, SiliconFlow and any OpenAI-compatible endpoint. There is no environment variable or dotfile path documented for this, which means configuration lives in the app's own storage and is not trivially scriptable.

MCP support and the plugin surface you do not get

Vela integrates the Model Context Protocol, described as a way to attach custom tool servers and extend what the model can do. That is a meaningful choice for a writing app, because MCP servers are an existing ecosystem rather than a bespoke plugin format, so a tool written for another MCP client has a chance of working here. It is also the only extension mechanism the README describes. There is no documented plugin API, no scripting hook, no template language for custom pipeline stages. If you want a fourth post-process step that checks your manuscript against a house style guide, MCP is the route, and it will require you to run a separate server process. The contributing section asks that large refactors be discussed in Issues first, which is a normal request but also a signal that the internal architecture is not yet treated as a public interface. For a v0.1.0 project that is reasonable. It does mean that anything you build against Vela's internals is exposed to change between releases.

Where Vela is the wrong tool

The GPL-3.0 licence is the first hard boundary. The README states the terms plainly: you may run, study, share and modify the code, but any new software you distribute based on your modifications must also be released under GPL-3.0. If your plan is to fork Vela into a closed-source commercial writing product, the README points you to the author for a separate commercial licence rather than granting one. That is a licensing conversation, not a technical one, and it is worth having before you invest engineering time. The second boundary is scale and form. A writer producing a 5,000-word short story gains almost nothing from a million-word vector index, and pays the setup cost of a native SQLite build and an embedding model assignment for no benefit. The third is that the project is early. v0.1.0, dated 2026-04-21, is the only release listed in the material, and the last push to the default branch is 2026-09-07. There is no stated deprecation policy, no migration guide between versions, and no documented schema for the SQLite store. Anyone whose manuscript lives only inside that store is taking on a risk the documentation does not address.

How Vela differs from a general-purpose writing app

The obvious comparison is a general-purpose editor with an AI sidebar, and the difference is not the chat panel. It is that Vela assumes a structured project: worldbuilding entries, character records with state that changes across chapters, an outline tree that descends from skeleton to chapter to scene-level pacing notes, and a retrieval index over all of it. A general editor stores prose and maybe a notes folder. The consequence is visible in the workflow. In Vela, generating a chapter means the outline stage has already produced scene and emotion requirements, and the drafting call receives those plus whatever the vector search recalled. In a general editor, you paste your setting notes into the prompt each time and hope the context window holds them. The trade-off runs the other way too. Vela's structure is opinionated, and the README describes it in terms of three-act and hero's journey templates. If your novel does not decompose into chapters with scene-level beats, you are working against the data model rather than with it. A plain Markdown editor with a retrieval plugin would let you keep your own structure and pay only for the retrieval layer.

Maintenance cost and what to watch between releases

Two dependencies drive the ongoing cost. The first is the native SQLite binding. Every Electron major upgrade, every Node version bump and every change to the packaging toolchain is a chance for better-sqlite3 to need a rebuild, and the README's own note about Xcode Command Line Tools and windows-build-tools tells you the project already knows this is the fragile step. The second is the provider list. Vela speaks OpenAI-compatible and Gemini protocols plus MCP, so a provider that changes its request shape or deprecates a model name can break a configured task slot without any change to Vela itself. The usage analytics panel will show you the token spend, but nothing in the material suggests it warns you when a configured model has been retired upstream. On the licence side, GPL-3.0 means the source of any distributed derivative must be offered under the same terms, and the README invites contact for closed-source commercial licensing. That is the author's stated position, not legal advice, and anyone building a product on this code should read the LICENSE file and take their own counsel. For an individual author running the app locally, none of the distribution obligations are triggered.

Editorial conclusion

Adopt Vela if you write long serialized fiction, already hold API keys for OpenAI, DeepSeek, Claude, Gemini or a local Ollama instance, and want your worldbuilding corpus retrieved from a SQLite file on your own disk rather than uploaded to a hosted writing service. Do not adopt it if you need a stable plugin surface, a hosted collaboration mode, or permissive licensing for a closed-source derivative; v0.1.0 is the only release listed, so treat the API and data format as unsettled. Before committing a manuscript to it, verify three things: that the better-sqlite3 build succeeds on your machine (macOS needs Xcode Command Line Tools, Windows needs windows-build-tools), that your chosen embedding provider is reachable from the settings page, and that the export path out of the SQLite store produces files you can read without Vela. If the export path is not documented for your target format, keep your source text in plain files alongside the app.

Official sources

1. heider-x/vela on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases