jncchds/abook repository overview

⁠ABook — Agentic AI Book Writing

A self-hosted web application that uses AI agents to collaboratively write books. Seven specialized agents — Story Bible, Characters, Plot Threads, Chapter Outlines, Writer, Checker, and Editor — work together under your direction, streaming their progress in real time and pausing to ask clarifying questions when needed.

⁠Features

⁠Writing pipeline

• Seven specialized agents across two phases: a 4-phase Planner (Story Bible → Characters → Plot Threads → Chapter Outlines) and a per-chapter writing pipeline (Pre-write Check → Write → Check → Edit)
• Checker → mechanical patch apply — the Checker flags continuity, grammar, repetition, and style issues as structured JSON patches; the Editor applies them mechanically (no LLM call) using indexed text matching with whitespace normalization and position hints
• Full synopsis spine — every prior chapter's title and outline is injected into Writer and Editor messages so agents stay aware of the whole narrative and avoid recycling beats or re-introducing established characters
• RAG context retrieval — Writer runs 3 targeted queries (characters, locations, plot threads) and Editor runs 4 (same + repeated-phrase detection) against pgvector embeddings

⁠Planning & guidance

• Guided planning Q&A — before planning, the planner posts its clarifying questions to the book's Clarifications page and waits; answer each one there (or skip it), and submitting the last answer completes the round and planning carries on. Answers are kept as clarifications and added to the premise in every prompt, so nothing is lost if planning is interrupted, and the round isn't repeated once it's done. Edit, add, archive or restore them on the same page, or reopen the round to be asked again
• Two ways to write a book — Interactive: write it in a chat with the LLM, in any order, approving every change; Autonomous: the LLM plans the whole book and writes it on its own
• Book chat (Interactive books) — say what you want (a character, a plot thread, a chapter, a change); the LLM answers, flags conflicts with what the book already establishes, and proposes changes as cards with a diff — nothing changes until you Apply them, and every applied change can be Undone. No chapter count, no up-front outline: chapters and sections are added as you go, and each written chapter is summarized and checked, with the fixes proposed back in the chat. The premise and Story Bible are settled first and then locked while you write (only you can unlock them). Works on a phone; also available over MCP
• Flexible workflow controls — Plan Book and Write Book (both pick up where the book left off), Illustrate Book, per-section runs on the Chapters page (▶ Write section writes a section's unfinished chapters the way Write Book does, breaking it down first when the planner expects several chapters; 🔍 Check checks each written chapter of it) and per-chapter runs on the chapter page (✍️ Write / Rewrite, 🖋 Edit prose, 🔍 Check); Stop cancels any running agent cleanly
• Refresh-safe progress — reloading the page (or losing the connection) mid-run keeps the current step, the latest progress message and everything streamed so far; new text continues where it left off
• Interrupted runs keep their output — if a Characters, Plot Threads, or Chapter Outlines run times out, drops, or is stopped part-way, everything that finished streaming is saved instead of discarded; run the phase again to pick up where it left off
• Re-runs build on what exists — regenerating a planning phase sends the current characters, plot threads, or outlines back to the model to refine and extend, rather than starting from a blank page; archived items stay out of it and are never overwritten

⁠Content management

• Story Bible, Characters & Plot Threads — generated by the Planner, fully editable, with per-item version history and snapshot restore
• Inline editing — edit book metadata, chapter titles/outlines, and add chapters manually without leaving the detail page
• Sections and chapter order — the plan is made of sections, each starting as one chapter. Insert anywhere (＋ After adds a section, ＋ Chapter here adds a chapter to the same section, ＋ Insert at the start), move chapters and sections up and down, and ✂ Split a chapter that needs more room: divide its outline between it and a new chapter right after it in the same section, and both are written again (the old text stays in the version history). A section with several chapters keeps an overall plan of its own (✎ Plan), and the sidebar numbers its chapters "3.1", "3.2". Plan Book outlines sections (the target count is a number of sections) and notes which ones need more than one chapter; ⋔ Break down has the planner divide an unwritten section into chapters, and Autonomous runs do it on their own before writing such a section. The Writer gets the section's overall plan and its other chapters, so each chapter tells its own share. Numbers follow the order, and plot threads' and characters' references (which count sections) move with them. Archived chapters and sections keep their place — Show archived in place shows them between their neighbours, and restoring puts them back there. Turn on Show sections in the book (Book Settings) to give each section a part heading ("I. Title") in the downloads and the reader
• Version history — chapters, characters, plot threads and clarifications all track history with preview and restore; soft-archive instead of delete. Every edit is kept as a version; a run of your own edits (web or Telegram) updates one version instead of piling up new ones, while any change by an agent or the book chat in between starts a new one
• Archived means archived — an archived chapter, character, or plot thread is kept purely so you can look at it or restore it. It is never sent to a model, never counted in planning or continuity checks, never included in an HTML/FB2/EPUB export or on the public reader page, and agents refuse to write to it
• Book continuation — create a sequel that copies all settings and inherits ancestor context; RAG and planning reference the full base-book chain
• Rewind — bring the whole book and its chat back to an earlier moment (before a chat message, after a chapter version, before or after a run). Every part gets the state it had then as a new version, so nothing in between is lost; later chat messages are hidden — see Rewind⁠

⁠Illustrations

• AI illustrations with Z-Image or Unsloth Studio — turn on Illustrate this book and the LLM plans illustrations for every finished chapter (what each image shows, where it goes, and its positive and negative prompts, chosen to suit the genre), plus the cover once the book is written. Review and edit the plan, then press Illustrate book to render everything in one image-model run — no LLM calls, so you can unload the LLM first (automatic for Ollama)
• The same objects, clothes and places in every image — the illustrator keeps a registry of recurring assets (props, outfits, places, creatures, vehicles) and repeats each one's description word for word whenever it appears; characters keep their usual outfit unless the story changes it. Review and edit the registry on the Illustrations page — an edit updates every prompt that shows the asset
• One style for the whole book — the illustrator writes an art direction once (style, a portrait composition shared by the whole cast, a book-wide negative prompt) from your visual style; it is added word for word to every image and can be edited on the Illustrations page
• Consistent characters — each character gets a visual description written from their profile and a reference portrait; every image showing them repeats that description, and scenes centred on them reuse the portrait's seed. Re-roll a portrait until the look is right, then re-render their scenes
• Configurable — image endpoint, steps, CFG, sizes and visual style live in the LLM configuration and presets, so applying a preset switches the text and image models together

⁠Exports & sharing

• Multiple export formats — HTML (6 colour themes, adjustable font size), EPUB, FB2, and a Metadata document (book info and stats, then the current Story Bible, clarifications, characters, plot threads and chapter plans, then the full timeline of planning, edits, agent messages and LLM calls). Rendered illustrations and the cover are embedded in all of them, compressed to JPEG to keep the download small
• Public Library — browse and read published books without logging in (when public mode is enabled); each chapter has its own URL for bookmarking and sharing
• Telegram bot — connect a book to a Telegram chat, group topic or channel: a pinned status card with Start / Continue / Stop, the planner's questions (reply to answer), a file after each chapter edit, the finished book, illustrations, live drafts while a chapter is written, and the book chat of Interactive books. Whoever can post in the chat gets the access you choose — see Telegram Bot⁠

⁠Infrastructure

• Pluggable LLM backend — Ollama (default, local), OpenAI (or any OpenAI-compatible API), or Google AI Studio; settings kept as presets (your default is copied into each new book) and per book
• Real-time streaming — watch chapters being written token by token via SignalR; planning phases stream with live progressive JSON previews. Only book content streams — a reasoning model's thinking is saved to the chat as one "💭 Thinking" message when each step finishes (even when it fails), and the live view reconnects by itself after a network drop. Live updates are numbered, so after a drop the page gets exactly the updates it missed replayed; a heartbeat every 15 seconds notices a connection that died silently and reconnects it
• Fail-safe runs — a stalled LLM connection times out instead of hanging the book; double-clicking a start button can't launch two runs; runs interrupted by a server restart are closed out with a note telling you how to pick up (Plan Book / Write Book, or /plan / /continue in Telegram)
• Health endpoint — GET /health reports whether the database is reachable (for Docker/uptime checks)
• Token usage statistics — per-agent prompt and completion token counts, persisted to the database and displayed in a collapsible panel. Calls that error, time out, or are cancelled are recorded too, with a Status column and the failure reason shown next to their partial counts
• MCP server — built-in Model Context Protocol server at /mcp; connect Claude Desktop, VS Code Copilot, or any MCP client using a per-user API token
• Multi-user — JWT sign-in (short-lived access token, httpOnly refresh cookie) with an admin role for user management
• Ollama model management — browse installed models, pull new ones with live progress
• Global concurrency limit — cap simultaneous agent runs across all books/users with AgentSettings__MaxConcurrentRuns
• PWA support — installable, works offline for cached content

⁠Architecture

[React SPA — served as static files from ASP.NET wwwroot]
        ↕ REST API + SignalR
[ASP.NET Core 10 API]
        ↕ Direct provider SDKs      ↕ EF Core 10 + Npgsql
[LLM (Ollama / OpenAI / Google)]   [PostgreSQL 16 (pgvector in-DB)]

React is built at image-build time and served from wwwroot/ — there is no separate frontend container at runtime.

⁠Quick Start

⁠Prerequisites

• Docker⁠ + Docker Compose⁠
• Ollama⁠ running on the host machine (or any OpenAI-compatible API)

⁠Run with Docker Compose

docker-compose up -d

# App is available at
open http://localhost:5000

On first launch the app shows a Create Admin Account setup screen — the first account registered automatically becomes admin. After signing in, go to Settings to configure your LLM provider and pull an Ollama model.

⁠Run from Docker Hub

docker run -d \
  -p 5000:8080 \
  -e ConnectionStrings__DefaultConnection="Host=<postgres-host>;Port=5432;Database=abook;Username=abook;Password=abook" \
  --add-host host.docker.internal:host-gateway \
  jncchds/abook:latest

services:
  abook-api:
    image: jncchds/abook:latest
    ports:
      - "5000:8080"
    environment:
      - ConnectionStrings__DefaultConnection=Host=postgres;Port=5432;Database=abook;Username=abook;Password=abook
      - ASPNETCORE_ENVIRONMENT=Production
    depends_on:
      postgres:
        condition: service_healthy
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: abook
      POSTGRES_USER: abook
      POSTGRES_PASSWORD: abook
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U abook -d abook"]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: unless-stopped

volumes:
  postgres_data:

⁠Configuration

⁠Environment Variables

For local development, copy src/ABook.Api/appsettings.Local.example.json → appsettings.Local.json and fill in your values.

⁠Sign-in

The browser gets a short-lived access token (kept in memory, never in storage) and a refresh token in an httpOnly cookie that is only sent to /api/auth, rotated on every use and revocable (sign-out, password change). A browser stays signed in for Jwt__RefreshTokenDays after its last visit.

Tokens are signed with Jwt__SigningKey. You don't have to set it — if it is missing, ABook generates a random key on first start and keeps it in its database, so sessions survive restarts and updates. It does log a ⚠️ warning at every startup and shows admins a banner, because anyone with a copy of the database could then forge sign-ins. To move the key into your configuration:

docker compose exec abook-api dotnet ABook.Api.dll secrets show

Copy the printed Jwt__SigningKey=… line into the environment: section of abook-api, then docker compose up -d (any other random 32+ character value works just as well). Changing the key never signs anyone out: it only invalidates access tokens, and browsers fetch a new one with their refresh cookie.

⁠LLM Providers

LLM settings are kept as presets (the 🔑 Presets page) and per book (each book's Settings page):

How the settings are resolved:

• Every book has its own LLM settings. When you create a book it gets a copy of your default preset (a sequel copies its base book instead). Later changes to the preset — or picking another default — never affect existing books; change those on the book's Settings page (where Apply Preset copies a preset in).
• Your default preset is chosen under Settings → Default LLM Preset or with Make default on the Presets page. New users get a private "Default" preset built from the LlmDefaults__* environment variables, if those are set.
• Shared presets are available to every user (including as their default) but only admins can create, edit or delete them. Admins share a preset with the Shared with everyone toggle; sharing cannot be undone. Anyone who can use a shared preset can see its API keys once it is copied into their books.
• There is no global or per-user fallback configuration any more (removed in v0.3.0).

Local models often ignore the JSON schema the planning agents send — returning a chapter number as 1.0 or "3", or a text field as a list. The parsers coerce those instead of failing, drop only the entries they genuinely cannot read, and post a ⚠️ note in the book's chat naming each dropped entry and the JSON behind it. If a planning phase does fail outright, the error in the chat quotes what the model actually returned.

⁠Image Generation (Illustrations)

Illustrations are rendered by one of two image providers, chosen under 🎨 Image Generation in a book's LLM settings or in a preset; use Test connection after setting the URL.

• Z-Image — a self-hosted Z-Image Turbo⁠ server: the FastAPI server in the adate project's compose/zimage folder (POST /generate, GET /images/{id}, GET /health).
• Unsloth Studio — the image models of an Unsloth Studio⁠ server. Enter the Studio address (with or without /v1) and an API key from Studio's Settings → API. Studio keeps only one model on the GPU, so if it also serves your text model (as an OpenAI Compatible provider at http://<host>:<port>/v1), set Image model too — e.g. unsloth/Z-Image-Turbo-GGUF:z-image-turbo-Q8_0.gguf (a Hub repo id, optionally : plus a checkpoint file). ABook then loads it before rendering whenever no image model is loaded, and Studio unloads the text model to make room. Leave it blank to use whatever is loaded on Studio's Images page.

Workflow: enable Illustrate this book in the book settings → write the book → open 🎨 Illustrations, review or edit the plan → Render portraits and re-roll any you don't like → Illustrate book.

⁠MCP Access

ABook includes a built-in Model Context Protocol⁠ server at /mcp. Any MCP-compatible client can connect to read and write book content and trigger agent workflows.

Tools (each tool's description says exactly what it does):