OpenNovel
OpenNovel - 本地优先的长篇小说叙事操作系统，四 Agent 自主创作
Install / Use
claude mcp add Yaemikoreal -- npx -y github:Yaemikoreal/OpenNovelIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Skill content
View source on GitHubOverview
OpenNovel is a CLI-driven narrative operating system for long-form fiction. It is not a "one-click novel generator" — it is a collaborative writing environment where the author controls the story while AI handles the mechanical complexity of state tracking, consistency verification, and iterative refinement.
The system is organized around three decoupled layers:
- Human Layer — Pure Markdown files (canon, characters, drafts). Editable in any text editor, trackable by git, openable in Obsidian.
- Machine Shadow — Structured state extracted by AI: YAML frontmatter, SQLite event ledger, and file-level snapshots.
- Semantic Layer — LlamaIndex-based vector retrieval for contextual memory (BGE-M3 optional).
Core Features
- Four-Agent Autonomous Pipeline — Writer (planning + creation + revision), Critic (five-dimension scoring + anchored feedback), Manager (state extraction + event recording), Director (global narrative analysis + scheduling proposals). Full pipeline runs on a single command.
- Agent Autonomy — Writer can proactively query missing information mid-creation via tool-calling protocol. SafetyFence constrains recursion depth, token budget, and timeout.
- Canon Integrity Checking — Rule-based validation against world-building documents. Detects violations of established setting rules without LLM dependency.
- Causal Event Graph — NetworkX-based directed acyclic graph of narrative events. Supports path analysis, centrality computation, upstream/downstream causal tracing.
- Automatic Foreshadowing Tracking — Director detects planted setups, tracks their progression, and identifies resolution points automatically every 3-5 chapters via causal chain analysis.
novel foreshadowfor manual override. - Auto-Generated Timeline & Summaries — Chapter summaries written on commit, event timeline converted from EventStore SQL at zero token cost. Both autonomous and interactive flows emit them automatically.
- Blind Mutation — Key chapters generate multiple structural directions via orthogonal mutation dimensions (narrative structure, point of view, causality, thematic arc). Corrective mode targets weak dimensions from prior evaluation.
- Stage Model Routing — Different LLM models per writing stage: cheap model for planning, flagship model for creation, premium model for revision.
- Model-Agnostic LLM Bus — LiteLLM integration supports any provider (OpenAI, Anthropic, DeepSeek, Ollama, local models). Each agent can be independently configured.
- Three-Layer Model Fallback — Agent-level model in novel.yaml, project-level model, global default in
.opennovel.yaml, hardcoded default. No repeated configuration needed. - Human-in-the-Loop — AI proposes, human approves. Every state change goes through
novel commitwith diff review. Full rollback support. - MCP Server — Four tools exposed via Model Context Protocol for Claude Code and other MCP clients.
Quick Start
Installation
git clone https://github.com/Yaemikoreal/OpenNovel.git
cd OpenNovel
pip install -e ".[dev]"
Configure API Keys
Set your LLM provider key as an environment variable:
export DEEPSEEK_API_KEY="sk-xxxx" # DeepSeek
export OPENAI_API_KEY="sk-xxxx" # OpenAI
export ANTHROPIC_API_KEY="sk-ant-xxxx" # Anthropic
Initialize a Project
# Create project in workspace (novels/<name>/)
novel init my-novel
# Or create at specific path
novel init .
The workspace is managed by .opennovel.yaml at the project root. Default model is deepseek/deepseek-v4-flash.
Write Your First Chapter (Interactive)
# Edit characters, world rules, and outline in your editor
# Then start AI-assisted writing:
novel write novels/my-novel/draft/ch_001.md
# Store inspirations:
novel stash "A sentence fragment" --tag mood
# Review and commit state changes:
novel commit novels/my-novel/draft/ch_001.md
Run Autonomous Creation
This is the primary workflow. Prepare your project, then execute:
novel auto novels/my-novel
The system processes all chapters sequentially through the Agent pipeline. See the Autonomous Writing section for details.
Autonomous Writing
The novel auto command orchestrates a four-agent pipeline that generates an entire novel from your outline, character files, and world rules.
Pipeline
┌─────────────────────────────────────────────────────────┐
│ Chapter Loop │
├─────────────────────────────────────────────────────────┤
│ Writer.think() → structured outline with scenes │
│ ↓ │
│ Knowledge Gap Detection → ToolRegistry query │
│ ↓ │
│ Writer.write() / write_with_autonomy() │
│ (mid-write tool calls via ##TOOL_CALL## protocol) │
│ ↓ │
│ Critic.evaluate() → five-dimension score (0-100) │
│ ↓ │
│ if score < 80: │
│ Writer.hot_fix() (targeted paragraph repair) │
│ or Writer.revise() (full chapter rewrite) │
│ → re-evaluate (max 5 retries) │
│ ↓ │
│ Manager.update() → character state + events │
│ ↓ │
│ Snapshot → Diff Check → chapter written │
│ ↓ │
│ Director.analyze() → strategy for next chapter │
└─────────────────────────────────────────────────────────┘
Scoring Dimensions
Critic evaluates each chapter across five dimensions, each scored 0-20:
| Dimension | Focus | |:---|:---| | Writing Quality | Sentence fluency, vocabulary, sensory detail | | Plot Logic | Causal coherence, pacing, payoff setup | | Character Consistency | Motivation, voice, emotional arc alignment | | Rhythm Control | Scene length variation, tension modulation | | Emotional Expression | Subtext, atmospheric resonance, reader impact |
Agent Autonomy (Mid-Write Tool Calling)
When enabled, Writer can detect knowledge gaps during creation and autonomously query information sources. The protocol is transparent:
- Writer's prompt includes tool-calling instructions.
- If the LLM needs additional information, it emits a
##TOOL_CALL##marker with the query. - The system intercepts the marker, executes the query through ToolRegistry, injects results, and continues the generation loop.
- SafetyFence enforces recursion depth, token budget, and timeout constraints.
This mechanism is controlled by the safety_fence configuration in novel.yaml.
Conditionals and Optimizations
- High-score bypass: Chapters scoring >= 90 skip Manager real-time update, deferred to batch processing at pipeline end.
- Chapter type routing: Climax chapters force Director analysis. Transition chapters skip Director. Routine chapters run Director every N chapters.
- Scheduling proposals: Director can propose chapter insertions, skips, or merges, applied from end to start after current chapter completes.
Blind Mutation
For chapters detected as climax or when prior score is below 80, Writer generates multiple structural variants through think_variations():
- Exploratory mode: Random dimension selection with varied temperature (0.5/0.7/0.9).
- Corrective mode: Targets weak dimensions identified by Critic, injecting negative constraints into the variant prompt.
- Outline pre-screening: Critic evaluates each variant outline on plot logic, character consistency, and pacing before full creation.
Example Output
A five-chapter time-paradox short story generated by the autonomous pipeline:
| Chapter | Title | Score | Words | |:---|:---|---:|---:| | ch_001 | Quantum Whisper | 85 | 6,064 | | ch_002 | Ripples | 85 | 4,110 | | ch_003 | Second Attempt | 85 | 5,694 | | ch_004 | Vortex | 82 | 4,306 | | ch_005 | Causal Loop | 85 | 5,746 | | Total | | 84.4 avg | 25,920 |
Creation time: approximately 14 minutes. Token consumption: 210,503.
MCP Server and Claude Code Integration
OpenNovel exposes its full creation pipeline through the Model Context Protocol (MCP), enabling Claude Code and other MCP clients to initialize projects, check status, write chapters, and run autonomous creation.
Starting the MCP Server
# The server runs on stdio transport
novel-mcp
Registering with Claude Code
Create or edit .mcp.json in your project root or in ~/.claude/settings.json:
{
"mcpServers": {
"opennovel": {
"command": "novel-mcp",
"args": [],
"env": {
"DEEPSEEK_API_KEY": "sk-xxxx",
"OPENAI_API_KEY": "sk-xxxx"
}
}
}
}
Available Tools
| Tool | Description | Key Parameters |
|:---|:---|:---|
| init_project | Create a new novel project with standard structure | path (str): project directory |
| get_status | Read project state: config, characters, chapters | path (str): project directory |
| write_chapter | Single chapter creation with evaluation | path, chapter_id, chapter_hint (str) |
| auto_create | Full multi-chapter autonomous creation | path, chapters (int, optional) |
Usage in Claude Code
Once configured, you can invoke OpenNovel through natural language in Claude Code:
Initialize a science fiction novel project at ./nova.
The setting is a generation ship where the crew discovers
the cryo-pods are slowly failing. Create 3 characters:
a pragmatic captain, a compassionate doctor, and a
mysterious passenger who shouldn't be awake.
Use auto_create to write 5 chapters.
Claude Code will call the MCP tools in sequence: init_project → edit files directly (canon, characters, outline) → auto_create with chapters=5.
You can also combine with direct file editing for finer control:
After init_project, I'll write the world rules myself...
CLI Command Reference
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
93.3kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Understand-Anything
81.6kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
Agent-Reach
78.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
70.8k🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
