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.

Native English support — 10 built-in English genre profiles with dedicated pacing rules, fatigue word lists, and audit dimensions. Set --lang en and go.

Quick Start

Install

npm i -g @actalk/inkos

Use via OpenClaw 🦞

InkOS is published as an OpenClaw Skill, callable by any compatible agent (Claude Code, OpenClaw, etc.):

clawhub install inkos          # Install from ClawHub

If you installed via npm or cloned the repo, skills/SKILL.md is already included — 🦞 can read it directly without a separate ClawHub install.

Once installed, Claw can invoke all InkOS atomic commands (draft/audit/revise/write next) via exec, with --json output for structured decision-making. You can also browse it on ClawHub by searching inkos.

Configure

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

inkos config set-global \
  --lang en \
  --provider <openai|anthropic|custom> \
  --base-url <API endpoint> \
  --api-key <your API key> \
  --model <model name>

# Example: OpenAI
# inkos config set-global --lang en --provider openai --base-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o
# Example: Anthropic
# inkos config set-global --lang en --provider anthropic --base-url https://api.anthropic.com --api-key sk-ant-xxx --model claude-sonnet-4-20250514
# Example: Any OpenAI-compatible endpoint (proxies, local models, etc.)
# inkos config set-global --lang en --provider custom --base-url https://your-endpoint.com/v1 --api-key sk-xxx --model gpt-4o

--lang en sets English as the default writing language for all projects. Saved to ~/.inkos/.env. 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 / anthropic / custom (use custom for any OpenAI-compatible API)
INKOS_LLM_BASE_URL=                               # API endpoint
INKOS_LLM_API_KEY=                                 # API Key
INKOS_LLM_MODEL=                                   # Model name

# Language (defaults to global setting or genre default)
# INKOS_DEFAULT_LANGUAGE=en                        # en or zh

# 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.

Option 3: Multi-model routing (optional)

Assign different models to different agents — balance quality and cost:

# Writer uses Claude (stronger creative), Auditor uses GPT-4o (cheaper & fast)
inkos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY
inkos config set-model auditor gpt-4o --provider openai
inkos config show-models        # View current routing

Agents without explicit overrides fall back to the global model.

Write Your First Book

English is the default for English genre profiles. Pick a genre and go:

inkos book create --title "The Last Delver" --genre litrpg     # LitRPG novel (English by default)
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 --format epub  # Export EPUB (read on phone/Kindle)

Language is set per-genre by default. Override explicitly with --lang en or --lang zh. Use inkos genre list to see all available genres and their default languages.

---

English Genre Profiles

InkOS ships with 10 English-native genre profiles. Each includes genre-specific rules, pacing, fatigue word detection, and audit dimensions:

Genre	Key Mechanics
LitRPG	Numerical system, power scaling, stat progression
Progression Fantasy	Power scaling, no numerical system required
Isekai	Era research, world contrast, cultural fish-out-of-water
Cultivation	Power scaling, realm progression
System Apocalypse	Numerical system, survival mechanics
Dungeon Core	Numerical system, power scaling, territory management
Romantasy	Emotional arcs, dual POV pacing
Sci-Fi	Era research, tech consistency
Tower Climber	Numerical system, floor progression
Cozy Fantasy	Low-stakes pacing, comfort-first tone

Also supports 5 Chinese web novel genres (xuanhuan, xianxia, urban, horror, other) for bilingual creators.

Every genre includes a fatigue word list (e.g., "delve", "tapestry", "testament", "intricate", "pivotal" for LitRPG) — the auditor flags these automatically so your prose doesn't read like every other AI-generated novel.

---

Key Features

33-Dimension Audit + De-AI-ification

The Continuity Auditor checks every draft across 33 dimensions: character memory, resource continuity, hook payoff, outline adherence, narrative pacing, emotional arcs, and more. Built-in AI-tell detection automatically catches "LLM voice" — overused words, monotonous sentence patterns, excessive summarization. Failed audits trigger an automatic revision loop.

