InkOS - Autonomous Novel Writing Agent

InkOS is a CLI tool for autonomous fiction writing powered by LLM agents. It orchestrates a 5-agent pipeline (Radar → Architect → Writer → Auditor → Reviser) to generate, audit, and revise novel content with style consistency and quality control.

The Writer uses a two-phase architecture: Phase 1 (creative writing, temp 0.7) produces the chapter text, then Phase 2 (state settlement, temp 0.3) updates all truth files for long-term consistency.

When to Use InkOS

Novel writing: Create and continue writing novels/books in Chinese web novel genres
Batch chapter generation: Generate multiple chapters with consistent quality
Import & continue: Import existing chapters from a text file, reverse-engineer truth files, and continue writing
Style imitation: Analyze and adopt writing styles from reference texts
Spinoff writing: Write prequels/sequels/spinoffs while maintaining parent canon
Quality auditing: Detect AI-generated content and perform 33-dimension quality checks
Genre exploration: Explore trends and create custom genre rules
Analytics: Track word count, audit pass rate, and issue distribution per book

Initial Setup

First Time Setup

bash

# Initialize a project directory (creates config structure)
inkos init my-writing-project

# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)
inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o
# For compatible/proxy endpoints, use --provider custom:
# inkos config set-global --provider custom --base-url https://your-proxy.com/v1 --api-key sk-xxx --model gpt-4o

Multi-Model Routing (Optional)

bash

# Assign different models to different agents — balance quality and cost
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

Agents without explicit overrides fall back to the global model.

View System Status

bash

# Check installation and configuration
inkos doctor

# View current config
inkos status

Common Workflows

Workflow 1: Create a New Novel

Initialize and create book:

bash

inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000
# Or with a creative brief (your worldbuilding doc / ideas):
inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md

Genres:
```
xuanhuan
```
(cultivation),
```
xianxia
```
(immortal),
```
urban
```
(city),
```
horror
```
,
```
other
```
Returns a
```
book-id
```
for all subsequent operations

Generate initial chapters (e.g., 5 chapters):
bash
```
inkos write next book-id --count 5 --words 3000 --context "young protagonist discovering powers"
```
- The
```
write next
```
  command runs the full pipeline: draft → audit → revise
- ```
--context
```
  provides guidance to the Architect and Writer agents
- Returns JSON with chapter details and quality metrics

Review and approve chapters:

bash

inkos review list book-id
inkos review approve-all book-id

Export the book (supports txt, md, epub):

bash

inkos export book-id
inkos export book-id --format epub

Workflow 2: Continue Writing Existing Novel

List your books:
bash
```
inkos book list
```
Continue from last chapter:
bash
```
inkos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"
```
- InkOS maintains 7 truth files (world state, character matrix, emotional arcs, etc.) for consistency
- If only one book exists, omit
```
book-id
```
  for auto-detection
Review and approve:
bash
```
inkos review approve-all
```

Workflow 3: Import Existing Chapters & Continue

Use this when you have an existing novel (or partial novel) and want InkOS to pick up where it left off.

Import from a single text file (auto-splits by chapter headings):
bash
```
inkos import chapters book-id --from novel.txt
```
- Automatically splits by
```
第X章
```
  pattern
- Custom split pattern:
```
--split "Chapter\\s+\\d+"
```
Import from a directory of separate chapter files:
bash
```
inkos import chapters book-id --from ./chapters/
```
- Reads
```
.md
```
  and
```
.txt
```
  files in sorted order

Resume interrupted import:

bash

inkos import chapters book-id --from novel.txt --resume-from 15

Continue writing from the imported chapters:
bash
```
inkos write next book-id --count 3
```
- InkOS reverse-engineers all 7 truth files from the imported chapters
- Generates a style guide from the existing text
- New chapters maintain consistency with imported content

Workflow 4: Style Imitation

Analyze reference text:
bash
```
inkos style analyze reference_text.txt
```
- Examines vocabulary, sentence structure, tone, pacing
Import style to your book:
bash
```
inkos style import reference_text.txt book-id --name "Author Name"
```
- All future chapters adopt this style profile
- Style rules become part of the Reviser's audit criteria

Workflow 5: Spinoff/Prequel Writing

