Setup Guide

Everything you need to get bookmoth running, from first install to first chapter.

Use bookmoth ink for a managed connection, or connect your own provider with Lifetime.

What is bookmoth?

A desktop writing app for novels and long-form non-fiction. You bring your project and your voice, and choose the AI connection that suits you. 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.

Use bookmoth ink without a separate AI account or API key. With a Lifetime licence, you can also use your own Anthropic or OpenRouter account, a local model, or a compatible custom endpoint. AI usage is separate from your licence payment. This guide walks you through the options.

Installing bookmoth

Purchase bookmoth from the store. You'll receive a serial key by email. Download the latest version from the download page.

Open the installer. On macOS, open the .dmg and drag bookmoth to Applications. On Windows, run the .exe installer.

Enter your serial key on first launch. This is the key from your purchase email. One key per machine. You can transfer it later from the settings.

Choose your AI connection. Use bookmoth ink or, with Lifetime, your own provider or local model. You can write and edit your own words without an AI connection.

Updates. When a new version is available, bookmoth will let you know. Download and install it over the top. Your serial key, projects, and all settings carry across automatically. See what’s new in the latest release.

Connecting AI

bookmoth ink handles the AI connection and payment through your prepaid ink balance. No separate AI account or API key is needed. With a Lifetime licence, you can instead connect your own cloud provider or a model running on your computer.

Your licence pays for the app. Ink pays for AI help when you draft, edit or plan; writing your own words uses no ink. With your own key, your chosen provider bills you directly at its rates. Usage depends on the task, chapter length, book context and settings.

If you choose your own connection, there are two kinds:

Cloud models (Anthropic, OpenRouter). The highest quality, nothing to install, pay only for what you use. Best for serious drafting. Anthropic's Claude is what we recommend for voice.

Local models (Ollama, LM Studio). Run entirely on your own computer: free to use, fully private, no internet required. Ideal if you want everything offline or under your own roof. They need a capable machine, and quality depends on the model you run.

Follow the ink section or your own provider's section below. You only need one connection to start using AI.

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.

AI is optional. The Editor and AI chapter drafting use your selected connection. You can work on your manuscript, plan and Codex without making an AI request.

How ink works

Ink pays for the AI help you use in bookmoth, without needing a separate AI account or API key. Plus includes ink; Lifetime lets you buy packs whenever you need them, or use your own AI connection instead.

What uses ink?

Drafting, revising, analysing your writing and asking the editor questions use ink. Writing and editing by hand, reading your book and saving your work do not.

How much can I do with the free trial?

Your seven-day Plus trial includes 2,250 ink. For a sense of scale, one of our Balanced drafting tests produced a 5,200-word chapter using 297 ink.

Your allowance can be shared across drafting, editing, planning and analysis. How far it goes depends on the model you choose, how much text the AI needs to read and how much you ask it to produce. The chapter example is one measured result, not a fixed price or a typical-user average.

How far does the monthly ink go?

Plus includes 6,000 ink each paid calendar month, on monthly or yearly billing. At around 300 ink per Balanced chapter draft, that is roughly 20 drafts if you spend the allowance entirely on drafting. Analysis, editor conversations and other AI tasks use the same balance.

Treat this as a guide, rather than a fixed chapter allowance. Longer context and more demanding model choices can use more ink. You can check your balance and recent usage in Settings.

Does working with an existing manuscript use more ink?

It can. Asking the AI to analyse or discuss a long manuscript involves more reading than starting with a short brief or a few pages. A smaller project can leave more of your ink available for drafting and replies.

bookmoth can reuse recently processed context, so follow-up questions about the same unchanged chapter may use less ink. This is called caching. The saved context lasts for up to an hour between uses and can refresh when reused. The saving depends on the task: new text, substantial edits, a different model or returning after the cache expires can require fresh processing. Each new answer still uses ink.

Simply opening and reading your manuscript yourself uses no ink.

What happens if I run out?

Your writing stays available, and you can keep writing and editing by hand. To continue using AI, add an ink pack in Settings: 7,500 ink for $10 or 20,000 for $25, in USD. Packs are available with either Lifetime or an active Plus subscription.

