inkos

Autonomous Novel Writing CLI Agent

中文 | English

---

Open-source CLI agent that autonomously writes, audits, and revises novels — with human review gates that keep you in control.

Quick Start

Install

npm i -g @actalk/inkos

Configure

Option 1: Global config (recommended, one-time setup)

inkos config set-global \
  --provider openai \
  --base-url https://api.openai.com/v1 \
  --api-key sk-xxx \
  --model gpt-4o

Saved to ~/.inkos/.env, shared by all projects. New projects just work without extra config.

Option 2: Per-project .env

inkos init my-novel     # Initialize project
# Edit my-novel/.env

# Required
INKOS_LLM_PROVIDER=openai                        # openai / anthropic
INKOS_LLM_BASE_URL=https://api.openai.com/v1     # API endpoint (proxy-friendly)
INKOS_LLM_API_KEY=sk-xxx                          # API Key
INKOS_LLM_MODEL=gpt-4o                            # Model name

# Optional
# INKOS_LLM_TEMPERATURE=0.7                       # Temperature
# INKOS_LLM_MAX_TOKENS=8192                        # Max output tokens
# INKOS_LLM_THINKING_BUDGET=0                      # Anthropic extended thinking budget

Project .env overrides global config. Skip it if no override needed.

Write Your First Book

inkos book create --title "Devouring Emperor" --genre xuanhuan  # Create a book
inkos write next my-book          # Write next chapter (full pipeline: draft → audit → revise)
inkos status                      # Check status
inkos review list my-book         # Review drafts
inkos review approve-all my-book  # Batch approve
inkos export my-book              # Export full book
inkos export my-book --format epub  # Export EPUB (read on phone/Kindle)

---

Why InkOS?

Writing a novel with AI isn't just "prompt and paste." Long-form fiction breaks down fast: characters forget things, items appear from nowhere, the same adjectives repeat every paragraph, and plot threads silently die. InkOS treats these as engineering problems.

• Canonical truth files — track the real state of the world, not what the LLM hallucinates
• Anti-information-leaking — characters only know what they've actually witnessed
• Resource decay — supplies deplete and items break, no infinite backpacks
• Vocabulary fatigue detection — catches overused words before readers do
• Auto-revision — fixes math errors and continuity breaks before human review

How It Works

Each chapter is produced by five agents in sequence:

Agent	Responsibility
Radar	Scans platform trends and reader preferences to inform story direction (pluggable, skippable)
Architect	Plans chapter structure: outline, scene beats, pacing targets
Writer	Produces prose from the plan + current world state
Continuity Auditor	Validates the draft against canonical truth files
Reviser	Fixes issues found by the auditor — auto-fixes critical problems, flags others for human review

If the audit fails, the pipeline automatically enters a revise → re-audit loop until all critical issues are resolved.

Canonical Truth Files

Every book maintains 7 truth files as the single source of truth:

File	Purpose
current_state.md	World state: character locations, relationships, knowledge, emotional arcs
particle_ledger.md	Resource accounting: items, money, supplies with quantities and decay tracking
pending_hooks.md	Open plot threads: foreshadowing planted, promises to readers, unresolved conflicts
chapter_summaries.md	Per-chapter summaries: characters, key events, state changes, hook dynamics
subplot_board.md	Subplot progress board: A/B/C line status tracking
emotional_arcs.md	Emotional arcs: per-character emotion tracking and growth
character_matrix.md	Character interaction matrix: encounter records, information boundaries

The Continuity Auditor checks every draft against these files. If a character "remembers" something they never witnessed, or pulls a weapon they lost two chapters ago, the auditor catches it. Legacy books without new truth files are automatically compatible.

Writing Rule System

The Writer agent has ~25 universal writing rules (character craft, narrative technique, logical consistency, language constraints, de-AI-ification), applicable to all genres.

On top of that, each genre has dedicated rules (prohibitions, language rules, pacing, audit dimensions), and each book has its own book_rules.md (protagonist personality, numerical caps, custom prohibitions) and story_bible.md (worldbuilding), auto-generated by the Architect agent.

See CHANGELOG for details.

Three Usage Modes

InkOS provides three interaction modes, all sharing the same atomic operations:

