Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/Narcooo/inkos

Autonomous novel writing CLI agent — AI agents write, audit, and revise novels with human review gates
https://github.com/Narcooo/inkos

agent ai-writing aigc-detection automated-storytelling chinese-novel cli-tool creative-writing-ai novel-generation

Last synced: 10 days ago
JSON representation

Autonomous novel writing CLI agent — AI agents write, audit, and revise novels with human review gates

Awesome Lists containing this project

README 

          


  InkOS Logo

  InkOS




Autonomous Novel Writing Cli AI Agent





  npm version

  License: MIT

  Node.js

  TypeScript






  中文 | English




---



Open-source CLI agent that autonomously writes, audits, and revises novels — with human review gates that keep you in control. Supports LitRPG, Progression Fantasy, Isekai, Romantasy, Sci-Fi, and more. Continuation, spinoff, fanfic, and style imitation workflows built in.



**Native English novel writing now supported！** — 10 built-in English genre profiles with dedicated pacing rules, fatigue word lists, and audit dimensions. Set `--lang en` and go.



## Quick Start



### Install



```bash

npm i -g @actalk/inkos

```



### Use via OpenClaw 🦞



InkOS is published as an [OpenClaw](https://clawhub.ai) Skill, callable by any compatible agent (Claude Code, OpenClaw, etc.):



```bash

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](https://clawhub.ai) by searching `inkos`.



### Configure



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



```bash

inkos config set-global \

  --lang en \

  --provider  \

  --base-url  \

  --api-key  \

  --model 



# provider: openai / anthropic / custom (use custom for OpenAI-compatible proxies)

# base-url: your API provider URL

# api-key: your API key

# model: your model name

```



`--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`**



```bash

inkos init my-novel     # Initialize project

# Edit my-novel/.env

```



```bash

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



```bash

# Assign different models/providers to different agents

inkos config set-model writer  --provider  --base-url  --api-key-env 

inkos config set-model auditor  --provider 

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:



```bash

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.





  Terminal screenshot




---



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





  Pipeline diagram




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





  Truth files snapshot




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



```bash

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)



```bash

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



```bash

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 `, `--lang en/zh`) |

| `inkos book update [id]` | Update book settings (`--chapter-words`, `--target-chapters`, `--status`, `--lang`) |

| `inkos book list` | List all books |

| `inkos book delete ` | Delete a book and all its data (`--force` to skip confirmation) |

| `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] ` | 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 ` | 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 `, `--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  ` | 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 ` | Analyze reference text to extract style fingerprint |

| `inkos style import  [id]` | Import style fingerprint into a book |

| `inkos import chapters [id] --from ` | 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 ` 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.



```bash

pnpm install

pnpm dev          # Watch mode for all packages

pnpm test         # Run tests

pnpm typecheck    # Type-check without emitting

```



## License



[MIT](LICENSE)