# ainovel-cli (Vietnamese Fork): A Multi-Agent CLI for Long-Form AI Novel Writing

> kentjuno/ainovel-cli is a Vietnamese-localized fork of voocel/ainovel-cli, a Go CLI for automated long-form novel writing that routes work through a five-role multi-agent pipeline (Coordinator, Architect, Writer, Editor, Arbiter) and supports offline Ollama or cloud API providers.

**kentjuno/ainovel-cli** — CLI sáng tác tiểu thuyết AI đa agent — Bản tiếng Việt của voocel/ainovel-cli

- Repository: https://github.com/kentjuno/ainovel-cli
- Stars: 527 · Forks: 256
- Language: Go
- License: Apache-2.0
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/kentjuno-ainovel-cli

## What This Fork Adds and Who It Serves

voocel/ainovel-cli is a Go CLI for automated long-form AI novel writing with a multi-agent architecture. The kentjuno fork adds three specific layers: a 100 percent Vietnamese TUI interface (menus, status bars, error messages, slash command descriptions), a default writing language of Vietnamese with 14 system prompts tuned for Vietnamese prose style, and a voice standards file (assets/voice.md) that defines rules to prevent AI writing clichés in Vietnamese output.

The target user is a Vietnamese-speaking author or developer who wants to write novels in Vietnamese and prefers an interface that does not require reading Chinese or English menus. The fork also retains support for Chinese-language novel output via a configuration field, for users who write in Chinese or want to translate between the two languages.

The repository description calls this a 'multilingual' fork, reflecting both the Vietnamese-first interface and the language field in config.json that supports vi and zh as output languages.

## The Five-Role Multi-Agent Pipeline

Novel generation in ainovel-cli runs through five sequential agent roles. The Coordinator manages the overall generation session and routes work between agents. The Architect creates the story outline, world-building, and chapter plans using a two-tier rolling planning system: a high-level plan for the full narrative arc and a lower-level plan for the current and upcoming chapters. Rolling planning means the outline updates dynamically as chapters are written, rather than locking the entire structure at the start.

The Writer agent produces chapter drafts based on the Architect's plan and the accumulated story context. The Editor agent evaluates each draft across seven quality dimensions and returns structured feedback. The Arbiter resolves conflicts between the Writer's output and the Editor's critique when the two are in tension, producing a final accepted draft for the chapter.

This pipeline is inherited from the upstream voocel/ainovel-cli with the Vietnamese fork adding the 14 tuned system prompts for the Writer and Editor roles. The voice file (assets/voice.md) defines specific rules these agents follow: sentence length guidelines, prohibited clichés in Vietnamese AI output, and structural patterns for natural Vietnamese fiction prose.

## Installing with Docker and Configuring a Provider

The recommended installation path uses Docker. Clone the repository, create the required directories, build the image, and start the TUI:

```bash
git clone https://github.com/kentjuno/ainovel-cli.git
cd ainovel-cli
mkdir -p config workspace novels
docker compose build
docker compose run --rm ainovel
```

The docker-compose.yml maps ./config to /root/.ainovel inside the container and ./workspace to /workspace. Configuration goes into config/config.json. On first run, the Setup Wizard in Vietnamese guides you through selecting a provider, entering an API key or local URL, selecting a model, and choosing the writing language.

For cloud API access, the config.json uses a provider and model field. An OpenRouter example from the README:

```json
{
  "language": "vi",
  "provider": "openrouter",
  "model": "anthropic/claude-3.5-sonnet",
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-YOUR_OPENROUTER_API_KEY"
    }
  },
  "context_window": 128000,
  "thinking": "off",
  "style": "default"
}
```

For a source build without Docker, the Dockerfile shows that the build compiles a single binary: `go build -o ainovel-cli ./cmd/ainovel-cli`.

## Running Fully Offline with Ollama

The fork lists Ollama local model support as a prominent feature. The README specifically covers Qwen 2.5 14B and 3.5 as the recommended models for offline use, with a context window of 65,536 tokens. GPU requirement: Nvidia with at least 12GB of VRAM.

Running offline requires creating a custom Ollama model definition with a large context window. The README provides a Windows PowerShell example:

```powershell
@"
FROM qwen2.5:14b
PARAMETER num_ctx 65536
"@ | Out-File -FilePath "$env:TEMP\ainovel.Modelfile" -Encoding ascii

ollama create ainovel-qwen -f "$env:TEMP\ainovel.Modelfile"
```

The config.json for Ollama inside Docker uses http://host.docker.internal:11434/v1 as the base URL, which routes from inside the container to the Ollama instance running on the host machine. For a binary running directly on the host (not Docker), the base URL is http://localhost:11434/v1 instead.

