ainovel-cli's multi-agent harness architecture is the most serious attempt at long-form AI writing I've seen. · voocel/ainovel-cli
Why This Matters Right Now
Everyone's building AI writing tools. Most of them are glorified "continue this text" wrappers. They fall apart after chapter three, forget character names by chapter seven, and turn into incoherent soup by chapter twenty. Nobody has seriously solved the engineering problem of long-form coherence — until maybe now.
ainovel-cli is a 71-star Go project that quietly dropped a multi-agent novel generation engine with a design philosophy that's worth your attention even if you never write a single word of fiction. The architecture decisions here are a clinic in how to build reliable, long-running LLM pipelines.
What It Actually Does
You feed it one sentence. It produces a complete novel. That's the pitch. But the interesting part is how it refuses to let the process fall apart.
Four specialized agents divide the labor: Coordinator orchestrates everything; Architect handles premise, outline, character files, and world rules; Writer autonomously plans, drafts, self-reviews, and commits each chapter; Editor evaluates arcs across seven quality dimensions. Each has a constrained tool set — Writer gets plan_chapter, draft_chapter, check_consistency, commit_chapter. Editor gets read_chapter, save_review, save_arc_summary. Nobody does everything, which means nobody context-overflows trying.
The seven-dimension editorial review is genuinely ambitious: setting consistency, character behavior, pacing, narrative coherence, foreshadowing, hooks, and aesthetic quality — where aesthetic is further broken down into descriptive texture, narrative technique, dialogue differentiation, word quality, and emotional resonance. Every critique must cite the original text as evidence. That's not vibes-based editing.
The Technical Architecture Worth Stealing
The real gem here is the Scaffolding + Harness split, documented in the README's architecture section. Most agent frameworks conflate setup with runtime. This project separates them explicitly:
• Scaffolding — model selection, prompt assembly, tool binding, sub-agent wiring happens before the run starts
• Harness — once running, the host layer owns state transitions, checkpoint recovery, handoff packages, review gating, and commit consistency
Critically: the LLM never controls the control flow. State is driven by signal files. The Phase state machine follows a strict forward-only rule (init → premise → outline → writing → complete) with no backtracking. The Flow layer handles in-writing transitions (writing → reviewing → rewriting → polishing → steering). This is deterministic orchestration on top of non-deterministic generation — exactly the right separation.
Chapter-level checkpoint recovery is table-stakes in production pipelines but almost nobody ships it in open-source tools. Here, Ctrl+C, crashes, or network drops all resume from the last committed chapter, covering all five phases: planning, writing, review, rewrite, and user intervention.
The rolling arc planning is clever. Instead of planning 500 chapters upfront (which produces hollow outlines), the Architect only plans the first 2-arc skeleton plus detailed chapters for arc 1. Subsequent arcs expand lazily, informed by save_arc_summary and character state snapshots. Far-future planning stays grounded because it's generated when it's needed, not when it's speculative.
For context management, the novel_context tool loads a structured pack per chapter: prior summaries, timelines, active foreshadowing threads, character state, style rules, next-chapter forecast, and relevance-recommended historical chapters across four dimensions — foreshadowing, character appearances, state changes, and relationships. The adaptive strategy auto-switches between full-context, sliding window, and hierarchical summarization based on total chapter count, which is the right engineering answer to the 500-chapter problem.
All state lives in JSON + Markdown files. No database. writerRestorePack and handoff packages serialize between agent invocations. The persistence layer is auditable and portable, which matters when you're debugging a novel that's 200 chapters in.
Honest Limitations: Who Should NOT Use This
Let's be direct about what this isn't.
It's 71 stars and no stable release tag. The docs/ folder explicitly says the runtime-and-recovery.md, writing-pipeline.md, and diagnostics.md docs are marked "suggested future additions." You're working with partial documentation on a young project. The architecture is thoughtful but the operational runbook isn't there yet.
It's Chinese-first. The README, comments, and default prompts are in Chinese. The tool can write English novels — the underlying LLMs are multilingual — but if you need to debug prompt behavior or tune the seven-dimension editor, you're reading Chinese source material. That's a real friction point for non-Chinese speakers.
API costs will be substantial. A 500-chapter novel with multi-agent review loops, self-consistency checks, and arc summarization is going to burn through tokens aggressively. There's no cost estimation tooling visible in the docs. Budget accordingly before you kick off a run.
Go isn't Python. If you want to fork and customize the agent behaviors or swap in your own prompts, you're writing Go. That's fine, but the AI tinkerer community skews Python-heavy. The contribution surface is narrower.
No cloud-hosted option. This is a CLI you run locally. If you want to generate novels asynchronously in the background or integrate it into a web app, you're building that infrastructure yourself.
The Verdict
This project deserves more stars than it has. The Novel Harness architecture — deterministic control plane over non-deterministic agents, forward-only phase state machine, lazy arc planning, chapter-level recovery — solves real problems that matter beyond novel generation. Any developer building long-running LLM workflows (code generation pipelines, research agents, document synthesis) should read this codebase.
For actual novel generation: if you read Chinese and are comfortable debugging a young Go project, this is the most architecturally serious open-source attempt at long-form AI fiction I've encountered. The rolling arc planning and seven-dimension editorial review alone put it ahead of anything in the Python ecosystem.
If you're a developer studying multi-agent architecture patterns, clone it anyway. The Scaffolding/Harness split and signal-file-driven control flow are ideas worth carrying into your next project regardless of what you're building.
The LLM never controls the control flow — state is driven by signal files, which is exactly the right separation between deterministic orchestration and non-deterministic generation.
Top comments (0)