Plus monthly ink refreshes on the first of each calendar month at 00:00 UTC and does not roll over. Your first payment brings the included allowance up to the month's 6,000-ink total; trial ink already used in that calendar month counts towards it. Yearly billing supplies the same monthly allowance, rather than a year's ink upfront.

Purchased ink never expires, but does not extend Plus app access beyond your subscription. Plus app access requires an active subscription. Your seven-day trial receives one trial allowance, even if it crosses into a new month.

Getting connected and checking your balance

Activate your licence, open Settings > Connection, choose bookmoth ink and turn on Use bookmoth ink. Choose Save or Done to keep the connection.

Balanced, Best quality and Fastest choose the AI used for chapter drafts, polish and your writing profile. More writing options contains separate Editor, planning and quick-edit choices. Settings shows estimated ink per chapter; editing, planning and other AI tasks also use ink.

Settings shows your balance and any daily limit. To add ink, choose a pack and complete checkout in your browser. Wait for the purchase confirmation in Settings. If you paid and ink has not arrived, use Check now or email support@bookmoth.app with your receipt. Please do not buy the same pack again.

Ink requests pass through our relay to Anthropic. The relay keeps balance and usage records without logging or storing your prose, prompts or replies. Read the AI and privacy details before choosing your connection.

Setting up Anthropic (Claude)

With a Lifetime licence, you can connect your own Anthropic account and pay Anthropic directly for AI usage. bookmoth ink already uses Claude without a separate Anthropic account.

Go to console.anthropic.com and create an account if you don't have one.

Navigate to API Keys and create a new key. Copy it.

In bookmoth, open Settings > Connection > Your own AI account and choose Anthropic. Under Which connection to use, choose Anthropic for everything.

Paste your API key and save.

Cost. Anthropic bills your own-key usage at its current rates. Cost depends on the model, input context and answer length. Check your spend and account limits in your Anthropic dashboard.

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.

Go to openrouter.ai and create an account.

Navigate to Keys and create a new API key. Copy it.

In bookmoth, open Settings > Connection > Your own AI account and choose OpenRouter.

bookmoth supplies the default OpenRouter endpoint:

https://openrouter.ai/api/v1/chat/completions

Enter the model name in the model field. Use the OpenRouter model ID, e.g. zhipu-ai/glm-5, anthropic/claude-sonnet-4, or deepseek/deepseek-r1. You can find model IDs on the OpenRouter models page.

Paste your OpenRouter API key. Under Which connection to use, choose OpenRouter for everything and save.

Which model? For fiction writing, zhipu-ai/glm-5 offers excellent voice fidelity at a fraction of the cost of Opus. See the model field in bookmoth's API settings to set your preferred model per project.

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).

Install Ollama from ollama.com.

Open Terminal (macOS) or Command Prompt (Windows) and pull a model:

ollama pull llama3

Start the Ollama server if it's not already running:

ollama serve

In bookmoth, open Settings > Connection > On this computer and choose Ollama.

bookmoth supplies the default Ollama endpoint:

http://localhost:11434/v1/chat/completions

Enter your model name exactly as it appears in Ollama. To check, run ollama list in terminal and use the name from the left column (e.g. llama3, mistral, qwen2.5).

No API key is needed. Under Which connection to use, choose Ollama for everything and save.

Using a HuggingFace model? Ollama and LM Studio aren't a separate catalogue, they're runtimes. Download a model from HuggingFace (the GGUF build, which most popular finetunes have) and load it into Ollama or LM Studio, then point bookmoth at it. Anything you can run locally, bookmoth can talk to.
Which model? bookmoth's tasks vary in complexity. Writing profile generation, chapter drafting, and editor chat are heavy calls that need a capable model, 30B parameters or larger recommended. Lighter tasks like scene planning and inline edits work fine with smaller, faster models. If you're getting errors or garbled output on profile generation, try a larger model. Sketch mode is designed for smaller models.
Timeouts. Local models can be slow on large prompts. bookmoth gives Ollama calls 30 minutes by default, so it won't cut out on you. You can adjust this in the advanced model routing panel. A cancel button is always visible during generation if you want to stop early.

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.

Download LM Studio from lmstudio.ai.