The README notes that running fully offline with a 14B model at 65,536 tokens of context is the way to produce Vietnamese fiction without any API costs after the initial model download.

## Context Management, Caching, and Step Recovery

Long-form novel generation has a context management problem: a story of dozens of chapters can accumulate far more tokens than any single context window holds. ainovel-cli addresses this with a four-level context compression system and a three-tier prompt caching layer.

Context compression reduces the accumulated story to summaries at four levels of detail, keeping the most recent content at full fidelity and earlier content as progressively more compressed summaries. This allows the Writer and Editor agents to maintain story continuity without requiring the full token history of every chapter in every generation call.

Prompt caching reduces redundant API calls by reusing stable parts of the prompt (the world-building rules, character definitions, voice guidelines) across chapter generations. Step-level recovery points allow a generation session to resume from the last successfully completed step rather than restarting from the beginning of a chapter if the session is interrupted. These three mechanisms together make multi-hour generation sessions practical on cloud APIs with per-token billing.

## Limitations: GPU Requirements and Fork Divergence

Offline use requires an Nvidia GPU with at least 12GB of VRAM for the Qwen 2.5 14B model. This is a hard constraint: smaller models run in less memory but produce lower-quality Vietnamese fiction prose. The README does not document alternative models that work well in less than 12GB.

The fork's docker-compose.yml pulls the upstream image (ghcr.io/voocel/ainovel-cli:latest) by default. This means a docker compose build without modification will build the Vietnamese-specific assets and source code locally, but the base image comes from the upstream voocel project. Deployments that need the full Vietnamese prompt set and voice file in the container image should verify that the build process copies assets/voice.md and the Vietnamese system prompts into the image correctly, rather than inheriting only the upstream binary.

As a fork, the repository also tracks a moving upstream target. Upstream changes to the agent architecture, context compression algorithm, or TUI framework require rebasing this fork. The README does not document a merge cadence with upstream.

## Advanced Features and Export Options

The TUI supports 14 slash commands covering story diagnosis (/diag), style simulation (/simulate), manual edit synchronization (/sync), external novel import (/import), and export (/export). The /export command produces the completed novel in TXT or EPUB format.

The story management system supports multiple independent novels stored in separate directories. The /diag command analyzes a running novel for narrative issues (pacing problems, character inconsistencies, plot gaps) and returns a structured report. The /simulate command shows a preview of how the writing style will read before committing to a full chapter generation.

The real-time Steer feature allows interrupting a running generation session to redirect the current chapter's development in a specific direction, without restarting the generation from the chapter beginning.

## Conclusion

ainovel-cli is the right tool for a Vietnamese-speaking writer who wants to produce long-form fiction with AI assistance and needs the interface itself to be in Vietnamese, or who wants to run the tool fully offline using a local Qwen model. The offline path has a real hardware requirement: a GPU with at least 12GB of VRAM. The cloud API path is lighter on hardware but adds per-token cost. As a fork of voocel/ainovel-cli, this repository inherits the upstream architecture but diverges in localization. The docker-compose.yml pulls the upstream image (ghcr.io/voocel/ainovel-cli:latest) by default, so builds that need the Vietnamese-specific prompts and voice file must build the image locally from the fork's Dockerfile. Verify that requirement before relying on the Vietnamese writing style rules in a Docker deployment.

## FAQ

### Can ainovel-cli run completely offline without cloud API calls?

Yes, through Ollama integration. You create a custom Ollama model with a 65,536-token context window (using qwen2.5:14b as the base), configure config.json to point to the Ollama local endpoint, and the tool runs with no external API calls. The hardware requirement is an Nvidia GPU with at least 12GB of VRAM.

### What is the multi-agent pipeline in ainovel-cli?

Five agent roles work in sequence: Coordinator manages the session, Architect creates and updates the story plan using two-tier rolling planning, Writer generates chapter drafts, Editor evaluates each draft across seven quality dimensions, and Arbiter resolves tensions between the Writer output and Editor feedback to produce the accepted chapter.

### How do I export a completed novel from ainovel-cli?

Use the /export slash command in the TUI. It supports TXT and EPUB output formats. The completed chapters are stored in the workspace directory mapped to ./workspace on the host machine.

## Sources

- [Issues](https://github.com/kentjuno/ainovel-cli/issues)
- [kentjuno/ainovel-cli on GitHub](https://github.com/kentjuno/ainovel-cli)
- [License: Apache-2.0](https://github.com/kentjuno/ainovel-cli/blob/main/LICENSE)
- [README](https://github.com/kentjuno/ainovel-cli/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kentjuno-ainovel-cli