How voocel/ainovel-cli works
1. What this repository is
- ainovel-cli is a Go-based command-line/TUI engine for long-form novel generation.
- The architecture is intentionally split between a thin host and an LLM-driven coordinator: the host starts runs, restores state, and observes events; the coordinator decides the creative workflow.
2. Process entry points
- cmd/ainovel-cli/main.go is the executable entry.
- Runtime can start through the TUI (internal/entry/tui), a headless mode (internal/entry/headless), or startup flows that gather the initial writing brief (internal/entry/startup).
- This makes the repo both interactive and automation-friendly, but all modes converge into the same host/coordinator pipeline.
3. Core orchestration boundary: Host vs. LLM
- internal/host contains the orchestration layer that does not decide story logic.
- It manages run lifecycle, checkpoint recovery, event dispatch, usage tracking, and reminder injection.
- The coordinator and subagents are responsible for decisions; the host only enforces boundaries such as stop conditions and state transitions.
4. Agent model
- internal/agents defines the higher-level agent runtime and context management.
- The documented roles are Coordinator, Architect, Writer, and Editor.
- The important architectural idea is that each role has its own context and tool access, but they collaborate through persisted artifacts in the store rather than direct shared memory.
5. Tool-driven workflow
- internal/tools is the main action surface for the agents.
- Tools cover planning, drafting, consistency checking, committing chapters, saving foundations/reviews/arc summaries, and reading chapter context.
- The tools are designed to return facts and write checkpoints, not to embed policy decisions, which keeps control flow in the agent layer.
6. Persistence and state model
- internal/store is the durable system-of-record for the novel.
- It stores the evolving manuscript and metadata: chapters, drafts, summaries, reviews, outline, characters, world rules, progress, timeline, foreshadowing, state changes, checkpoints, and runtime/session data.
- The output directory described in the README is the primary persistence boundary: the system can crash and resume from these files.
7. Workflow and recovery mechanics
- internal/host/flow and internal/domain model the run state, phase/flow transitions, simulation state, commits, checkpoints, and usage.
- internal/host/reminder generates per-turn system reminders from current persisted facts, rather than relying on long-lived prompt state.
- Recovery is step-granular: the host reads progress plus checkpoints and reconstructs the next required action.
8. Long-context management
- internal/agents/ctxpack and internal/tools/novel_context* implement context packing for long novels.
- The system uses layered summaries, sliding windows, and compacted store-derived context to keep LLM prompts within window limits.
- This is a core architectural boundary: narrative memory is externalized into the store and selectively rehydrated into prompts.
9. Content generation pipeline
- The canonical writing loop is: load novel context → read relevant chapter history → plan chapter → draft → consistency check → commit.
- Architect-generated assets such as premise, outline, characters, world rules, compass, and layered outline are stored under output/<novel>/meta.
- Editor outputs reviews and summaries that feed back into the next writing cycle, while internal/host/budget, usage, and reminder logic keep the loop constrained.
10. Import, simulation, export, and diagnostics
- internal/host/imp handles imported source novels: it splits source text, analyzes foundations, and reconstructs story structure.
- internal/host/sim and internal/stylestat support style imitation by building a simulation profile from sample texts.
- internal/host/exp exports finished content to TXT or EPUB.
- internal/diag analyzes output artifacts and emits exportable diagnostic reports, which is a separate observability/quality subsystem rather than part of the writing loop.
11. Configuration and model/provider abstraction
- internal/bootstrap loads and merges configuration from global, project, and CLI sources.
- internal/models abstracts provider/model registry and pricing/lookup, which is how the repo supports OpenRouter, Anthropic, Gemini, OpenAI, Ollama, and others.
- This provider abstraction is a key integration boundary: the novel engine is model-agnostic.
12. Prompt, rule, and style assets
- assets/ holds embedded prompts, reference docs, style presets, and rule baselines.
- internal/rules loads and merges rule files, while the README describes a layered rule system: built-in defaults plus user/project overrides.
- These assets are not just static text; they are part of the architecture because they directly shape agent behavior and quality checks.
13. User interaction surface
- internal/entry/tui is the primary human interface, with panels for progress, commands, import/export, simulation, and real-time steering.
- internal/notify and internal/logger support feedback and logging around the run.
- The TUI is an observer/control plane, not the creative engine itself.
14. Operational and release tooling
- .github/workflows/release.yml, .goreleaser.yml, and scripts/install.sh indicate this is shipped as a cross-platform CLI binary.
- Tests are extensive across host, store, rules, diagnostics, and simulation, which reinforces that the main risk is state-machine correctness and persistence integrity rather than HTTP/API wiring.
Main entry points: host Host · tui TUI · agents Agents runtime · tools Tools
Components 22
Entry & UI
Executable entrypoints and user interaction surfaces.
- CLI entry · Program entrypoint.
cmd/ainovel-cli/main.go - TUI · Primary human control and observation surface.
internal/entry/tui - Headless mode · Non-interactive execution path.
internal/entry/headless - Startup flow · Initial mode selection and writing-brief capture.
internal/entry/startup
Core Orchestration
Host control loop, flow routing, reminders, and run lifecycle.
- Host · Lifecycle control, boundaries, and event dispatch.
internal/host - Flow router · Routes run phases and transitions.
internal/host/flow - Reminders · Builds per-turn system reminders and stop guards.
internal/host/reminder - Budget · Tracks and constrains model usage.
internal/host/budget.go
Agents & Context
LLM roles, context management, and prompt packing.
- Agents runtime · Coordinator and subagent execution model.
internal/agents - Context packer · Builds compact long-context prompts from persisted facts.
internal/agents/ctxpack
Domain & Store
Run state model and durable novel persistence.
- Store · System of record for manuscript, metadata, checkpoints, and runtime state.
internal/store - Domain model · Phases, chapters, commits, reviews, simulation, usage, and transitions.
internal/domain
Writing Pipeline
Tooling that plans, drafts, checks, and commits chapters.
- Tools · Planning, drafting, checking, and persistence actions for agents.
internal/tools - Novel context · Selective rehydration of chapter and story context.
internal/tools/novel_context.go
Support Systems
Configuration, model abstraction, diagnostics, and output/import utilities.
- Bootstrap · Merges global, project, and CLI configuration.
internal/bootstrap - Model registry · LLM provider lookup and pricing abstraction.
internal/models - Diagnostics · Analyzes output artifacts and emits diagnostic reports.
internal/diag - Import flow · Splits and reconstructs imported novels into structured foundations.
internal/host/imp - Simulation · Builds style imitation profiles from sample texts.
internal/host/sim - Export flow · Exports finished content to TXT or EPUB.
internal/host/exp - Rules engine · Loads, merges, and checks rule files.
internal/rules
Prompt Assets
Embedded prompts, rules, references, and style baselines.
- Prompts & rules · Prompt templates, references, rules, and style presets.
assets
Connections 32
- CLI entry → Bootstrap: loads config · Initializes runtime configuration before execution.
- CLI entry → TUI: launches UI · Starts the interactive control plane.
- CLI entry → Headless mode: launches headless · Starts non-interactive execution.
- CLI entry → Startup flow: gathers brief · Begins startup and mode selection flows.
- TUI → Host: controls run · Sends user actions into the orchestration layer.
- Headless mode → Host: runs pipeline · Delegates automated execution to the host.
- Startup flow → Host: starts session · Creates the initial run context for orchestration.
- Host → Flow router: routes phases · Advances state transitions and run stages.
- Host → Reminders: injects reminders · Builds turn-specific system guidance from persisted facts.
- Host → Budget: enforces limits · Tracks usage and stop conditions.
- Host → Agents runtime: delegates decisions · Hands creative decisions to agent roles.
- Agents runtime → Context packer: packs context · Prepares compact prompt state for each role.
- Context packer → Store: rehydrates facts · Pulls layered summaries and history from durable storage.
- Agents runtime → Tools: uses tools · Performs planning and writing actions through tools.
- Tools → Novel context: builds context · Constructs chapter-aware prompts for generation and review.
- Tools → Store: writes checkpoints · Persists drafts, summaries, reviews, and runtime artifacts.
- Tools → Domain model: reads model · Uses the run and story state model for decisions and payloads.
- Host → Domain model: tracks state · Reads and updates lifecycle, checkpoint, and usage state.
- Store → Domain model: persists state · Durable repository of novel, session, and progress data.
- Bootstrap → Model registry: selects provider · Configures model/provider registry and pricing lookup.
- Agents runtime → Model registry: calls LLMs · Uses provider-agnostic model resolution.
- Host → Import flow: imports source · Reconstructs imported novels and foundations.
- Host → Simulation: simulates style · Builds or runs style imitation support flows.
- Host → Export flow: exports output · Writes finished content to release formats.
- Diagnostics → Store: analyzes artifacts · Reads persisted outputs to produce diagnostics.
- Rules engine → Prompts & rules: loads baselines · Consumes embedded rule files and reference material.
- TUI → Diagnostics: shows reports · Surfaces diagnostics and progress to the user.
- TUI → Import flow: imports novels · Offers interactive import and recovery operations.
- TUI → Export flow: exports novels · Provides export actions from the UI.
- TUI → Simulation: runs simulation · Exposes simulation controls in the UI.
- Tools → Rules engine: checks rules · Validates writing against loaded rule sets.
- Agents runtime → Prompts & rules: reads prompts · Uses embedded prompts, references, and styles.