Setup Guide

What is bookmoth?

A desktop writing app for novels and long-form non-fiction. You bring your project, your voice, and your own AI provider. bookmoth learns how you write and keeps everything it produces within your style.

Take the weight out of the first draft with a guided brief and AI-drafted chapters, or import an existing manuscript and use bookmoth for editorial feedback, planning, and revision. Either way, you stay in control with a sidekick that knows what you're trying to do.

bookmoth doesn't include an AI model. You connect one (Anthropic, OpenRouter, Ollama, or LM Studio) and pay the provider directly. A full novel typically costs under $5 in usage. This guide walks you through setup.

Installing bookmoth

Connecting an AI provider

bookmoth doesn't come with an AI built in, and that's on purpose. Think of bookmoth as the studio: the desk, the drafting, the voice work, the planning. The AI is the engine that does the actual generating, and you bring your own. You choose which one, and you can swap it whenever you like.

This is also why bookmoth is a one-time purchase with no subscription. You pay your AI provider directly for what you use, usually a few dollars for a whole novel, and nothing more to us than the app itself. Your key, your account, your spend, all in your hands.

There are two kinds of provider, and you only need one to begin:

Pick whichever suits you and follow its section below. You only need one to start.

You can also have the best of both. Hybrid mode keeps your chapter drafts on Claude, where quality matters most, and sends the lighter work (planning, summaries, quick edits) to a cheaper or local model. You get Claude-grade prose where it counts and a much smaller bill everywhere else. See Hybrid mode below.

Setting up Anthropic (Claude)

Anthropic's Claude models produce the highest quality output. This is the recommended setup for serious drafting.

Setting up OpenRouter

OpenRouter gives you access to multiple AI models (Claude, GPT, Gemini, open-source models) through a single API key. Often cheaper than direct Anthropic access.

Setting up Ollama (local, offline)

Run AI models entirely on your machine. No internet needed, no API costs. Requires a reasonably powerful computer (16GB+ RAM recommended).

Setting up LM Studio (local, offline)

LM Studio provides a visual interface for downloading and running local models. Good if you prefer a GUI over the command line.

Using Hybrid mode

Hybrid mode splits your API calls between Anthropic and your Custom Endpoint based on how demanding the task is. Quality-critical work stays on Claude. Everything else runs through your cheaper or local provider.

Heavy tasks always use Anthropic (Claude): chapter drafting, writing profile generation, editor chat, polish and voice revision. These are the calls where output quality matters most.

Medium and light tasks try your Custom Endpoint first: scene generation, chapter summaries, codex extraction, inline edits, slash commands. If the custom endpoint fails or is unreachable, bookmoth silently falls back to Anthropic. You never see an error.

Advanced model routing

For most users, the standard routing modes (Cloud, Hybrid, Custom) are all you need. Advanced routing is for writers who want finer control over which model handles which type of task.

In API / LLM settings, click Advanced model routing below the mode selector. This opens a panel where you can assign a different model to each of bookmoth's three task tiers:

Leave any tier blank and it uses your default model from the main settings. This means you only need to fill in the tiers you want to override.

A common setup for local users running Ollama: assign a large model like qwen2.5:72b to Heavy, a mid-size model like qwen2.5:14b to Medium, and a fast model like llama3:8b to Light. Same endpoint, three different models, each matched to the task.

The advanced panel also includes a timeout setting. bookmoth sets sensible defaults per provider (2 minutes for OpenRouter, 30 minutes for local models), but you can override it here if you need more or less time.

Your first project

Once your AI provider is connected, you're ready to start.

The Editor

The Editor is the chat panel on the right side of the Brief tab. It's a guided conversation that helps you build and refine your project. Think of it as a developmental editor on call.

The Editor can see your whole project, the brief, writing profile, chapter plan, scene breakdowns, the Codex, and any chapter you load for review, and it can talk about any of it. When it proposes changes to a document, it summarises what it wants to do and asks for confirmation before applying anything.