De-AI-ification rules are baked into the Writer agent's prompts: fatigue word lists, banned patterns, style fingerprint injection — reducing AI traces at the source. revise --mode anti-detect runs dedicated anti-detection rewriting on existing chapters.

Style Cloning

inkos style analyze examines reference text and extracts a statistical fingerprint (sentence length distribution, word frequency patterns, rhythm profiles) plus an LLM-readable style guide. inkos style import injects this fingerprint into a book — all future chapters adopt the style, and the Reviser audits against it.

Creative Brief

inkos book create --brief my-ideas.md — pass your brainstorming notes, worldbuilding doc, or character sheets. The Architect agent builds from your brief (generating story_bible.md and book_rules.md) instead of inventing from scratch.

Continuation Writing

inkos import chapters imports existing novel text, auto reverse-engineers all 7 truth files (world state, character matrix, resource ledger, plot hooks, etc.), supports Chapter N and custom split patterns, and resumable import. After import, inkos write next seamlessly continues the story.

Fan Fiction

inkos fanfic init --from source.txt --mode canon creates a fanfic book from source material. Four modes: canon (faithful continuation), au (alternate universe), ooc (out of character), cp (ship-focused). Includes a canon importer, fanfic-specific audit dimensions, and information boundary controls to keep lore consistent.

Multi-Model Routing

Different agents can use different models and providers. Writer on Claude (stronger creative), Auditor on GPT-4o (cheaper and fast), Radar on a local model (zero cost). inkos config set-model configures per-agent; unconfigured agents fall back to the global model.

Daemon Mode + Notifications

inkos up starts an autonomous background loop that writes chapters on a schedule. The pipeline runs fully unattended for non-critical issues, pausing for human review when needed. Notifications via Telegram and Webhook (HMAC-SHA256 signing + event filtering). Logs to inkos.log (JSON Lines), -q for quiet mode.

Local Model Compatibility

Supports any OpenAI-compatible endpoint (--provider custom). Stream auto-fallback — when SSE isn't supported, InkOS retries with sync mode automatically. Fallback parser handles non-standard output from smaller models, and partial content recovery kicks in on stream interruption.

Reliability

Every chapter creates an automatic state snapshot — inkos write rewrite rolls back any chapter to its pre-write state. The Writer outputs a pre-write checklist (context scope, resources, pending hooks, risks) and a post-write settlement table; the Auditor cross-validates both. File locking prevents concurrent writes. Post-write validator enforces 11 hard rules with auto spot-fix.

---

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 via RadarSource interface — skip it or bring your own data source
Architect	Plans chapter structure: outline, scene beats, pacing targets
Writer	Produces prose from the plan + current world state (two-phase: creative writing → state settlement)
Continuity Auditor	Validates the draft against 7 canonical truth files, 33-dimension check
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.

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 constraints, 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.

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 the dungeon boss encounter and party dynamics" --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 external AI agents via exec, or used in scripts.

3. Natural Language Agent Mode

inkos agent "Write a LitRPG novel where the MC is a healer class in a dungeon world"
inkos agent "Write the next chapter, focus on the boss fight and loot distribution"
inkos agent "Create a progression fantasy about a mage who can only use one spell"

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, --chapter-words, --target-chapters, --brief <file>, --lang en/zh)
inkos book update [id]	Update book settings (--chapter-words, --target-chapters, --status, --lang)
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)
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 fanfic init	Create a fanfic book from source material (--from, --mode canon/au/ooc/cp)
inkos config set-global	Set global LLM config (~/.inkos/.env)
inkos config set-model <agent> <model>	Per-agent model override (--base-url, --provider, --api-key-env)
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 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 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. book create supports --brief <file> to pass a creative brief — the Architect builds from your ideas instead of generating from scratch.

Roadmap

• packages/studio Web UI for review and editing (Vite + React + Hono)
• Partial chapter intervention (rewrite half a chapter + cascade truth file updates)
• Novel-to-comic pipeline (truth files → storyboard → manga pages)
• Custom agent plugin system

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