Import parent canon:
bash
```
inkos import canon spinoff-book-id --from parent-book-id
```
- Creates links to parent book's world state, characters, and events
- Reviser enforces canon consistency

Continue spinoff:

bash

inkos write next spinoff-book-id --count 3 --context "alternate timeline after Chapter 20"

Workflow 6: Fine-Grained Control (Draft → Audit → Revise)

If you need separate control over each pipeline stage:

Generate draft only:

bash

inkos draft book-id --words 3000 --context "protagonist escapes" --json

Audit the chapter (33-dimension quality check):
bash
```
inkos audit book-id chapter-1 --json
```
- Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more
Revise with specific mode:
bash
```
inkos revise book-id chapter-1 --mode polish --json
```
- Modes:
```
polish
```
  (minor),
```
spot-fix
```
  (targeted),
```
rewrite
```
  (major),
```
rework
```
  (structure),
```
anti-detect
```
  (reduce AI traces)

Workflow 7: Monitor Platform Trends

bash

inkos radar scan

Analyzes trending genres, tropes, and reader preferences
Informs Architect recommendations for new books

Workflow 8: Detect AI-Generated Content

bash

# Detect AIGC in a specific chapter
inkos detect book-id

# Deep scan all chapters
inkos detect book-id --all

Uses 11 deterministic rules (zero LLM cost) + optional LLM validation
Returns detection confidence and problematic passages

Workflow 9: View Analytics

bash

inkos analytics book-id --json
# Shorthand alias
inkos stats book-id --json

Total chapters, word count, average words per chapter
Audit pass rate and top issue categories
Chapters with most issues, status distribution
Token usage stats: total prompt/completion tokens, avg tokens per chapter, recent trend

Advanced: Natural Language Agent Mode

For flexible, conversational requests:

bash

inkos agent "写一部都市题材的小说，主角是一个年轻律师，第一章三千字"

Agent interprets natural language and invokes appropriate commands
Useful for complex multi-step requests

Key Concepts

Book ID Auto-Detection

If your project contains only one book, most commands accept

book-id

as optional. You can omit it for brevity:

bash

# Explicit
inkos write next book-123 --count 1

# Auto-detected (if only one book exists)
inkos write next --count 1

--json Flag

All content-generating commands support

--json

for structured output. Essential for programmatic use:

bash

inkos draft book-id --words 3000 --context "guidance" --json

Truth Files (Long-Term Memory)

InkOS maintains 7 files per book for coherence:

World State: Maps, locations, technology levels, magic systems
Character Matrix: Names, relationships, arcs, motivations
Resource Ledger: In-world items, money, power levels
Chapter Summaries: Events, progression, foreshadowing
Subplot Board: Active and dormant subplots, hooks
Emotional Arcs: Character emotional progression
Pending Hooks: Unresolved cliffhangers and promises to reader

All agents reference these to maintain long-term consistency. During

import chapters

, these files are reverse-engineered from existing content via the ChapterAnalyzerAgent.

Two-Phase Writer Architecture

The Writer agent operates in two phases:

Phase 1 (Creative): Generates the chapter text at temperature 0.7 for creative expression. Only outputs chapter title and content.
Phase 2 (Settlement): Updates all truth files at temperature 0.3 for precise state tracking. Ensures world state, character arcs, and plot hooks stay consistent.

This separation allows creative freedom in writing while maintaining rigorous continuity tracking.

Context Guidance

The

--context

parameter provides directional hints to the Writer and Architect:

bash

inkos write next book-id --count 2 --context "protagonist discovers betrayal, must decide whether to trust mentor"

Context is optional but highly recommended for narrative coherence
Supports both English and Chinese

Genre Management

View Built-In Genres

bash

inkos genre list
inkos genre show xuanhuan

Create Custom Genre

bash

inkos genre create --name "my-genre" --rules "rule1,rule2,rule3"

Copy and Modify Existing Genre

bash

inkos genre copy xuanhuan --name "dark-xuanhuan" --rules "darker tone, more violence"

Command Reference Summary