1. Full Pipeline (One Command)

inkos write next my-book              # Draft → audit → auto-revise, all in one
inkos write next my-book --count 5    # Write 5 chapters in sequence

2. Atomic Commands (Composable, External Agent Friendly)

inkos draft my-book --context "Focus on master-disciple conflict" --json
inkos audit my-book 31 --json
inkos revise my-book 31 --json

Each command performs a single operation independently. --json outputs structured data. Can be called by OpenClaw or other AI agents via exec, or used in scripts.

3. Natural Language Agent Mode

inkos agent "Write an urban cultivation novel with a programmer protagonist"
inkos agent "Write the next chapter, focus on master-disciple conflict"
inkos agent "Scan market trends first, then create a new book based on results"

13 built-in tools (write_draft, audit_chapter, revise_chapter, scan_market, create_book, get_book_status, read_truth_files, list_books, write_full_pipeline, web_fetch, import_style, import_canon, import_chapters), with the LLM deciding call order via tool-use.

CLI Reference

Command	Description
inkos init [name]	Initialize project (omit name to init current directory)
inkos book create	Create a new book (--genre, --platform, --chapter-words, --target-chapters, --brief <file> for creative brief)
inkos book update [id]	Update book settings (--chapter-words, --target-chapters, --status)
inkos book list	List all books
inkos genre list/show/copy/create	View, copy, or create genres
inkos write next [id]	Full pipeline: write next chapter (--words to override, --count for batch, -q quiet mode)
inkos write rewrite [id] <n>	Rewrite chapter N (restores state snapshot, --force to skip confirmation, --words to override)
inkos draft [id]	Write draft only (--words to override word count, -q quiet mode)
inkos audit [id] [n]	Audit a specific chapter
inkos revise [id] [n]	Revise a specific chapter
inkos agent <instruction>	Natural language agent mode
inkos review list [id]	Review drafts
inkos review approve-all [id]	Batch approve
inkos status [id]	Project status
inkos export [id]	Export book (--format txt/md/epub, --output <path>, --approved-only)
inkos radar scan	Scan platform trends
inkos config set-global	Set global LLM config (~/.inkos/.env)
inkos config show-global	Show global config
inkos config set/show	View/update project config
inkos config set-model <agent> <model>	Set model override for a specific agent (--base-url, --provider, --api-key-env for multi-provider routing)
inkos config remove-model <agent>	Remove agent model override (fall back to default)
inkos config show-models	Show current model routing
inkos doctor	Diagnose setup issues (API connectivity test + provider compatibility hints)
inkos detect [id] [n]	AIGC detection (--all for all chapters, --stats for statistics)
inkos style analyze <file>	Analyze reference text to extract style fingerprint
inkos style import <file> [id]	Import style fingerprint into a book
inkos import canon [id] --from <parent>	Import parent canon for spinoff writing
inkos import chapters [id] --from <path>	Import existing chapters for continuation (--split, --resume-from)
inkos analytics [id] / inkos stats [id]	Book analytics (audit pass rate, top issues, chapter ranking, token usage)
inkos update	Update to latest version
inkos up / down	Start/stop daemon (-q quiet mode, auto-writes inkos.log)

[id] is auto-detected when the project has only one book. All commands support --json for structured output. draft/write next support --context for writing guidance and --words to override per-chapter word count. book create supports --brief <file> to pass a creative brief (your brainstorming/worldbuilding doc) — the Architect builds from your ideas instead of generating from scratch.

Key Features

State Snapshots + Chapter Rewrite

Every chapter automatically creates a state snapshot. Use inkos write rewrite <id> <n> to roll back and regenerate any chapter — world state, resource ledger, and plot hooks all restore to the pre-chapter state.

Write Lock

File-based locking prevents concurrent writes to the same book.

Pre-Write Checklist + Post-Write Settlement

The Writer agent outputs a pre-write checklist before writing (context scope, current resources, pending hooks, conflict overview, risk scan), and a settlement table after writing (resource changes, hook changes). The Auditor cross-validates the settlement table against prose content.

Pluggable Radar

Radar data sources are pluggable via the RadarSource interface. Built-in sources for Tomato Novel and Qidian. Custom data sources or skipping radar entirely are both supported.

