ainovel-cli: a Vietnamese-localised multi-agent CLI for drafting long-form novels

What ainovel-cli actually takes off your plate

Writing a long serialised novel with a single chat window fails for a boring reason: the outline, the character sheet, the world rules and the last twenty chapters all compete for the same context budget, and the draft drifts. ainovel-cli is built around that failure. The README describes it as a command line tool for automatic long-form novel composition using a multi-agent architecture, and the repository is a Vietnamese localisation of voocel/ainovel-cli, so the upstream engineering is inherited rather than reimplemented.

The intended user is someone who already has an LLM endpoint and wants the book-shaped work handled in a terminal: outline generation, character and setting bibles, chapter drafting, editorial scoring and export. The README positions the Vietnamese build around three things the upstream does not offer: a fully Vietnamese TUI, a language switch for the generated prose, and a Vietnamese style rule file at assets/voice.md intended to suppress the stock phrasing that AI drafts fall into. That last item is the most opinionated part of the fork, and it is a content decision rather than a code one.

The five-agent pipeline and the two-tier planning loop

The architecture named in the README is a chain: Coordinator, Architect, Writer, Editor, Arbiter. The Coordinator drives the run; the Architect produces planning artefacts; the Writer drafts; the Editor scores; the Arbiter resolves. The README also lists a seven-dimension quality evaluation performed by the Editor, though it does not enumerate the dimensions in the text available here, so treat that as a described capability rather than a documented rubric.

Two mechanisms do the heavy lifting. Rolling planning is described as two-tier: the system plans at a coarse level and refines near the writing front, so the full book is never planned in one pass. Context management is described as four-level compression. Together these are the answer to context exhaustion, and they are the reason the tool can target long-form output at all. Prompt caching is described as three-tier, which matters for cost: a pipeline that re-sends stable planning context on every step is expensive, and caching is the standard mitigation.

Step-level recovery is the last piece. The README lists recovery points at the step level, which implies an interrupted run can resume rather than restart. What the README does not document is rollback of already-written chapters, so do not assume an undo.

Installing ainovel-cli with Docker and running the first chapter

The README recommends Docker and Docker Desktop for Windows, macOS and Linux, with a Go build as the alternative. Clone the repository and create the two directories the compose file mounts.

git clone https://github.com/kentjuno/ainovel-cli.git
cd ainovel-cli
mkdir -p config workspace novels

The compose file mounts ./config to /root/.ainovel and ./workspace to /workspace, and the image is built from the local Dockerfile, which compiles ./cmd/ainovel-cli with Go 1.25 and runs the binary on alpine:3.22.

docker compose build
docker compose run --rm ainovel

If you prefer to build from source, the README gives the equivalent command.

go build -o ainovel-cli ./cmd/ainovel-cli
./ainovel-cli

On first run the Setup Wizard appears in Vietnamese and asks for provider, API key or base URL, model, and the language for the generated novel. The configuration lands in config/config.json. A minimal local Ollama setup looks like this, and the README is explicit that the Docker path must use host.docker.internal rather than localhost.

{
  "language": "vi",
  "provider": "ollama",
  "model": "ainovel-qwen",
  "providers": {
    "ollama": {
      "base_url": "http://host.docker.internal:11434/v1",
      "stream_idle_timeout": "300s"
    }
  },
  "context_window": 65536,
  "thinking": "off",
  "style": "default"
}

The README's Ollama instructions create a derived model with a 65536-token context window before this config is used. Expect the TUI to start, the wizard to complete, and generation to begin; the README does not state a first-chapter runtime, and none is claimed here.

Where ainovel-cli will frustrate you

The context window is the hard constraint. The README recommends a GPU with at least 12GB of VRAM for local Qwen 2.5 or 3.5, and the Ollama path requires creating a model with num_ctx set to 65536. Run a stock model without that step and the pipeline's compression and planning layers are working against a much smaller budget than they assume. This is a setup trap, not a bug, but it is the one most likely to produce disappointing output on a first attempt.

Provider behaviour is the second gap. The README lists OpenRouter, Gemini, Claude, OpenAI and DeepSeek, and shows per-provider JSON blocks, but it does not document how the tool reacts when a provider returns a malformed plan or refuses a request mid-pipeline. Step-level recovery is described; error taxonomy is not.

Finally, this is a fork. The module path in go.mod is github.com/voocel/ainovel-cli, while the repository is kentjuno/ainovel-cli, and the compose file pulls ghcr.io/voocel/ainovel-cli:latest. The Vietnamese layer is maintained separately from the engine it wraps, so upstream changes have to be carried across. Nothing in the README describes that merge process.

ainovel-cli versus a general writing assistant

A general assistant such as a chat interface with a long context window solves the same problem differently: you hold the outline and continuity in your head or in a document, and you paste context as needed. That approach has no pipeline, no editorial scoring and no recovery points, but it also has no configuration file, no Docker image and no model context requirement.

ainovel-cli inverts the trade. It moves continuity into the tool: planning artefacts, character and world state, rolling planning and four-level compression are the system's responsibility, not yours. The cost is setup and lock-in to the tool's file layout. If your novel is short enough to fit in one context window, the pipeline is overhead. If it is not, the pipeline is the product. The same reasoning separates it from tools aimed at converting finished fiction into other formats, which start after the drafting problem is already solved.

Licence, maintenance and the upgrade path

The repository is Apache-2.0. That is a permissive licence with an explicit patent grant, and it permits commercial use and modification provided the licence and notices are preserved. It is not legal advice; if you plan to ship generated novels commercially, read the licence text and check the terms of whichever model provider you configure, since the model's terms are separate from the tool's.

Maintenance: the last push was on 2026-09-08, which is recent, and the repository is not archived. No releases were retrieved, so there is no versioned artefact to pin against. The Dockerfile builds from source and docker-compose.yml also names ghcr.io/voocel/ainovel-cli:latest, which is a moving tag. For reproducible runs, build locally with docker compose build rather than relying on latest.

Upgrade cost is the fork tax. Because the engine module is voocel/ainovel-cli and the localisation lives in this repository, pulling upstream changes means reconciling translated TUI strings and the assets/voice.md style file with new upstream behaviour. Budget for that as recurring work, not a one-time setup.

Editorial conclusion

Adopt ainovel-cli if you already have an LLM endpoint and want a terminal workflow that keeps outline, characters, world state and chapter text in one pipeline, and if Vietnamese prose is the target. Do not adopt it if you need a hosted service with no local setup, or if you expect chapter-level rollback that the README does not describe. Before committing, run docker compose build and docker compose run --rm ainovel, complete the Setup Wizard, and confirm that your provider returns usable text at the context_window you configured; a model that ignores the configured window will surface as truncated or looping chapters rather than as a clean error.

Frequently asked questions

Official sources

1. Issues
2. kentjuno/ainovel-cli on GitHub
3. License: Apache-2.0
4. README