You can use the Editor at any stage of your project:

The CodexBeta

The Codex is your story bible: the characters, places, objects, and lore that make up your world. It keeps track of who is who, and feeds the right details to the AI as you write, so your cast stays consistent from the first chapter to the last. Crucially, it does most of the building for you, and it only sends the AI what each chapter actually needs.

This section is the long version: how the Codex works, what every toggle does, and the handful of habits that keep it accurate. If you read one part, make it the risk of accepting everything.

Where to find it

The Codex is one of the main tabs along the top of a project (it's labelled Codex on novels, Research on shortform pieces). Open it and you get a workbench: type tabs across the top, your entries listed beneath, and the selected entry open for editing on the right. The type tabs are Characters, Places, Objects, and Lore, so a large cast stays sorted.

Screenshot to addimages/screenshot-codex-workbench.pngThe Codex tab: type tabs (Characters / Places / Objects / Lore), the entry list, and an entry open on the right.

It builds itself

You don't have to fill in forms. After you draft or import a chapter, bookmoth reads it and suggests new entries and updates: a character who just appeared, a place that was named, a detail that changed. The suggestions collect in a review queue. You accept, edit, or reject each one. Nothing is added to your Codex without your say-so. The point is to spare you the bookkeeping, not to take the decisions away from you.

Two things drive this: Auto-scan new drafts, which reads each chapter as you draft it, and the Scan chapters… button, which reads chapters on demand. Both are covered below. Both only ever propose. They never write to the Codex directly.

What an entry holds

Every entry has a name, a type (character, place, object, or lore), and a description. For most entries, that's all you need. The description is the part the AI reads most, so keep it tight and current. When you want more, an entry can also carry:

• Aliases. Nicknames, first names, titles. bookmoth recognises a character however you refer to them, so "Marty", "Mr Cleaver", and "Martin" all point to the same person. Aliases also drive mention detection (see below) and they're the fix for duplicates: if bookmoth ever creates two entries for the same character (say "Barnaby" and "Barnaby Trewint"), add the shorter name as an alias on the main entry, then delete the duplicate.
• Details. Structured facts, like a character sheet: Appearance, Personality, Voice, Background, Arc, plus any rows you add yourself. Each detail has its own AI-visible switch, so you can keep, say, a Voice note that the AI uses while hiding a Background note that's just for you. Add only what's useful.
• Relations. Links to other entries. Link a captain to their ship, and whenever the captain is pulled into a chapter, the ship comes along too (one level deep, so the ship's own relations don't cascade in).
• Tags. Your own labels for filtering and grouping entries. Tags are for you. They're never sent to the AI.
• Research. Notes you want to keep but never want the AI to see. Spoilers, scratch ideas, things you're still deciding. Never sent, whatever an entry's other settings say.

Screenshot to addimages/screenshot-codex-entry.pngOne character entry open, showing name, description, aliases, the detail rows, and the AI-visibility control.

When the AI sees an entry: the send setting

You don't want every entry sent to the AI on every chapter. That wastes context and money, especially on smaller local models with tight context windows. So each entry has one setting that decides how often it's handed to the writing AI:

You set this once per entry and largely forget it. The default, Send when mentioned, is right for the great majority of entries.

Screenshot to addimages/screenshot-codex-visibility.pngClose-up of the Send always / Send when mentioned / Never send control, with the Auto-detect toggle visible beside it.

Auto-detect vs Send when mentioned

These two get confused, so here's the difference plainly.

Send when mentioned is the policy: it says "only include this entry in chapters that actually feature it." Auto-detect is the mechanism that powers that policy: it's how bookmoth decides whether an entry is featured. With Auto-detect on (the default for any "when mentioned" entry), bookmoth watches the chapter's plan, its summary and scene beats, for the entry's name or any alias, matching whole words only. Find a match, include the entry. No match, leave it out.

Turn Auto-detect off and the entry stays on "Send when mentioned", but bookmoth stops watching the text for it. In practice that means the entry only rides into a chapter when it's a relation of another included entry. You'd do this when a name is too common to match cleanly:

• A character literally called Will, Hope, May or Art, where the name collides with ordinary words and would otherwise pull the entry into chapters that never feature the character.
• A place called The Bridge or The Wall, same problem.
• An entry you only ever want to appear alongside a specific character, handled through a relation rather than its own name.

So: Send when mentioned decides whether bookmoth includes entries by mention at all; Auto-detect decides whether this particular entry takes part in that. Most entries leave both on and never think about it.

The two Codex-wide toggles

At the top of the Codex, next to the Scan button, sit two switches that apply to the whole project rather than a single entry:

• Auto-scan new drafts (on by default). After bookmoth finishes drafting a chapter, it quietly reads that chapter and drops any new entries or updates into the review queue. You'll see the "suggestions to review" count tick up. Nothing is saved until you accept it. Turn this off if you'd rather scan manually, or to keep things quiet while you draft a long run of chapters.
• Pause mention tracking (off by default). When paused, bookmoth stops auto-including entries based on mentions across the whole project. Entries set to Send always still go. This is a temporary lever for cutting context and cost, or for troubleshooting, not something to leave on, since it switches off the behaviour that keeps your cast consistent.

Screenshot to addimages/screenshot-codex-toggles.pngThe Codex toolbar: the "Scan chapters…" button, the "Auto-scan new drafts" and "Pause mention tracking" checkboxes, and the review pill.

Scan chapters

Scan chapters… is the manual version of auto-scan, for when you want to read a batch of chapters in one go. Click it and bookmoth opens a picker listing every chapter that has enough text to read. Tick the ones you want (Select all and Deselect all are there), and it reads each in turn.

Under the hood, a scan makes one AI call per chapter, on the medium task tier, reading the real prose (or, for an imported project with no drafts yet, the chapter's continuity notes). It returns two kinds of suggestion: brand-new entries, and updates to entries you already have. Everything lands in the review queue. As with auto-scan, nothing is written to the Codex until you accept it.

The most useful single moment to scan is straight after importing an existing manuscript: one pass seeds your whole Codex from prose you've already written.

Screenshot to addimages/screenshot-codex-scan.pngThe "Scan chapters" dialog with the chapter checklist and Select all / Deselect all.

The review queue

Suggestions don't touch your Codex. They wait in the review queue, shown as a "N suggestions to review" pill. Open it and they're sorted into two groups: New entries and Updates to existing entries. For each one you can edit the name, type and description in place, then Accept or Reject it. There's an Accept all and a Reject all if you'd rather move fast.

Two details worth knowing, because they explain the section that follows:

• Accepting a new entry adds it to your Codex, defaulting to "Send when mentioned" unless you change it in the row.
• Accepting an update appends the new text to the existing entry's description. It does not replace what's there. So updates accumulate, which is good for building a picture and bad if you accept things you haven't read.
• Conflict flags. When a scan thinks a new fact contradicts something already recorded, the row carries a "May contradict existing" note. That's your cue to look closely before accepting.

Screenshot to addimages/screenshot-codex-review.pngThe review modal: New and Updates groups, an editable row, a "May contradict existing" badge, and Accept / Reject buttons.

The risk of accepting everything

The review queue is fast, and "Accept all" is tempting. But accepting every suggestion without reading it is the main way a Codex goes wrong, and because the Codex feeds the writing AI, a messy Codex quietly degrades your drafts. Here's what tends to happen, and the fix for each:

None of this needs much effort. Review in small batches, read the conflict flags, and spend ten seconds on anything that updates an entry you care about. That's the whole discipline.

When to scan

You don't need to scan constantly. Each scan costs one AI call per chapter, and re-scanning a chapter you haven't touched just re-proposes things you've already judged. Scan when there's something new to read:

• Right after importing a manuscript. The single highest-value scan. It seeds the Codex from your existing prose in one pass.
• After drafting with Auto-scan off, or after writing or heavily editing a chapter by hand.
• After a round of revisions, to catch facts that changed: a renamed character, a moved location, a rule you reworked.
• From the brief, before you write a word. The Editor can offer to seed your Codex straight from the project brief, so your core cast exists before chapter one.

If Auto-scan new drafts is on and you're drafting normally, you may rarely press Scan at all. It's there for imports, hand-written chapters, and catching up after big changes.

Writing a series

If you're writing the second (or third, or fourth) book in a series, bookmoth can carry context forward from previous books. The easiest way to set this up is through the Editor.

When you start a new project, tell the Editor it's a sequel. Something like "this is book 2 in a series" or "I'm continuing from my previous novel" is enough. The Editor will ask you about what happened in the previous book, the world you've established, any continuing plot threads, and which characters are returning. It populates the series context fields and returning characters for you automatically.

You don't need to fill anything in manually. Just have the conversation and the Editor does the rest.

If you prefer to do it yourself, expand the Series Context card in the Brief tab and enable it. You'll see three text fields:

Returning characters are managed in the Codex. Add characters from previous books with their descriptions, and they're visible to the AI when drafting.

Windows notes

bookmoth is independent software, not distributed through the Microsoft Store. Windows will show a SmartScreen prompt the first time you run it. This is normal for any new, independently distributed application.

To install: click More info on the SmartScreen prompt, then click Run anyway.

bookmoth is safe, built on open-source infrastructure, and stores everything locally on your machine.

Troubleshooting

Things go wrong sometimes. Here's what's likely happening when they do.

The model stops before finishing

When a chapter rewrite or a long generation comes back cut off, the AI model has hit its own output limit. Different providers and tiers have different caps on how much they'll write in one response.

What to try:

• Use shorter chapters. Splitting a 4,000-word chapter into two 2,000-word chapters often works around the limit.
• Check your provider's max output setting. Some providers (OpenRouter, Zhipu, others) let you raise the cap in their dashboard or by upgrading your plan.
• Try a different model. Different models, even on the same provider, can have very different output limits. Anthropic's Claude models can typically write a full chapter in one response.

The model refuses to write something

Some AI models are trained to refuse content they classify as sensitive. This can include anything involving violence, illness, sex, drugs, politics, religion, or other flagged topics, even when it's part of a novel or memoir. The refusal often shows up as a generic "I can't help with that" message, or something like "this content is sensitive, please try a new topic."

This isn't bookmoth blocking your work. It's the AI model you've connected.

What to try:

• Try a different model. GLM and some restricted Llama variants tend to be the most aggressive about refusals. Mistral, Mixtral, and uncensored Llama variants (Hermes, Dolphin) are typically more permissive. Anthropic's Claude handles the full range of literary fiction including dark themes.
• Rephrase what you're asking for. Sometimes a small change in how a note or instruction is worded gets a different result. Not always, but worth a try.
• Split the chapter into smaller passages and edit them one at a time. Some filters fire on context size as much as content.

Connection or provider errors

If you see a "provider error" message, the AI service itself returned an error. Common causes:

• Invalid API key. Re-check the key you've pasted in bookmoth's API settings.
• Wrong endpoint URL. Most OpenAI-compatible endpoints end in /v1/chat/completions. The setup sections above show the correct URL for each provider.
• Model name unrecognised. The model field needs to match the exact ID your provider uses (e.g. zhipu-ai/glm-5, not glm5 or GLM-5).
• Rate limit hit. Wait a minute and try again. If it's persistent, your provider may be limiting you due to high usage or low balance.
• Network issue. Check your internet connection.

Getting help

If you run into anything, email support. It goes directly to Stu, the founder. You'll get a real answer, usually the same day.