Daemon Mode

inkos up starts an autonomous background loop that writes chapters on a schedule. The pipeline runs fully unattended for non-critical issues, but pauses for human review when the auditor flags problems it cannot auto-fix. All logs are written to inkos.log (JSON Lines format) in the project root. Use -q to suppress stderr and keep only file logging.

Notifications

Telegram, Feishu, WeCom, and Webhook. In daemon mode, get notified on your phone when a chapter is done or an audit fails. Webhook supports HMAC-SHA256 signing and event filtering.

External Agent Integration

Atomic commands + --json output make InkOS callable by OpenClaw and other AI agents. OpenClaw executes inkos draft/audit/revise via exec, reads JSON results, and decides next steps.

Architecture

inkos/
├── packages/
│   ├── core/              # Agent runtime, pipeline, state management
│   │   ├── agents/        # architect, writer, continuity, reviser, radar, ai-tells, post-write-validator, sensitive-words, detector, style-analyzer
│   │   ├── pipeline/      # runner, agent (tool-use), scheduler, detection-runner
│   │   ├── state/         # File-based state manager (7 truth files + snapshots)
│   │   ├── llm/           # OpenAI + Anthropic dual SDK (streaming)
│   │   ├── notify/        # Telegram, Feishu, WeCom, Webhook
│   │   └── models/        # Zod schema validation
│   └── cli/               # Commander.js CLI (22 commands)
│       └── commands/      # init, book, write, draft, audit, revise, agent, review, detect, style...
└── (planned) studio/      # Web UI for review and editing

TypeScript monorepo managed with pnpm workspaces.

Roadmap

• Full pipeline (radar → architect → writer → auditor → reviser)
• Canonical truth files + continuity audit
• Built-in writing rule system
• Full CLI (22 commands)
• State snapshots + chapter rewrite
• Daemon mode
• Notifications (Telegram / Feishu / WeCom)
• Atomic commands + JSON output (draft / audit / revise)
• Natural language agent mode (tool-use orchestration)
• Pluggable radar (RadarSource interface)
• External agent integration (OpenClaw, etc.)
• Genre customization + per-book rules (genre CLI + book_rules.md)
• 33-dimension continuity audit (including AI-tell detection + spinoff dims + outline adherence)
• De-AI-ification rules + style fingerprint injection
• Spinoff writing (canon import + 4 audit dimensions + info boundary control)
• Style cloning (statistical fingerprint + LLM style guide + Writer injection)
• Post-write validator (11 hard rules + auto spot-fix)
• Audit-revise loop hardening (AI marker guard + temperature lock)
• Multi-LLM provider (OpenAI + Anthropic + compatible endpoints)
• AIGC detection + anti-detect rewrite pipeline
• Webhook notifications + smart scheduler (quality gates)
• Cross-chapter coherence (chapter summaries + subplot/emotion/character matrices)
• Continuation writing (import chapters + auto reverse-engineer truth files + resumable import)
• Multi-provider agent routing (different agents use different API endpoints and keys, inkos config set-model --base-url --provider)
• Analytics (inkos analytics: audit pass rate, top issues, chapter ranking, token usage stats)
• EPUB export (inkos export --format epub, read on phone/Kindle)
• Structured logging (ANSI colors, JSON Lines file logging, quiet mode, LLM streaming heartbeat)
• Stream auto-fallback (auto sync retry when SSE fails — compatible with Zhipu, Gemini proxies, etc.)
• Local model compatibility (fallback parsing + partial response recovery on stream interruption)
• Creative brief (book create --brief — pass your brainstorming doc, Architect builds from it)
• packages/studio Web UI for review and editing (Vite + React + Hono)
• Partial chapter intervention (rewrite half a chapter + cascade truth file updates)
• Full English novel support (English genre profiles, prompts, audit rules, post-write validator)
• Custom agent plugin system
• Platform-specific export (Qidian, Tomato, etc.)

Contributing

Contributions welcome. Open an issue or PR.

pnpm install
pnpm dev          # Watch mode for all packages
pnpm test         # Run tests
pnpm typecheck    # Type-check without emitting

License

MIT