inkos

InkOS

Multi-Agent Novel Production System

中文 | English

---

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

v0.3 Update (2026-03-13)

Three-layer rule separation: core guardrails → genre-specific rules → per-book custom rules.

Genre Customization

5 built-in genres, each with a complete set of writing rules: chapter types, prohibition lists, fatigue words, language rules, and audit dimensions.

Genre	Built-in Rules
Xuanhuan (Fantasy)	Numerical system, power scaling, same-type absorption decay formula, face-slap/upgrade/payoff pacing
Xianxia (Cultivation)	Cultivation/enlightenment pacing, artifact system, heavenly dao rules
Urban	Era research, business/social-driven plot, era-matched legal terminology, no numerical system
Horror	Atmosphere progression, fear levels, restrained narration, no power scaling audit
General	Minimal fallback

Specify a genre when creating a book and matching rules activate automatically:

inkos book create --title "Devouring Emperor" --genre xuanhuan

View, copy, or create genre rules:

inkos genre list                      # List all genres
inkos genre show xuanhuan             # View full xuanhuan rules
inkos genre copy xuanhuan             # Copy to project for customization
inkos genre create wuxia --name Wuxia # Create a new genre from scratch

After copying to your project, add/remove prohibitions, adjust fatigue words, modify pacing rules, customize language rules — changes take effect on the next chapter.

Each genre has dedicated language rules (with bad → good examples), enforced by both writer and auditor:

• Xuanhuan: ✗ "Fire essence increased from 12 to 24 wisps" → ✓ "His arm felt stronger than before, knuckles tightening into a fist"
• Urban: ✗ "Quickly analyzed the current debt situation" → ✓ "Flipped through the stack of wrinkled IOUs three times"
• Horror: ✗ "Felt a wave of fear" → ✓ "The hairs on the back of his neck stood up one by one"

Per-Book Rules

Each book has its own book_rules.md, auto-generated by the Architect agent when creating a book — also editable anytime. Rules here are injected into every chapter's prompt:

protagonist:
  name: Lin Jin
  personalityLock: ["ruthlessly calm", "patient but lethal", "smart, not reckless"]
  behavioralConstraints: ["no mercy, no hesitation", "warm to allies but never sentimental"]
numericalSystemOverrides:
  hardCap: 840000000
  resourceTypes: ["particles", "bloodline density", "spirit stones"]
prohibitions:
  - protagonist goes soft at critical moments
  - pointless harem romance dragging the plot
  - side characters stealing the spotlight
fatigueWordsOverride: ["pupils constricted", "disbelief"]   # Override genre defaults

Protagonist personality lock, numerical caps, custom prohibitions, fatigue word overrides — each book's rules are independent, without affecting the genre template.

19-Dimension Audit

Auditing is broken down into 19 dimensions, with genre-appropriate subsets auto-enabled:

OOC check, timeline, setting conflicts, foreshadowing, pacing, writing style, information leaking, vocabulary fatigue, broken interest chains, side character intelligence drops, side character tool-ification, hollow payoffs, dialogue authenticity, padding detection, knowledge base contamination, POV consistency, power scaling collapse, numerical verification, era research

Xuanhuan/Xianxia: all 19 dimensions. Urban: 17 dimensions (including era research). Horror: 15 dimensions.

De-AI-ification

5 universal rules + genre-specific language rules to control AI marker word density and narration habits:

• AI marker word frequency limit: "as if" / "suddenly" / "unexpectedly" / "couldn't help but" — max 1 per 3,000 words
• Narrator never draws conclusions for the reader, only writes actions
• No analytical report language ("core motivation", "information gap" never appear in prose)
• Same imagery rendered no more than twice
• Methodology jargon stays out of prose

Vocabulary fatigue audit simultaneously checks marker word density — exceeding threshold triggers a warning.

Other

• Supports OpenAI + Anthropic native + all OpenAI-compatible endpoints
• Reviser supports polish / rewrite / rework modes
• Genres without numerical systems skip resource ledger generation
• All commands support --json structured output for OpenClaw / external agent integration
• Auto-detect book-id when project has only one book
• inkos update for self-updating, inkos init supports current directory
• API errors include diagnostic hints, inkos doctor includes connectivity test

---

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 three 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

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.

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 v0.3 Update 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"

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

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.

Usage

inkos book create --title "Devouring Emperor" --genre xuanhuan  # Create a book
inkos write next my-book          # Write next chapter (full pipeline)
inkos status                      # Check status
inkos review list my-book         # Review drafts
inkos export my-book              # Export full book
inkos up                          # Daemon mode

CLI Reference

Command	Description
inkos init [name]	Initialize project (omit name to init current directory)
inkos book create	Create a new book (generates worldbuilding + outline + book rules)
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
inkos write rewrite [id] <n>	Rewrite chapter N (restores state snapshot, requires confirmation)
inkos draft [id]	Write draft only (no audit or revision)
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 to txt/md
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 doctor	Diagnose setup issues (includes API connectivity test)
inkos update	Update to latest version
inkos up / down	Start/stop daemon

[id] is auto-detected when the project has only one book. All commands support --json for structured output. draft/write next/book create support --context for writing guidance.

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.

Notifications

Telegram, Feishu, and WeCom. In daemon mode, get notified on your phone when a chapter is done or an audit fails.

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
│   │   ├── pipeline/      # runner (atomic ops + full pipeline), agent (tool-use), scheduler
│   │   ├── state/         # File-based state manager
│   │   ├── llm/           # OpenAI + Anthropic dual SDK (streaming)
│   │   ├── notify/        # Telegram, Feishu, WeCom
│   │   └── models/        # Zod schema validation
│   └── cli/               # Commander.js CLI (16 commands)
│       └── commands/      # init, book, write, draft, audit, revise, agent, review, status, export...
└── (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 (16 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)
• 19-dimension continuity audit
• De-AI-ification rules
• Multi-LLM provider (OpenAI + Anthropic + compatible endpoints)
• AI detection review (AIGC detection + auto-rewrite to reduce detection rate)
• packages/studio Web UI for review and editing
• Multi-model routing (different models for different agents)
• 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