inkos

InkOS - Story Creation AI Agent

InkOS is a story creation and multilingual translation AI agent for long-form novels, short fiction, scripts, storyboards, interactive-film projects, fan works, continuations, covers, open-world / branching interactive play, and long-document localization. Prefer the Studio Chat / action-surface workflow for natural-language requests: the model proposes or invokes typed actions, InkOS executes them, and completion is derived from real tool results and files, not from prose claims.

Long-form writing still uses the chapter pipeline internally:

• Input governance: Architect / Planner / Composer preserve author intent, current focus, outline sections, and relevant truth files instead of injecting everything blindly.
• Writing: Writer produces prose with length governance, craft rules, and context selected for the current task.
• Settlement and review: Observer / Reflector update runtime state; Auditor checks continuity and quality; Reviser handles critical issues. The default write cycle keeps automatic repair conservative and leaves unresolved issues visible for human or agent follow-up.

Truth files are persisted as schema-validated JSON (story/state/*.json) with markdown projections for human readability. SQLite temporal memory database (story/memory.db) enables relevance-based retrieval on Node 22+.

v1.7.1 Mental Model

Treat InkOS as a confirmable action system, not a bag of prompt shortcuts. v1.7.1 adds non-canonical narrative forecasting, background production tasks that do not block discussion, retryable task state, whole-book backup / restore, and rollback-safe latest-chapter deletion.

• Natural-language requests should go through Studio Chat / TUI / inkos interact whenever possible.
• Do not infer success from assistant prose. A book, short, cover, or play step is complete only when the corresponding tool result and files exist.
• Use short_fiction_run only for a standalone short-fiction package.
• Use generate_cover only for cover generation/regeneration.
• Use play_start / play_step for Open World or Branching Interactive sessions.
• Use script / storyboard / interactive-film tools only for production artifacts that should be saved and exported, not for casual discussion.
• Use the translation project workflow for EPUB, text-based PDF, TXT, or Markdown localization. Keep source and target languages, glossary, review report, and export format explicit; do not replace it with an ad hoc one-turn translation when the user wants a complete deliverable.
• Use research_web only when the user explicitly asks for external facts, market references, era/profession details, or worldbuilding research. Research reports are reference material and do not automatically mutate canon or prose.
• Use long-form chapter tools only for existing long-form books.
• Use narrative forecasts when the author wants to compare possible long-form directions before writing. A forecast is non-canonical planning material: selecting a branch may write selected-branch-plan.md, but it must not be described as changing prose, outlines, or canonical state.
• A running production task does not prevent ordinary discussion, but do not start another conflicting book mutation until that task reaches a terminal state.
• Agent Skills provide professional guidance and static references. They do not grant new file, network, image, or writing permissions by themselves.
• Context is governed: protected facts and current intent should not be silently compressed away; compressible history may be summarized when the context budget is tight.
• Studio Chat can receive user-uploaded text / Markdown / image attachments. Text attachments are injected into the LLM context; image attachments require a vision-capable model.
• External materials can be archived and retrieved later with evidence traces instead of relying on ad hoc pasted context.
• Prompt packs are user-tunable in Studio Project Settings. Project overrides are saved under prompt/<pack>/<prompt>.md; do not edit generated artifacts just to change system behavior.
• Long-form chapter revision from Chat passes the current user instruction into the reviser as a one-off brief. If the revision is not applied, inspect the returned gate metrics and remaining audit issues before claiming it was fixed.

v1.7.0 keeps the v1.6 interactive-film and Agent Skills model, then adds complete multilingual translation/localization, English-native short/script/storyboard/interactive-film paths, existing-novel import from Chat, configurable review and revision gates, abortable long tasks, recoverable write locks, material archive/retrieval, and Studio-editable prompt packs. Still surface unresolved review or execution issues plainly instead of claiming they were fixed.

When to Use InkOS

• English novel writing: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set --lang en
• Chinese web novel writing: 5 built-in Chinese genres (xuanhuan, xianxia, urban, horror, other)
• Fan fiction: Create fanfic from source material with 4 modes (canon, au, ooc, cp)
• 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
• Standalone short fiction: Generate a complete short-fiction package with outline, draft, review artifacts, synopsis, selling points, and optional cover image
• Cover generation: Generate or regenerate only a cover prompt and cover image from a title, synopsis, or visual direction without rerunning story writing
• Interactive worlds: Start Open World or Branching Interactive sessions with world contracts, character agents, inventory/evidence/relationship state, guided choices, free actions, and optional image generation
• Interactive-film projects: Create playable branch graphs, variables/flags, relationship state, endings, node images, and exportable interactive project packages
• Scripts and storyboards: Convert ideas, outlines, or prose into script/storyboard deliverables while preserving user format choices
• Long-document translation: Translate EPUB, text-based PDF, TXT, or Markdown by chapter and semantic segment, maintain terminology, review source and target side by side, and export TXT/Markdown/EPUB
• Agent Skills: Load standard AgentSkills/OpenClaw or project-local SKILL.md packages; let the Chat Agent invoke them from user intent, or force one with @skill-id
• Traceable web research: Create sourced Markdown reports for facts, era/profession details, markets, and worldbuilding references
• 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)
# Prefer --api-key-env so the key never appears in shell history:
export OPENAI_API_KEY=sk-xxx
inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o
# For compatible/proxy endpoints, use --provider custom and point ONLY to trusted endpoints:
# inkos config set-global --provider custom --base-url https://your-trusted-proxy.com/v1 --api-key-env OPENAI_API_KEY --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

Agents without explicit overrides fall back to the global model.

Provider setup tip

When the user needs an aggregator provider, point them to Studio's service settings. InkOS includes kkaiapi and OpenRouter as optional aggregator choices. For kkaiapi, use:

• Chinese website: https://kkaiapi.com/
• English website: https://en.kkaiapi.com/
• Chinese API docs: https://kkaiapi.com/docs
• English API docs: https://en.kkaiapi.com/docs
• Chinese models/pricing: https://kkaiapi.com/models
• English models/pricing: https://en.kkaiapi.com/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:

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

   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:

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

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

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

Workflow 2: Continue Writing Exis

Content truncated.