InkOS - Autonomous Novel Writing Agent

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

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

# 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

View System Status

# Check installation and configuration
inkos doctor

# View current config
inkos status

Common Workflows

Workflow 1: Create a New Novel

1. 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
2. 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
3. Review and approve chapters:
   bash

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

4. Export the book (supports txt, md, epub):
   bash

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

Workflow 2: Continue Writing Existing Novel

1. List your books:
   bash

   inkos book list

2. 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
3. Review and approve:
   bash

   inkos review approve-all

Workflow 3: Import Existing Chapters & Continue

1. 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+"

2. Import from a directory of separate chapter files:
   bash

   inkos import chapters book-id --from ./chapters/

   • Reads

     .md

     and

     .txt

     files in sorted order
3. Resume interrupted import:
   bash

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

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

1. Analyze reference text:
   bash

   inkos style analyze reference_text.txt

   • Examines vocabulary, sentence structure, tone, pacing
2. 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

1. 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
2. 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)

1. Generate draft only:
   bash

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

2. 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
3. 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

inkos radar scan

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

Workflow 8: Detect AI-Generated Content

# 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

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

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

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

Key Concepts

Book ID Auto-Detection

book-id

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

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

--json Flag

--json

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

Truth Files (Long-Term Memory)

• 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

import chapters

Two-Phase Writer Architecture

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

Context Guidance

--context

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

inkos genre list
inkos genre show xuanhuan

Create Custom Genre

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

Copy and Modify Existing Genre

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

Command Reference Summary

inkos init [name]

inkos book create

--brief <file>

inkos book list

inkos write next

inkos draft

inkos audit

inkos revise

inkos agent

inkos style analyze

inkos style import

inkos import canon

inkos import chapters

inkos detect

inkos export

inkos analytics

inkos stats

inkos radar scan

inkos config set-global

inkos config set-model <agent> <model>

--provider

--base-url

--api-key-env

inkos config show-models

inkos doctor

inkos update

inkos up/down

inkos.log

-q

inkos review list/approve-all

Error Handling

Common Issues

• Verify the ID with

  inkos book list

• Ensure you're in the correct project directory

• Run

  inkos config set-global

  with valid credentials
• Check API key and base URL with

  inkos doctor

• Ensure

  --context

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

• Check chapter for encoding issues
• Ensure chapter-words matches actual word count
• Try

  inkos revise

  with

  --mode rewrite

• Use

  --resume-from <n>

  to append to existing chapters
• Or delete existing chapters first

Running Daemon Mode

# Start background daemon
inkos up

# Stop daemon
inkos down

# Daemon auto-processes queued chapters

Tips for Best Results

1. Provide rich context: The more guidance in

   --context

   , the more coherent the narrative
2. Start with style: If imitating an author, run

   inkos style import

   before generation
3. Import first: For existing novels, use

   inkos import chapters

   to bootstrap truth files before continuing
4. Review regularly: Use

   inkos review

   to catch issues early
5. Monitor audits: Check

   inkos audit

   metrics to understand quality bottlenecks
6. Use spinoffs strategically: Import canon before writing prequels/sequels
7. Batch generation: Generate multiple chapters together (better continuity)
8. Check analytics: Use

   inkos analytics

   to track quality trends over time
9. 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