heider-x/vela: an AI novel writing IDE that keeps your drafts and API keys on your own machine

The problem Vela targets: a novel outgrows the context window

A chat window is fine for a short story. It falls apart somewhere around the point where your cast list, your magic system, and forty chapters of prior text no longer fit in one prompt. Authors who write serialized web fiction hit that wall early, because the format rewards consistency across hundreds of chapters and punishes a character whose eye colour changes in chapter sixty.

Vela is aimed at exactly that author. The README describes it as an IDE for long-form novel writing, web fiction, and creative writing, built around a local RAG knowledge base that holds imported reference novels, worldbuilding documents and character sheets. During drafting, the app retrieves the most relevant chunks and feeds them to the model alongside your outline. The claim is not better prose. It is fewer contradictions.

The second audience is the privacy-minded one. The README states that all data and model calls run on your own computer with your own API key, a model it calls BYOK. That framing matters for authors under exclusive contracts, or anyone who does not want an unpublished manuscript sitting in a vendor's training pipeline.

How the pipeline works: outline, draft, rewrite, refine, review

The workflow is staged rather than conversational. According to the README, you first define worldbuilding, the main plot axis, and character profiles with state tracked across chapters. From there the app generates a structural skeleton, then chapter-level outlines, then per-scene requirements covering pacing and emotional beats. Narrative structures such as three-act and hero's journey are listed as options.

Drafting is streamed chapter by chapter, and the README says generation can be aborted at any point. After a chapter exists, three post-processing stages run in sequence: rewrite, refine, review. Rewrite can target a selected passage or the whole chapter while trying to hold character and plot consistency. Refine looks for grammar errors, typos and logic holes. Review has the model read the chapter as an editor or reader and flag pacing, character arc and foreshadowing problems.

The architecture underneath is visible in package.json. The desktop shell is Electron with Vite, the UI is React with Zustand and Radix primitives, and the editor layer pulls in both CodeMirror packages and Monaco. Storage is better-sqlite3 for relational data plus @lancedb/lancedb and apache-arrow for the vector side, which is what the README means by a lightweight vector engine. Model access goes through OpenAI-compatible and Gemini protocols, with MCP support for external tool servers.

One design choice is worth flagging. Splitting storage between SQLite and LanceDB means two stores to keep in sync, and the README does not describe a reindex command or what happens to embeddings when you switch embedding models. That is a real gap at v0.1.0.

Installing Vela and running a first chapter

The README offers two paths. The first is a direct download from the Releases page: a .dmg for macOS, an NSIS .exe for Windows, and an AppImage for Linux. The second is a source build, which the README says needs Node.js 18 or newer and pnpm 8 or newer.

git clone https://github.com/heider-x/vela.git
cd vela
pnpm install
pnpm dev

Running pnpm dev starts the Vite dev server with hot reload. The README adds a caveat for the source path: building better-sqlite3 needs native toolchain prerequisites, Xcode Command Line Tools on macOS and windows-build-tools on Windows. There is also a rebuild script in package.json for exactly that native module:

pnpm rebuild

Packaging a distributable uses pnpm build, which chains tsc, vite build and electron-builder. If you only want to write, take the download path and skip the toolchain entirely.

Configuration happens inside the app, not in a config file. The README describes it as: open the app, click the settings gear in the lower left, go to the model configuration page, then add a model. You pick a provider (OpenAI, DeepSeek, Gemini, Ollama, Zhipu, or a custom endpoint), enter the API Key and Base URL, and assign different models to different jobs: writing, polishing, and embedding retrieval. That last assignment is the one to get right, because retrieval quality depends on the embedding model, and the README does not say what happens if you leave it unset.

Once a model is assigned, the practical first run is small: create a project, write a short worldbuilding note, import one reference document, then generate an outline before asking for a chapter. Starting with a full novel before confirming that retrieval returns sensible chunks is the fastest way to waste tokens.

Where Vela will frustrate you

The version number is the first thing to weigh. The only release listed is v0.1.0, dated 2026-04-21. The last push to the master branch was on 2026-09-07, so work is ongoing, but a single tagged release means there is no upgrade history to learn from and no evidence about how the project handles breaking changes to its on-disk format.

Native modules are the second friction point. better-sqlite3 and @lancedb/lancedb both compile or ship platform binaries, and the README's own note about Xcode Command Line Tools and windows-build-tools signals that source builds will fail on machines without a C++ toolchain. Electron apps that embed native database engines also tend to break across Electron major upgrades, and the README does not describe a migration path.

The third issue is cost opacity. Vela is local-first, but unless you point it at Ollama, every draft, rewrite, refine and review call leaves your machine and bills your provider. The README mentions a usage analytics panel tracking calls, tokens and cost trends, but it does not give any guidance on what a full novel pipeline costs. A three-stage post-process on every chapter multiplies token spend in a way that a single chat prompt does not.

Finally, the documentation is thin on failure modes. The README does not document rollback, does not explain how to re-embed the knowledge base after changing embedding models, and does not describe what happens to in-flight generation if the API returns an error mid-stream. Treat v0.1.0 as software to trial on a side project, not as the only copy of a manuscript under contract.

Vela versus a general-purpose AI writing assistant

The obvious comparison is a hosted AI writing tool or a chat interface bolted onto a word processor. Those products generally keep your project in their cloud, run retrieval server-side, and bill a subscription rather than per-token API costs. The difference in approach is not the model. It is where the state lives.

With a hosted assistant, your character bible and chapter history sit in someone else's database, and the retrieval index is their problem to maintain. You get zero setup, working sync across devices, and no native build step. You give up the ability to run offline, and you accept that the vendor decides which model reads your draft.

Vela inverts that. The README states that data is stored in a local SQLite database with a local vector engine, and that the app works with the network disconnected. Your manuscript is a file on your disk. You choose the provider per task, so you can draft with DeepSeek, polish with Claude, and run a privacy pass through a local Ollama model, which is a combination no single hosted product offers.

The cost of that control is everything the hosted product hides: API keys to manage, embedding models to pick, a native build to keep working, and no sync between your laptop and your desktop. Vela is the better fit when the manuscript is the asset you care about protecting. It is the worse fit when you want to open a browser and write.

Licence and the cost of keeping it running

Vela is GPL-3.0. The README is explicit about the practical consequence: you may run, study, share and modify the code, but a distributed derivative must also be released under GPL-3.0. The README also notes that closed-source commercial licensing is available by contacting the author.

For an individual novelist this is close to irrelevant. You are not distributing the software, so the copyleft obligations do not attach to your manuscript. For anyone planning to fork Vela into a paid product, or to embed it in a commercial writing service, the licence is the deciding factor and the author's contact route is the one to use. This is a description of what the README states, not legal advice; a lawyer should read the actual LICENSE file before you build a business on it.

Upgrade cost is the other ongoing expense. Because there is one release and no documented migration procedure, every future version carries the risk that your SQLite schema or vector index needs rebuilding. The knowledge base is the expensive part to reconstruct, since re-importing and re-embedding a million words costs both time and embedding API calls. Keeping your source documents in a folder outside the app is the cheap insurance.

Editorial conclusion

Adopt Vela if you write long serialized fiction, already pay for an LLM API key, and want your setting notes and drafts to stay in a local SQLite file rather than a hosted account. Skip it if you need a stable, documented tool with a migration story, or if you want a hosted editor you can open on a borrowed laptop. Before committing a manuscript, verify two things yourself: that your provider's embedding endpoint works with the retrieval model you select, and that the packaged build for your OS is present on the Releases page, since the README points there rather than documenting a package-manager install.

Frequently asked questions

Official sources

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