Search for and download a model inside LM Studio (the Discover tab). You can paste a HuggingFace model ID here to fetch it directly.

Go to the Developer tab and click Start Server.

In bookmoth, open Settings > Connection > On this computer and choose LM Studio.

bookmoth supplies the default LM Studio endpoint:

http://localhost:1234/v1/chat/completions

Enter the model name as shown in LM Studio's Developer tab (it appears at the top of the server panel once loaded).

No API key is needed. Under Which connection to use, choose LM Studio for everything and save.

Model size matters. Writing profile generation and chapter drafting are heavy calls. If you're getting errors, try a larger model (30B+ parameters). Smaller or "flash" variants work well for lighter tasks and Sketch mode but may not handle the bigger prompts. bookmoth gives LM Studio calls 30 minutes by default, and you can cancel at any time during generation.

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. This hybrid choice can retry lighter tasks on Anthropic if the other connection fails. Both connections may therefore incur usage charges. Choosing the other provider for everything does not fall back to Anthropic.

Open Settings > Connection > Your own AI account, choose Anthropic and add your key.

Select a provider tab (OpenRouter, Ollama, LM Studio, or Custom) and enter your model name and API key if needed.

Click Test connection on both Anthropic and your custom endpoint to verify they're working.

Under Which connection to use, select Anthropic for the heavy work and save.

Cost savings. Roughly 70% of bookmoth's API calls are medium or light tasks. Running those through a local model or a cheaper provider like OpenRouter can significantly reduce your Anthropic bill while keeping your chapter drafts on Claude.

Advanced model routing

For ink, use the quality choices and More writing options described above. With your own connection, the standard routing choices are usually enough. Advanced routing lets you assign a model to each kind of task.

In Settings > Connection, choose your own connection and open Advanced model routing. You can assign a different model to each task tier:

Heavy tasks: chapter drafting, writing profile generation, editor chat and polish. These need careful reading, reliable instructions and room for a long answer. Test a representative task; model size alone does not guarantee the result.

Medium tasks: scene generation, chapter summaries, codex extraction, brief drafting. Structured output that needs good reasoning but not frontier-level prose. 14B+ parameters recommended.

Light tasks: inline edits, slash commands, quick classification. Speed matters more than depth. 7B+ parameters is fine.

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.

Fallback. When everything runs on your chosen endpoint, failures stay with that connection and are not retried on Anthropic. Only Anthropic for the heavy work can retry lighter tasks there, using your Anthropic key.

Your first project

You can begin with your own writing, notes and plan. Connect ink or your own provider when you want AI help.

Let the Editor guide you. You can fill in the brief, series context, and chapter plan manually, but the Editor is designed to walk you through it. Just have a conversation about your project and it builds everything for you. It's faster and usually produces richer results than typing into fields directly.

Create a new project from the sidebar. Give it a name.

Talk to the Editor. The Brief tab opens a guided conversation. Tell the Editor about your novel: premise, characters, tone, world. The more you put in here, the better your chapters will be.

Add your writing examples. Click Writing Examples and paste in a few pages of your own prose. bookmoth analyses this to build your voice profile.

Generate your writing profile. Once you have a brief (at least 500 words) and writing examples, bookmoth creates a long-form voice profile that governs every draft.

Plan your chapters. Use the Chapter Plan tab to create your structure, or let the Editor help you map it out.

Write. Select a chapter in the Manuscript tab and click Write Chapter. Your first draft will be governed by your brief and your voice profile.

