InkOS: A Story Creation AI Agent for Long Fiction, Scripts, and Interactive Games

What InkOS Solves and Who It Is For

Generating a long novel with an LLM through a plain chat interface produces incoherent results. Each new chapter loses track of earlier plot points, character decisions contradict earlier ones, and the context window fills with irrelevant dialogue. InkOS addresses this problem by maintaining a structured state for each project: a character registry, a world state, a story outline, and a history of what has been written, reviewed, and revised. The agent refers to this state when generating new content rather than relying on whatever fits in the immediate context.

The system is aimed at two groups. The first is writers who want to use AI assistance for long-form fiction, scripts, or translated novels without managing prompt engineering manually. The second is developers building storytelling products who need a production-grade pipeline with observable state, atomic writes, and failure recovery. The package.json describes the project as a story creation AI agent for novels, short fiction, scripts, interactive worlds, and multilingual translation.

InkOS is written in TypeScript, distributed as an npm package, and requires Node.js 22.16 or higher. The last push to the repository was on 2026-09-27.

The pi-agent Harness: One Execution Core for Every Interface

The central design decision in InkOS 2.0 is the consolidation of all execution paths into a single pi-agent harness. Previously, the Studio, TUI, and CLI might have had separate decision-making logic. Now they share the same action surface and the same tool loop. This means that what the Studio chat executes is identical to what the CLI executes, and both produce results that are auditable through the same run snapshot mechanism.

The harness model treats the LLM as the entity that understands and proposes actions. InkOS is the entity that confirms, records, and recovers from failures. The README describes this as: the model is responsible for understanding, proposing, and invoking capabilities; InkOS is responsible for confirmation, context, state, atomic writes, and output authenticity.

This separation has a practical consequence for reliability. When a writing job fails midway, the harness can resume from the last successful checkpoint rather than restarting from the beginning. Multi-chapter writing jobs run as a single recoverable task. The README notes that chapter workspaces validate content, state, foreshadowing, and run snapshots before atomic commit, preventing the situation where state has advanced but the chapter text has not been written to disk.

Installing InkOS and Starting a First Project

InkOS installs from npm as a global CLI tool:

npm i -g @actalk/inkos

The Studio interface, which combines chat, project management, and chapter preview, starts from an initialized project directory:

inkos init my-novel
cd my-novel
inkos

After running inkos, open the Studio from the URL shown in the startup log. The Studio provides visual service configuration for LLM providers. Supported providers include Google Gemini, Moonshot, MiniMax, Zhipu, Alibaba Bailian, OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. The CLI and Studio read from the same configuration, so credentials set through the Studio are available in CLI mode.

InkOS is also published as an OpenClaw skill, installable with:

clawhub install inkos

This makes it callable from Claude Code and other compatible agents. When installed via npm, the skills/SKILL.md file is included and readable by compatible agents without a separate ClawHub install.

Creation Modes: Long Fiction, Short Stories, Scripts, Interactive Play, and Translation

InkOS 2.0 supports several distinct production modes, each with its own state model and creative rules while sharing the common execution infrastructure.

Long fiction mode builds from a brief through world-building, character definitions, volume outlines, and chapter intents. Writing, reviewing, revision, and state settlement are independent callable actions, each traceable and recoverable. Context is organized by priority level (protected vs. compressible) to prevent long books from losing coherence as they grow.

The short fiction mode (InkOS Short) produces a complete standalone story with full text, outline, editorial notes, promotional copy, and a cover image when a cover service is configured. It runs through the same chat interface as long fiction.

InkOS Play adds open-world interactive fiction. You specify a world contract, time-advancement rules, character agents, item and evidence rules, and visual style. The system maintains world state, clickable choices, free-action input, and a HUD across play sessions.

Script, storyboard, and translation modes are also included, each with its own SKILL.md defining the methodology. The README notes that English-language novel writing is supported by passing --lang en.

The multi-branch story planning feature generates two to five isolated future branches from the current story state, allowing writers to compare narrative paths before committing to one. Selected branches save only a candidate plan file without modifying the main story.

19 Built-in Skills and the Custom Skill Extension Model

InkOS ships with 19 built-in professional skills, each defined by a SKILL.md file. These cover long-form writing, editorial review, commercial short fiction, Play mode, script writing, storyboarding, interactive games, translation, story breakdowns, market research, import, cover generation, and AI-register reduction (the README describes this as removing stylistic markers of AI writing).

The skill system uses a standard SKILL.md format. A minimal skill file looks like:

---
name: Detective Play
description: Detective evidence and suspect-board play.
---
Use evidence chains; do not turn clues into generic atmosphere.

Skills provide instructions and static reference material to the chat agent. They do not grant new execution permissions; all write operations still go through the InkOS tool layer and confirmation gates. Skills can be placed in the project skills/ directory, .agents/skills/, or the user-level ~/.agents/skills/. The INKOS_SKILL_DIRS environment variable points to additional skill directories.

To override a built-in skill method, you import a project skill with the same ID through the Studio. The agent then uses the project-level skill instead of the built-in.

Limitations: AGPL License, Node.js Version Requirements, and Compute Costs

InkOS is licensed under AGPL-3.0-only. This license requires that any software that uses or extends InkOS and is distributed over a network must also release its source code under AGPL. For a developer building a commercial writing product on top of InkOS, this is a significant constraint. The LICENSE file in the repository confirms this.

The Node.js version requirement is Node.js 22.16 or higher, as specified in the package.json engines field. The pnpm version requirement is 9.0.0 or higher for development. These are recent versions, and older server environments may not meet them without an upgrade.

Every writing operation makes LLM API calls. A long novel with regular review and revision cycles generates substantial token usage. The README mentions kkaiapi as a supported aggregation endpoint and notes that cover generation uses gpt-image-2. Costs depend on which models you configure and how many chapters your project has. The README does not provide cost estimates.

The v2.0.0 branch is described as a development version with local build verification. Projects migrated from 1.x must run the migration tool before continuing production work.

InkOS vs. Direct LLM Prompting for Long Fiction

Using an LLM directly for long fiction through a standard chat interface is the simplest approach and requires no installation. The limitation is that a chat interface has no persistent world state, no character registry, no outline tracking, and no revision workflow. As the story grows longer than the context window, earlier details are lost.

InkOS imposes a structured state model that the agent consults at each writing step. The protected vs. compressible context layering described in the README is a concrete mechanism for keeping critical story information (characters, major plot points) in the model's window even as the conversation grows.

The cost of this structure is setup time and operational complexity. You need to initialize a project, configure a model provider, understand the skill system, and migrate existing work when version changes require it. Direct prompting has none of these requirements. The right choice depends on the length and complexity of the project: short stories are well within direct prompting range, while multi-volume novels benefit from the state management InkOS provides.

Editorial conclusion

InkOS suits writers and developers who need a stateful, structured pipeline for long-form story creation with LLM support and revision tracking. The AGPL-3.0 license makes it unsuitable for proprietary SaaS products that do not intend to release their source. Before starting, verify your Node.js version is 22.16 or higher and configure your LLM API credentials, since InkOS routes all model calls through its own service configuration layer.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. Narcooo/inkos on GitHub
4. README
5. Releases