lingfengQAQ/webnovel-writer: a Claude Code plugin that keeps long serial fiction consistent

The failure mode it targets: an AI that forgets chapter 80 by chapter 200

Most AI writing tools are judged on a single generation. A serialized web novel is judged on chapter 400, where a character's motivation must still match chapter 12, a power level established in volume one cannot quietly drift, and a foreshadowing planted early has to be registered, advanced and eventually paid off. The README frames the problem exactly this way: the hard part is not writing chapter one, it is that character motivation does not drift, that power levels, timelines, locations and world rules do not contradict each other, and that every chapter's new facts settle into a searchable state system.

The intended user is a serial author who writes inside Claude Code and wants the assistant to check references before drafting and file new facts afterward. It is not a prompt pack for one-off scene generation. The project's own one-line positioning is that it is a consistency system for long serialization, not a generator that forgets what it wrote.

Story System: one accepted commit per chapter, with read-only views derived from it

Version 6.0.0 introduced a default main chain called Story System, and the data flow is the most interesting part of the design. The `.story-system/` directory is described as the single source of truth, holding both the pre-writing contract and the post-writing commit. When a chapter is finished, a new fact enters the books through an accepted `CHAPTER_COMMIT`.

Everything else is a derived, read-only projection: `.webnovel/state.json`, `index.db`, `vectors.db`, `summaries/`, and `memory_scratchpad.json`. The README is explicit that these are views for querying and display, not places you edit. A `.webnovel/projection_log.jsonl` records projection runs so you can locate which of state, index, summary, memory or vector failed to synchronize. `project-status`, `doctor`, `preflight` and the dashboard surface the main chain and runtime state directly.

The write pipeline is gated rather than fire-and-forget. `/webnovel-write` prechecks the project root, placeholders and Story System health, refreshes the runtime contract, calls a `context-agent` to produce a writing brief, drafts from that brief, then calls a `reviewer` for multi-dimensional review where a blocking issue stops the run. Polishing, formatting and an Anti-AI final check follow. Only then does a `data-agent` extract facts, generate the `CHAPTER_COMMIT`, drive the projections and take a chapter-level backup. The stated reason for splitting it this way is to separate how it is written from what happened: prose and pacing can be loose, but facts must be registered, reviewed and archived.

Installing the plugin and running a first chapter

Installation goes through the Claude Code marketplace, so Claude Code is a prerequisite. Adding the marketplace and installing the plugin are two commands; the README notes you can swap `--scope user` for `--scope project` if you only want it active in the current project.

claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user

Python dependencies come from a requirements file that the README pulls over HTTPS. The badge states Python 3.10 or newer, so check that first.

python -m pip install -r https://raw.githubusercontent.com/lingfengQAQ/webnovel-writer/HEAD/requirements.txt

Initialization runs inside Claude Code and is a staged question-and-answer session that builds the book skeleton, setting collection, master outline and initial state. It creates the project directory with `.story-system/`, `.webnovel/`, and the Chinese-named folders for manuscript, outlines, settings and review reports.

/webnovel-init

Retrieval is configured by copying `.env.example` to `.env` in the book project root. The README's minimal config points Embedding at ModelScope and Rerank at Jina, but states both can be replaced with any OpenAI-compatible endpoint.

EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_embed_api_key

RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_rerank_api_key

Planning, writing, reviewing and querying are separate slash commands, which is worth noting because it means you drive the loop yourself rather than getting one button.

/webnovel-plan 1      # plan volume 1
/webnovel-write 1     # write chapter 1
/webnovel-review 1-5  # review chapters 1 to 5
/webnovel-query 伏笔  # query project state

The dashboard is read-only and its front end ships prebuilt with the plugin, so there is no `npm build` step locally. What you should see after a write is a final report rather than raw JSON or a traceback: a one-line status of 已完成, 部分完成, 需要你处理 or 未完成, followed by files produced, problems and slow steps, and next-step suggestions. Only unrecoverable failures point you at `.webnovel/logs/run_last.log`.

The retrieval fallback is generous, and that is also the honest limit

If you leave `EMBED_API_KEY` empty the system falls back to BM25 keyword retrieval automatically. That is a real convenience: you can start a book with no embedding provider at all and add one later. The README is equally clear about the cost, stating that semantic recall will be weaker. For a long serial where the same character is referred to by three different names and a location is described rather than named, keyword matching is exactly where recall breaks down. Treat the fallback as a way to evaluate the workflow, not as the configuration you ship a 2 million character book on.

There is a second constraint in the same area: every projection target (state, index, summary, memory, vector) is derived from the accepted commit. When one projection fails, the views disagree with the main chain until it is rerun. The README addresses this with `projection_log.jsonl` and says the system will report projections it already retried successfully, but it also means the diagnostic files are part of your normal reading, not an emergency-only tool.

Version 7 was frozen, so the CLI rewrite is not an option

The version guide in the README is unusually candid and should shape any adoption decision. The `master` branch carries v6, the Claude Code plugin, and is described as maintained with fatal-bug fixes only. The `v7` branch was a CLI multi-host rewrite; it is frozen, unreleased, and kept as a development archive. The next mainline is v8, a writing workbench built as a plugin for DeepSeek Harness, and it is still in development with its design documents published on the v8 branch.

So there is no supported non-Claude-Code path today, and the CLI that would have provided one was evaluated and dropped. If your team standardized on a terminal tool or a different agent host, this project does not currently meet you there. Feedback collected in the original v7 discussion is described as an important input to v8, which suggests the direction is still moving.

A fair comparison is with a general-purpose memory layer such as a retrieval-augmented note system bolted onto an editor. Those give you search over your own notes and leave the writing loop to you. webnovel-writer instead owns the loop: it produces the writing brief, blocks on review, extracts facts and commits them. The trade-off is that you inherit its directory layout, its Chinese-language commands and reports, and its opinion that facts must pass review before they count. If you want retrieval without that workflow, a generic RAG setup over your manuscript is less opinionated and less to maintain.

Licence, maintenance and what upgrading actually costs

The project is GPL-3.0. For an author running the plugin locally that distinction rarely matters, but if you plan to wrap it in a hosted service or ship a modified version inside a commercial product, the copyleft terms of GPL-3.0 are the thing to read, and this is not legal advice. The repository ships a LICENSE file at the top level.

The last push was on 2026-09-16, and the most recent release listed is v6.2.1 from 2026-07-07. The README describes v6 as maintained with fatal-bug fixes only, which is a maintenance posture rather than an active feature roadmap. Practically, that means upgrade cost is low but so is the rate of new capability on this branch; the forward-looking work is on v8, and the README does not document a migration path from v6 to v8. The `/webnovel-doctor` command is the project's own upgrade-adjacent tool: it is described as a stage-aware check of directories, files, the database, RAG, dependencies and dashboard artifacts. Running it after changing dependencies or pulling a new plugin version is the concrete way to find out whether your project still lines up.

Editorial conclusion

Adopt it if you already work inside Claude Code and your problem is continuity across hundreds of chapters rather than prose quality on a single scene. Do not adopt it if you need a standalone CLI, a hosted service, or a non-Chinese workflow; the v7 CLI was frozen and never released, and the README's commands, directory names and reports are all in Chinese. Before you commit, verify three things: that your Python is 3.10 or newer, that you can supply EMBED_API_KEY and RERANK_API_KEY or accept the BM25 fallback, and that /webnovel-doctor returns a clean preflight on your project root.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. lingfengQAQ/webnovel-writer on GitHub
4. README
5. Releases