Autonomous novel writing CLI agent - use for creative fiction writing, novel generation, style imitation, chapter continuation/import, EPUB export, AIGC detection, and fan fiction. Native English support with 10 built-in English genre profiles (LitRPG, Progression Fantasy, Isekai, Cultivation, System Apocalypse, Dungeon Core, Romantasy, Sci-Fi, Tower Climber, Cozy Fantasy). Also supports Chinese web novel genres (xuanhuan, xianxia, urban, horror, other). Multi-agent pipeline, two-phase writer (creative + settlement), 33-dimension auditing, token usage analytics, creative brief input, structured logging (JSON Lines), multi-model routing, and custom OpenAI-compatible provider support.
novelsmith is a CLI tool for autonomous fiction writing powered by LLM agents. It orchestrates a 5-agent pipeline (Radar → Architect → Writer → Auditor → Reviser) to generate, audit, and revise novel content with style consistency and quality control.
The Writer uses a two-phase architecture: Phase 1 (creative writing, temp 0.7) produces the chapter text, then Phase 2 (state settlement, temp 0.3) updates all truth files for long-term consistency.
--lang en# Initialize a project directory (creates config structure)
novelsmith init my-writing-project
# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)
novelsmith config set-global --provider openai --base-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o
# For compatible/proxy endpoints, use --provider custom:
# novelsmith config set-global --provider custom --base-url https://your-proxy.com/v1 --api-key sk-xxx --model gpt-4o
# Assign different models to different agents — balance quality and cost
novelsmith config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY
novelsmith config set-model auditor gpt-4o --provider openai
novelsmith config show-models
Agents without explicit overrides fall back to the global model.
# Check installation and configuration
novelsmith doctor
# View current config
novelsmith status
Initialize and create book:
novelsmith book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000
# Or with a creative brief (your worldbuilding doc / ideas):
novelsmith book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md
xuanhuan (cultivation), xianxia (immortal), urban (city), horror, otherbook-id for all subsequent operationsGenerate initial chapters (e.g., 5 chapters):
novelsmith write next book-id --count 5 --words 3000 --context "young protagonist discovering powers"
write next command runs the full pipeline: draft → audit → revise--context provides guidance to the Architect and Writer agentsReview and approve chapters:
novelsmith review list book-id
novelsmith review approve-all book-id
Export the book (supports txt, md, epub):
novelsmith export book-id
novelsmith export book-id --format epub
List your books:
novelsmith book list
Continue from last chapter:
novelsmith write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"
book-id for auto-detectionReview and approve:
novelsmith review approve-all
Use this when you have an existing novel (or partial novel) and want novelsmith to pick up where it left off.
Import from a single text file (auto-splits by chapter headings):
novelsmith import chapters book-id --from novel.txt
第X章 pattern--split "Chapter\\s+\\d+"Import from a directory of separate chapter files:
novelsmith import chapters book-id --from ./chapters/
.md and .txt files in sorted orderResume interrupted import:
novelsmith import chapters book-id --from novel.txt --resume-from 15
Continue writing from the imported chapters:
novelsmith write next book-id --count 3
Analyze reference text:
novelsmith style analyze reference_text.txt
Import style to your book:
novelsmith style import reference_text.txt book-id --name "Author Name"
Import parent canon:
novelsmith import canon spinoff-book-id --from parent-book-id
Continue spinoff:
novelsmith write next spinoff-book-id --count 3 --context "alternate timeline after Chapter 20"
If you need separate control over each pipeline stage:
Generate draft only:
novelsmith draft book-id --words 3000 --context "protagonist escapes" --json
Audit the chapter (33-dimension quality check):
novelsmith audit book-id chapter-1 --json
Revise with specific mode:
novelsmith revise book-id chapter-1 --mode polish --json
polish (minor), spot-fix (targeted), rewrite (major), rework (structure), anti-detect (reduce AI traces)novelsmith radar scan
# Detect AIGC in a specific chapter
novelsmith detect book-id
# Deep scan all chapters
novelsmith detect book-id --all
novelsmith analytics book-id --json
# Shorthand alias
novelsmith stats book-id --json
# Create an English LitRPG novel (language auto-detected from genre)
novelsmith book create --title "The Last Delver" --genre litrpg --chapter-words 3000
# Or set language explicitly
novelsmith book create --title "My Novel" --genre other --lang en
# Set English as default for all projects
novelsmith config set-global --lang en
novelsmith genre list to see all available genres# Create a fanfic from source material
novelsmith fanfic init --title "My Fanfic" --from source-novel.txt --mode canon
# Modes: canon (faithful), au (alternate universe), ooc (out of character), cp (ship-focused)
novelsmith fanfic init --title "What If" --from source.txt --mode au --genre other
For flexible, conversational requests:
novelsmith agent "写一部都市题材的小说,主角是一个年轻律师,第一章三千字"
If your project contains only one book, most commands accept book-id as optional. You can omit it for brevity:
# Explicit
novelsmith write next book-123 --count 1
# Auto-detected (if only one book exists)
novelsmith write next --count 1
All content-generating commands support --json for structured output. Essential for programmatic use:
novelsmith draft book-id --words 3000 --context "guidance" --json
novelsmith maintains 7 files per book for coherence:
All agents reference these to maintain long-term consistency. During import chapters, these files are reverse-engineered from existing content via the ChapterAnalyzerAgent.
The Writer agent operates in two phases:
This separation allows creative freedom in writing while maintaining rigorous continuity tracking.
The --context parameter provides directional hints to the Writer and Architect:
novelsmith write next book-id --count 2 --context "protagonist discovers betrayal, must decide whether to trust mentor"
novelsmith genre list
novelsmith genre show xuanhuan
novelsmith genre create --name "my-genre" --rules "rule1,rule2,rule3"
novelsmith genre copy xuanhuan --name "dark-xuanhuan" --rules "darker tone, more violence"
| Command | Purpose | Notes |
|---|---|---|
novelsmith init [name] | Initialize project | One-time setup |
novelsmith book create | Create new book | Returns book-id. --brief <file>, --lang en/zh, --genre litrpg/progression/... |
novelsmith book list | List all books | Shows IDs, statuses |
novelsmith write next | Full pipeline (draft→audit→revise) | Primary workflow command |
novelsmith draft | Generate draft only | No auditing/revision |
novelsmith audit | 33-dimension quality check | Standalone evaluation |
novelsmith revise | Revise chapter | Modes: polish/spot-fix/rewrite/rework/anti-detect |
novelsmith agent | Natural language interface | Flexible requests |
novelsmith style analyze | Analyze reference text | Extracts style profile |
novelsmith style import | Apply style to book | Makes style permanent |
novelsmith import canon | Link spinoff to parent | For prequels/sequels |
novelsmith import chapters | Import existing chapters | Reverse-engineers truth files for continuation |
novelsmith detect | AIGC detection | Flags AI-generated passages |
novelsmith export | Export finished book | Formats: txt, md, epub |
novelsmith analytics / novelsmith stats | View book statistics | Word count, audit rates, token usage |
novelsmith radar scan | Platform trend analysis | Informs new book ideas |
novelsmith config set-global | Configure LLM provider | OpenAI/Anthropic/custom (any OpenAI-compatible) |
novelsmith config set-model <agent> <model> | Set model override for a specific agent | --provider, --base-url, --api-key-env for multi-provider routing |
novelsmith config show-models | Show current model routing | View per-agent model assignments |
novelsmith doctor | Diagnose issues | Check installation |
novelsmith update | Update to latest version | Self-update |
novelsmith up/down | Daemon mode | Background processing. Logs to novelsmith.log (JSON Lines). -q for quiet mode |
novelsmith review list/approve-all | Manage chapter approvals | Quality gate |
novelsmith fanfic init | Create fanfic from source material | --from <file>, --mode canon/au/ooc/cp |
novelsmith genre list | List all available genres | Shows English and Chinese genres with default language |
"book-id not found"
novelsmith book list"Provider not configured"
novelsmith config set-global with valid credentialsnovelsmith doctor"Context invalid"
--context is a string (wrap in quotes if multi-word)"Audit failed"
novelsmith revise with --mode rewrite"Book already has chapters" (import)
--resume-from <n> to append to existing chaptersFor long-running operations:
# Start background daemon
novelsmith up
# Stop daemon
novelsmith down
# Daemon auto-processes queued chapters
--context, the more coherent the narrativenovelsmith style import before generationnovelsmith import chapters to bootstrap truth files before continuingnovelsmith review to catch issues earlynovelsmith audit metrics to understand quality bottlenecksnovelsmith analytics to track quality trends over timenovelsmith exportnovelsmith init.novelsmith/ directory per booknovelsmith doctor for troubleshooting