Long Novel Agent Kit

Local continuity infrastructure for writing long novels with desktop agents.

Long Novel Agent Kit does not replace the model, the writing agent, or the author's judgment. It gives local desktop agents a durable project memory and a set of safety gates so a long novel can survive long context windows, agent handoffs, source material updates, and multi-chapter continuity drift.

中文说明 · 中文整体架构与功能说明

The Short Version

Use the desktop agent for intelligence. Use this kit for continuity.

• The desktop agent reads PDFs, old drafts, notes, web pages, images, and long files with its native tools.

• The agent writes confirmed summaries, facts, research notes, and decisions into .novel-agent/.

• Before drafting, the agent calls prepare-session or build-context instead of relying on chat history.

• Before delivery, the agent calls continuity checks and delivery helpers.

• After the author accepts a chapter, writer tools record the chapter and update durable state with author confirmation.

• Another local agent can later read the same .novel-agent/ state and continue the book.

Related MCP server: novel-mcp

Architecture At A Glance

flowchart TD
  Author["Author"]
  Agent["Local desktop agent<br/>Codex, Cursor, Claude Desktop, etc."]
  Native["Agent native abilities<br/>model, long context, file parsing, web, PDF/OCR, retrieval"]
  Skill["SKILL.md<br/>workflow instructions"]
  MCP["server.py<br/>stdio MCP tools"]
  CLI["cli.py<br/>local commands"]
  State[".novel-agent/<br/>durable novel state"]
  Pack["desktop-pack<br/>local HTML/JSON/command packet"]
  Runtime["standalone runtime<br/>no-Python CLI and MCP executables"]

  Author --> Agent
  Agent --> Native
  Agent --> Skill
  Agent --> MCP
  Agent --> CLI
  MCP --> State
  CLI --> State
  State --> MCP
  State --> CLI
  CLI --> Pack
  CLI --> Runtime
  Pack --> Agent
  Runtime --> Agent

Component Responsibilities

Core State Model

Every novel project keeps long-term continuity in .novel-agent/.

Capability Map

The Main Writing Flow

sequenceDiagram
  participant A as Desktop Agent
  participant K as Long Novel Agent Kit
  participant S as .novel-agent
  participant U as Author

  A->>K: source-intake / add-source / add-research
  K->>S: store confirmed evidence
  A->>K: prepare-session chapter N
  K->>S: read facts, rules, sources, chapters, debts
  K-->>A: chapter-safe context and fingerprints
  A->>A: draft chapter with native model
  A->>K: check-chapter / chapter-readiness
  K-->>A: continuity and contract issues
  A->>U: deliver draft and known issues
  U-->>A: accept or request revision
  A->>K: record-chapter with author confirmation
  A->>K: propose-after-write / proposal-readiness
  K->>S: write audited accepted state when allowed

The important rule: generate context from durable state before writing. Do not treat chat history as the source of truth.

Read-Only Mode And Writer Mode

Read-only MCP is the default and recommended mode:

python server.py --read-only --tool-profile core

Read-only mode can prepare context, check drafts, build reports, inspect packs, and explain next steps. It cannot change .novel-agent/.

Writer mode can change durable state, so it is gated:

• The author must confirm the write.

• write-session-check compares project identity, state fingerprint, and chapter context fingerprint.

• Proposal readiness checks evidence, conflicts, and risk.

• .write.lock prevents concurrent writes.

• Snapshots are created before applied proposal updates.

• Every durable write appends to audit.jsonl.

Desktop Packs

desktop-pack is the bridge between the kit and ordinary local desktop-agent usage.

It writes a local directory containing:

• first-three.html, local-summary.html, and user-steps.html for a normal user

• pack-index.json, commands.json, commands-index.json, and schemas for an agent

• chapter-session.json, handoff-report.json, project status, continuity audit, and author review queue

• setup, install, upgrade, uninstall, local check, and archive scripts for macOS, Windows, and POSIX shells

• evidence templates and result JSON schemas for proving real GUI client behavior

• acceptance review and writer-mode authorization packets

The pack is a local guide and snapshot. If it is copied or moved, run pack-doctor, pack-freshness, or rebind-pack-kit before trusting old paths.

No-Python Handoff

For non-technical users on another computer, build a same-OS standalone runtime first:

python cli.py standalone-build \
  --output-dir release/long-novel-agent-runtime-macos-arm64 \
  --target-os macos \
  --apply \
  --force \
  --format json

Then create a handoff bundle:

release/long-novel-agent-runtime-macos-arm64/long-novel-agent desktop-handoff-bundle ./my-novel \
  --platform codex \
  --mode read-only \
  --chapter 1 \
  --runtime-dir release/long-novel-agent-runtime-macos-arm64 \
  --output-dir release/my-novel-agent-bundle \
  --archive \
  --force \
  --format json

The bundle contains project/, pack/, runtime/, launchers, MCP snippets, runtime command files, and agent-read-me-first.md. When both runtime executables are present, the target computer does not need Python.

For a Windows .exe release, build on Windows and follow Windows Runtime Release. The GitHub Actions template is stored at docs/github-actions-windows-release.yml; copy it into .github/workflows/ only when the GitHub token used for the push has workflow scope.

Quick Start From Source

git clone https://github.com/mushroomfk/long-novel-agent-kit.git
cd long-novel-agent-kit
python cli.py doctor
python cli.py init ./my-novel --title "My Novel"
python cli.py prepare-session ./my-novel --chapter 1 --platform codex --mode read-only --format markdown

Check a draft:

python cli.py check-chapter ./my-novel --chapter 1 --file chapters/001.md --format markdown

Generate a desktop setup guide:

python cli.py desktop-setup ./my-novel --platform codex --mode read-only --format markdown

What This Kit Does Not Do

• It does not run an LLM.

• It does not include embedding search.

• It does not parse PDF/OCR/web pages by itself.

• It does not upload manuscripts.

• It does not require a server for local desktop use.

• It does not replace literary judgment, editing taste, or author approval.

Those jobs belong to the host desktop agent and the author. This kit persists and verifies the continuity layer.

Repository Layout

.
├── cli.py                         # local CLI
├── server.py                      # stdio MCP server
├── install.py                     # local skill and MCP installer
├── SKILL.md                       # agent workflow instructions
├── schemas/                       # JSON schemas for proposals and desktop packs
├── assets/review-panel.html       # local static proposal review panel
├── examples/                      # smoke, handoff, evidence, and adversarial examples
├── docs/                          # architecture, install, workflow, and release docs
├── scripts/verify_agent_kit.py    # full regression check
└── scripts/adversarial_release_check.py

Verification

Run the full regression suite:

python scripts/verify_agent_kit.py

Run the stronger release gate:

python scripts/adversarial_release_check.py

An optional GitHub Actions workflow template is available at docs/github-actions-verify.yml. Repository maintainers with workflow scope can copy it to .github/workflows/verify.yml.

Requirements

• Python 3.10 or newer for source-based CLI/MCP usage.

• A local desktop agent that can start stdio MCP or run shell commands.

• Optional: PyInstaller when building no-Python runtime bundles.

Supported Local Agent Paths

• CLI-only agents can run python cli.py ....

• MCP-capable agents can start python server.py --read-only.

• Codex and Cursor local config paths can be generated automatically by install.py.

• Claude Desktop and generic JSON MCP clients can use explicit config snippets.

Remote connector-only platforms are outside this local stdio MCP flow.

License

MIT. See LICENSE.