Bringing an existing manuscript? You can import a .md, .txt, or .docx file. Make sure each chapter starts with "Chapter 1", "Chapter 2" etc. on its own line. Markdown headings (## Chapter 1) work too. Coming from Scrivener? Compile to Plain Text using the default preset.

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:

Early on: describe your premise, characters, tone. The Editor asks follow-up questions to deepen your brief. The richer this gets, the better everything downstream works.

Chapter planning: ask the Editor to map out your chapter structure. It outputs chapter titles, summaries, and act assignments directly into your chapter plan.

Mid-project: need to change a character's arc, adjust tone, or restructure? Tell the Editor. It makes surgical edits to the relevant documents without rewriting everything else.

When you're stuck: ask it what to do next. It knows where you are in the project and points you at the next sensible step.

After drafting: use "Ask the Editor" on any chapter for editorial feedback: pacing, voice, structure, dialogue, whatever you want a second opinion on.

The Editor sees everything. Your brief, writing profile, chapter plan, and Codex are all visible to the Editor in every conversation. You don't need to re-explain context between sessions.

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.

The Codex is in active development. It's the focus of bookmoth's current update, so expect it to keep growing. Everything below describes how it works today.

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.

Screenshots
The Codex workbench The Codex workbench
Screenshot to addimages/screenshot-codex-workbench-light.pngThe Codex tab: type tabs (Characters / Places / Objects / Lore), the entry list, and an entry open on the right.
The Codex workbench. Type tabs along the top, entries listed, the selected entry open for editing.

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. It also understands the ends of a full name on its own: "Barnaby" and "Mr Trewint" both count for Barnaby Trewint without you adding either as an alias. Aliases are still the fix for duplicates: if bookmoth ever creates two entries for the same character, add the shorter name as an alias on the main entry, then delete the duplicate.
  • A timeline of dated facts. The big one; it gets its own section below. In short: facts that know which chapter made them true, so the AI never learns a twist early.
  • 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.
A single Codex entry open for editing A single Codex entry open for editing
Screenshot to addimages/screenshot-codex-entry-light.pngOne character entry open, showing name, description, aliases, the detail rows, and the AI-visibility control.
A single entry. Name and description at the top, with aliases, details, relations, tags, and research below.

The timeline: facts with dates

A story bible has a problem an encyclopedia doesn't: things change. A character is poor in chapter one and rich in chapter nine, missing in chapter three and found in chapter six. Write all of that into one description and the AI reads all of it at once, wherever it happens to be drafting.

So every entry carries a timeline of dated facts. Each fact knows the chapter that made it true. When bookmoth drafts chapter two, it only sees the facts the story has established by chapter two: everything later stays sealed until the writing gets there. Facts with no date, the timeless ones, are always true and always sent. A fact can also replace an earlier one ("scar over her left eye" replaces "unmarked face"), and the AI is told what changed and when.

You can add facts by hand, but mostly they arrive on their own: chapter scans propose them, dated to the chapter they came from, and you accept or reject each one in the review queue. Every fact has its own hidden switch, its own date you can change, and a little arrow that jumps you to the chapter it happened in.

Got an entry with a wall-of-text description from the old way of working? Press Split description into timeline facts… under the description. bookmoth reads it, proposes the dated facts hiding in it, and offers to trim the description down as you accept them, with your timeless character notes left in place. Nothing changes until you accept it, fact by fact or all at once.

An entry's timeline of dated facts An entry's timeline of dated facts
Screenshot to addimages/screenshot-codex-timeline-light.pngAn entry's timeline: timeless facts, then facts grouped under the chapter that made them true.
Barnaby Trewint's timeline. Timeless facts first, then dated facts grouped by the chapter that made them true.

In the book: an entry's journey

Above the timeline sits a row of dots, one per chapter. Solid means the entry appears in that chapter's prose. Hollow means it sits that chapter out. Dashed means the chapter isn't written yet. A small number above a dot counts the facts placed there. Click any dot and you get the chapter, what changes for the entry there, and a jump straight to the page. It's the fastest way to answer "where was she last seen?" without leaving the Codex.

The chapter-by-chapter dot row, with a chapter's popover open The chapter-by-chapter dot row, with a chapter's popover open
Screenshot to addimages/screenshot-codex-strip-light.pngThe "In the book" dot row, with one chapter's dot clicked open to show what changes there.
Click a dot for that chapter: what changed there, and a straight jump to the page.

Codex names in your prose

In the Manuscript tab, the Codex names toolbar button highlights every codex mention in the chapter you're reading, first names and surnames included. Hover a name for the entry at a glance: its description, its most recent facts as of that chapter (no spoilers, even for you-the-hoverer), and arrows to hop between every mention in the chapter. Click through to open the full entry. It's off by default; switch it on when you want the map visible.

Codex names highlighted in the manuscript, with a mention card open Codex names highlighted in the manuscript, with a mention card open
Screenshot to addimages/screenshot-codex-names-light.pngA manuscript chapter with codex names underlined, and one mention's card open showing the entry and a jump-between-mentions control.
Every codex mention underlined in the prose. Click one for the entry, at a glance, without leaving the page.

Bringing a world in from Obsidian (or anywhere)

Import codex… takes your existing worldbuilding however it exists. Paste rough notes and bookmoth maps them into entries you review. Load a single Obsidian note and its structure is read as it is, not guessed: [[links]] become relations, frontmatter type/aliases/tags carry across, and the review card shows you the links survived before you accept anything.

Built a whole vault? Import a folder… reads every note in it, one entry per file: filenames become names, folders become types (Characters/, Places/, Lore/...), links become relations. No AI is involved, so a four-hundred-note vault costs nothing to read, and notes matching entries you already have are skipped, so re-importing an evolving vault only proposes what's new. Everything still lands in the review queue first.

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:

SettingWhat it doesUse it for
Send alwaysIncluded in every chapter bookmoth drafts.Your three to six core entries: the protagonist, a central rule of the world, the thing that matters everywhere.
Send when mentionedIncluded only in chapters where its name or an alias appears. The default.Almost everything: the wider cast, places, objects that come and go.
Never sendKept in your Codex for your reference, never handed to the AI.Spoilers, placeholders, entries you're still deciding on.

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

The send setting and auto-detect toggle on an entry The send setting and auto-detect toggle on an entry
Screenshot to addimages/screenshot-codex-visibility-light.pngClose-up of the Send always / Send when mentioned / Never send control, with the Auto-detect toggle visible beside it.
The send setting on an entry, with the Auto-detect toggle that appears for "Send when mentioned" entries.

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.
The Codex toolbar with the two project-wide toggles The Codex toolbar with the two project-wide toggles
Screenshot to addimages/screenshot-codex-toggles-light.pngThe Codex toolbar: the "Scan chapters…" button, the "Auto-scan new drafts" and "Pause mention tracking" checkboxes, and the review pill.
The Codex toolbar. The Scan button, the two project-wide toggles, and the review pill on the right.

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.

The Scan chapters picker The Scan chapters picker
Screenshot to addimages/screenshot-codex-scan-light.pngThe "Scan chapters" dialog with the chapter checklist and Select all / Deselect all.
The Scan chapters picker. Choose which chapters bookmoth reads. One AI call per chapter.

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 grouped: New entries, Updates to existing entries (each becoming a dated fact), and, when you've asked for a description to be untangled, the facts proposed from it. For each one you can edit the name, type, text and chapter 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 adds a dated fact to the entry's timeline, pinned to the chapter it came from (changeable in the row). It never rewrites your description. When the new fact contradicts an old one, the row offers replace or keep both: replace marks the old fact superseded, and the AI is told what changed and when.
  • 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.
The Codex review queue The Codex review queue
Screenshot to addimages/screenshot-codex-review-light.pngThe review modal: New and Updates groups, an editable row, a "May contradict existing" badge, and Accept / Reject buttons.
The review queue. New entries and updates, each editable, with conflict flags where bookmoth spots a contradiction.

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:

What goes wrongWhy it mattersThe fix
Duplicate entriesA scan proposes "Barnaby" as new when "Barnaby Trewint" already exists. Accept it and you have two records for one person. Both can be sent to the AI, which now sees a split, contradictory picture.Add the shorter name as an alias on the main entry, then delete the duplicate.
Contradictory factsAccept a flagged conflict with "keep both" and the timeline says a character's eyes are green and blue. The AI reads both and may blend or pick wrong.Read the "May contradict existing" badge. Let the new fact replace the old one, or reject it.
Fact clutterAccept every trivial proposal and the timeline fills with facts nobody needs, heavier context and an AI anchored to noise.Reject the trivia at review. A fact earns its place by mattering later.
Noise entriesOne-off walk-ons and incidental objects become tracked entries and start riding into chapters, wasting context, worst on small local models.Reject them at review, or set them to "Never send".
Over-broad namesAn entry named Will, Hope or The Bridge auto-detects on ordinary words and gets injected into chapters that never feature it.Turn Auto-detect off for that entry, or reserve "Send always" for the few that truly matter.

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.

This is what keeps it light. bookmoth does the work of deciding what each chapter needs, so even a large Codex stays focused and affordable, including on local models with smaller context windows. Powerful when you want it, invisible when you don't. The only thing it asks of you is a few seconds in the review queue.

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:

Starting situation: where things left off at the end of the last book. What happened, where are the characters now, what's unresolved.

World and rules: anything established in previous books that still applies. Magic systems, political structures, geography, social dynamics.

Continuing threads: plot threads, relationship dynamics, unresolved tensions, or promises to the reader that carry across books.

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

Each book is its own project. Create a new project for each book. The series context carries forward what the AI needs to know. Your writing examples and voice profile can be the same across books for consistency. The Editor is the fastest way to get set up: just tell it about the previous book and it handles the rest.

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.

Your book is saved on your computer or in your chosen sync folder. AI features send relevant text through the connection you select; see the privacy policy.

Which model should I choose?

For ink, start with Balanced in Connection. For your own cloud provider, start with bookmoth's default models if you are unsure, add that provider's API key and run Test connection. A successful test checks the connection with a small request; it does not guarantee that a long profile or draft will fit.

Heavy means demanding work, not a required model brand. Writing Profile analysis and chapter drafting need careful reading, strong instruction following and room for a long answer. A Sonnet-class model can be a reasonable choice. A failed request does not, by itself, mean you need a more expensive model.

  • Heavy: prioritise writing quality and a generous answer limit for profiles, drafts and polish. Try one profile or chapter before committing to a large batch.
  • Medium: a faster, cheaper model can suit summaries and extraction. Check the results for missed facts before relying on it across a book.
  • Light: short edits and simple tasks are a good place to save money. A model that handles these well may still struggle with a whole chapter.
  • Editor: choose a model that follows instructions reliably. Check the routing summary in Connection to see which provider and model will actually receive the work.

Three different limits

Context window means how much the model can read at once, including your brief, samples and instructions. Output limit means how much it can return in one answer. Writing quality means how well it understands and matches your prose. A large reading window does not guarantee a long answer or a good voice match.

Some reasoning models also spend part of the response budget thinking. Local models depend on your computer's memory, speed and server settings. Model size alone is not a guarantee: test a representative task and read the result.

Before paying for a different model

  1. Check that the chosen provider has a key, API credit and access to the selected model. Select its exact identifier from the provider's model list.
  2. Check Heavy for Writing Profile analysis. Changing Light will not change that task.
  3. Read the failure message below. Missing credit, an invalid key or an unavailable model will not be fixed by repeatedly pressing Analyse.
  4. Change one thing and try one task. Each retry may incur provider charges, even if the answer does not finish.

For current availability and limits, consult your provider's model listing. Anthropic documents model capabilities and API errors. Provider limits and access can change.

Troubleshooting

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

The model stops before finishing

A reported length limit means the answer stopped at the allowed response size. It does not necessarily mean the model lacks the intelligence to do the task. Reasoning can also use part of the available budget.

  • Writing Profile analysis: check the Heavy model in Connection and choose one with a larger output allowance. If the message instead says the input is too long, use a larger reading window or shorter representative samples, keeping your original files.
  • Chapter drafting or revision: try a shorter passage or scene at a time.
  • Request rejected for output length: the requested allowance may exceed what the provider accepts. Contact support if this persists with a supported model; an account upgrade is not necessarily the answer.

The model returned no answer

An empty answer does not establish the cause. If reasoning was returned, the model thought without producing a final answer. Otherwise the cause may be a service or compatibility problem. Test the connection, then contact support if the same task keeps failing. Include the provider, exact model, task and displayed error, never your API key or manuscript unless requested.

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:

  • Check the provider's content policy. Models differ in what they will handle, and no model is guaranteed to accept every literary passage.
  • 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:

  • No key configured. Add a key for the provider selected in Connection. Each provider needs its own key.
  • No API credit or a billing problem. Check billing with your API provider. Repeated retries cannot replenish credit.
  • 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.
If all else fails. Email support@bookmoth.app. It goes directly to me. You'll get a real answer, usually the same day.

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.