Command	Purpose	Notes
`inkos init [name]`	Initialize project	One-time setup
`inkos book create`	Create new book	Returns book-id. `--brief <file>` for creative brief
`inkos book list`	List all books	Shows IDs, statuses
`inkos write next`	Full pipeline (draft→audit→revise)	Primary workflow command
`inkos draft`	Generate draft only	No auditing/revision
`inkos audit`	33-dimension quality check	Standalone evaluation
`inkos revise`	Revise chapter	Modes: polish/spot-fix/rewrite/rework/anti-detect
`inkos agent`	Natural language interface	Flexible requests
`inkos style analyze`	Analyze reference text	Extracts style profile
`inkos style import`	Apply style to book	Makes style permanent
`inkos import canon`	Link spinoff to parent	For prequels/sequels
`inkos import chapters`	Import existing chapters	Reverse-engineers truth files for continuation
`inkos detect`	AIGC detection	Flags AI-generated passages
`inkos export`	Export finished book	Formats: txt, md, epub
`inkos analytics` / `inkos stats`	View book statistics	Word count, audit rates, token usage
`inkos radar scan`	Platform trend analysis	Informs new book ideas
`inkos config set-global`	Configure LLM provider	OpenAI/Anthropic/custom (any OpenAI-compatible)
`inkos config set-model <agent> <model>`	Set model override for a specific agent	`--provider` , `--base-url` , `--api-key-env` for multi-provider routing
`inkos config show-models`	Show current model routing	View per-agent model assignments
`inkos doctor`	Diagnose issues	Check installation
`inkos update`	Update to latest version	Self-update
`inkos up/down`	Daemon mode	Background processing. Logs to `inkos.log` (JSON Lines). `-q` for quiet mode
`inkos review list/approve-all`	Manage chapter approvals	Quality gate

Error Handling

Common Issues

"book-id not found"

Verify the ID with
```
inkos book list
```
Ensure you're in the correct project directory

"Provider not configured"

Run
```
inkos config set-global
```
with valid credentials
Check API key and base URL with
```
inkos doctor
```

"Context invalid"

Ensure
```
--context
```
is a string (wrap in quotes if multi-word)
Context can be in English or Chinese

"Audit failed"

Check chapter for encoding issues
Ensure chapter-words matches actual word count
Try
```
inkos revise
```
with
```
--mode rewrite
```

"Book already has chapters" (import)

Use
```
--resume-from <n>
```
to append to existing chapters
Or delete existing chapters first

Running Daemon Mode

For long-running operations:

bash

# Start background daemon
inkos up

# Stop daemon
inkos down

# Daemon auto-processes queued chapters

Tips for Best Results

Provide rich context: The more guidance in
```
--context
```
, the more coherent the narrative
Start with style: If imitating an author, run
```
inkos style import
```
before generation
Import first: For existing novels, use
```
inkos import chapters
```
to bootstrap truth files before continuing
Review regularly: Use
```
inkos review
```
to catch issues early
Monitor audits: Check
```
inkos audit
```
metrics to understand quality bottlenecks
Use spinoffs strategically: Import canon before writing prequels/sequels
Batch generation: Generate multiple chapters together (better continuity)
Check analytics: Use
```
inkos analytics
```
to track quality trends over time
Export frequently: Keep backups with
```
inkos export
```

Support & Resources

Homepage: https://github.com/Narcooo/inkos
Configuration: Stored in project root after
```
inkos init
```
Truth files: Located in
```
.inkos/
```
directory per book
Logs: Check output of
```
inkos doctor
```
for troubleshooting

inkos

NPX Install

Tags

SKILL.md Content

InkOS - Autonomous Novel Writing Agent

When to Use InkOS

Initial Setup

First Time Setup

Multi-Model Routing (Optional)

View System Status

Common Workflows

Workflow 1: Create a New Novel

Workflow 2: Continue Writing Existing Novel

Workflow 3: Import Existing Chapters & Continue

Workflow 4: Style Imitation

Workflow 5: Spinoff/Prequel Writing

Workflow 6: Fine-Grained Control (Draft → Audit → Revise)

Workflow 7: Monitor Platform Trends

Workflow 8: Detect AI-Generated Content

Workflow 9: View Analytics

Advanced: Natural Language Agent Mode

Key Concepts

Book ID Auto-Detection

--json Flag

Truth Files (Long-Term Memory)

Two-Phase Writer Architecture

Context Guidance

Genre Management

View Built-In Genres

Create Custom Genre

Copy and Modify Existing Genre

Command Reference Summary

Error Handling

Common Issues

Running Daemon Mode

Tips for Best Results

Support & Resources