InkOS: an AGPL-3.0 story agent that keeps its own state
Story Creation AI Agent for novel, scripts, translation, interactive games, and IP content
At a glance
- What is it?
- InkOS is a TypeScript agent system for long novels, short fiction, scripts, interactive film-games and translation. Its distinguishing claim is not the writing model but the harness around it: atomic chapter commits, a shared SQLite FTS5 retrieval layer, and a confirmation gate on heavy actions.
- Who is it for?
- InkOS fits writers and small studios who want a self-hosted, scriptable pipeline for long-form serial fiction, short pieces, scripts, storyboards or interactive film-games, and who are comfortable with a Node 22 CLI and an OpenAI-compatible model endpoint. It does not fit anyone who needs a permissive licence for a closed product, or who wants a polished consumer writing app with no configuration.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 21 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem InkOS targets is continuity, not sentence quality
Most writing tools stop at the prompt. You paste a premise, you get a chapter, and the next chapter has no memory of the first. InkOS is built around the opposite assumption: the hard part of a long serial is keeping world state, character state, foreshadowing and prior text consistent across dozens or hundreds of chapters. The README frames the project as a system where "创意、设定、角色、记忆、审稿、修订、封面、互动状态和跨语言交付" are managed by the agent rather than by the writer's notes file. That is a state-management problem dressed as a writing problem. The intended users are people producing serialised content at volume: web novel authors, short-drama and script writers, translation teams, and developers building interactive narrative games. The topic list on the repository points the same way, listing chinese-novel, novel-generation, short-drama and storyboard alongside generic ai-agent tags. If you write one 2,000-word story a month, the machinery here is heavier than the task.
One harness for chat, TUI, CLI and workers
Version 1.8.0 is explicitly a consolidation release. The README states that InkOS 1.8.0 collapsed two previously separate things, the chat agent calling tools and the per-format production pipelines, into a single harness built around pi-agent. The division of labour is stated plainly: the model handles understanding, proposing and invoking capabilities; InkOS handles confirmation, context, state, atomic writes to disk, and verifying that artefacts are real. The old pipelines were demoted to deterministic capabilities that can be invoked directly, interrupted, and observed, rather than parallel natural-language decision cores. Concretely, Studio Chat, the TUI, the `inkos interact` command and the production workers share the same pi-agent tool loop and the same structured action/result shape. That matters for anyone integrating InkOS into a larger system: a command issued through the CLI entry point runs through the same execution kernel as the terminal UI, so behaviour should not diverge between surfaces. The README also warns integrators not to infer completion from the model's own prose. The JSON output of `inkos interact` contains assistant text plus interaction session metadata, but the README says the real execution result is determined by tool results and files written to disk.
Chapter workspaces and atomic commits
The mechanism worth understanding before you trust the output is the chapter workspace. According to the README, manuscript text, state, foreshadowing and run snapshots are first validated inside a chapter workspace and only then committed atomically. The failure mode this prevents is specific and familiar to anyone who has scripted a generation loop: state advances, the chapter text never lands on disk, and the project is now internally inconsistent. InkOS claims to avoid that split by treating the commit as a single unit. Studio can show the rewrite workspace and the actual review findings, which implies the review step produces inspectable artefacts rather than a pass/fail flag. A second mechanism sits on top of this: multi-chapter writing runs as a single recoverable task executed in order, with first-token and streaming idle timeouts, stale-state repair and atomic file sets. The README presents these as reducing the chance of passive hangs or half-finished runs. That is a plausible design, though it also tells you something about the operating environment: you are expected to point this at a model endpoint that may stall, and the harness is built to survive that rather than to prevent it.
Retrieval is a rebuildable projection over your own files
InkOS 1.8.0 introduced a unified local retrieval layer. Story memory, the material library, and skill reference material all share a SQLite FTS5 / BM25 index. The README is careful about the authority relationship: the original files remain the source of truth, the index can be rebuilt, and search results retain their source and position. That is the right ordering. An index that silently becomes authoritative is a data-loss trap. The related feature is book-level material binding. Imported material can be explicitly bound to a particular book and given a declared purpose, so that during writing the agent retrieves relevant passages for the current task instead of stuffing every file into the context window. This is the single most practical idea in the release notes for long projects. Anyone who has watched a context window fill with an entire worldbuilding folder will recognise the problem. The constraint is that binding is manual and declarative: the material does not bind itself, and retrieval quality depends on how you have described each source's purpose.
Install, model configuration and the interact entry point
The README requires Node.js 22 or higher and gives one install command: `npm i -g @actalk/inkos`. The package is published as `@actalk/inkos` on npm. For agent-to-agent use, InkOS is published as an OpenClaw skill and can be installed with `clawhub install inkos`; the README notes that when you install via npm or clone the repository, `skills/SKILL.md` is already included and does not need a separate ClawHub install. The recommended integration entry point is a single command: `inkos interact --json --message "继续当前书，但把节奏再收紧一点"`. The README advises OpenClaw and similar agents to prefer this over the atomic commands (`plan chapter`, `compose chapter`, `draft`, `audit`, `revise`, `write next`), which remain available as lower-level tools. Skills are plain `SKILL.md` files, loaded from the project `skills/` directory, `.agents/skills/`, `~/.agents/skills/` or `~/.openclaw/skills/`, or from paths listed in the `INKOS_SKILL_DIRS` environment variable. In chat you can force one for a turn with an `@skill-id` mention. The README states that skills supply instructions and static reference material only and do not add execution permissions; creation, writing, editing and image generation still pass through InkOS tools and the confirmation gate. Model configuration lives in Studio, covering multiple service configs, model routing and cover-service config, with support for OpenAI-compatible endpoints and aggregators such as OpenRouter and kkaiapi. English output is enabled with `--lang en`.
Where the design costs you something
Three limitations stand out from the material. First, the AGPL-3.0 licence is the binding constraint for commercial adoption. If you modify InkOS and let users interact with it over a network, the licence's network clause is the thing your legal review will focus on. This is not a project you can quietly embed in a closed SaaS product. Second, the README itself warns that 当前更新相对频繁, and the release cadence supports that: v1.7.1 on 21 July, v1.7.2 on 28 July, v1.8.0 on 17 August 2026. A release that reworks the execution core into a single harness will change internal behaviour that integrations depend on. If you build on the atomic commands rather than `inkos interact`, you are building on a surface the maintainers have explicitly repositioned as a lower-level tool. Third, the confirmation gate on heavy actions is a deliberate friction. It is the correct default for an agent that writes files, but it means InkOS is not a fire-and-forget batch generator; unattended runs need to be designed around the gate rather than against it. The README does not describe an unattended mode that bypasses confirmation.
Compared with wiring a generic coding agent to a folder of markdown
The obvious alternative is not another novel-writing product. It is a general-purpose agent such as Claude Code or OpenClaw pointed at a repository of outline and character files, with a prompt that says write the next chapter. That approach is cheaper to start and imposes no licence on your own code. The difference in approach is where state lives. In the generic setup, state is whatever the model can reconstruct from files and conversation history; consistency is a prompt-engineering hope. In InkOS, state is a first-class object with a validation step and an atomic commit, retrieval runs over a rebuildable index with source positions preserved, and the formats (long-form, short, script, storyboard, interactive film-game, Play, translation) each keep their own state model and creative rules while sharing the run snapshot, word-count observation, cancellation signal and failure recovery. You are trading flexibility and zero licence obligations for a structured state machine. The README's own framing supports this reading: it says the formats reuse the skill architecture but do not reuse long-form prompts that do not suit them, which is an admission that one prompt template across formats produces bad output.
Maintenance cost and the upgrade path
Because InkOS is distributed as a global npm package, upgrading is `npm i -g @actalk/inkos` again, and the project's own version history shows breaking surface changes inside minor releases. The 1.8.0 notes describe the Studio chat, TUI, `inkos interact` and worker paths converging on one tool loop, and describe the older pipelines as demoted rather than removed. If you have scripts that call `plan chapter`, `compose chapter`, `draft`, `audit`, `revise` or `write next`, the README still lists them as available, but they are no longer the recommended entry point. Budget for reading the release notes on each minor bump. On the licence side, AGPL-3.0 means the obligations attach to distribution and to network use of modified versions, and the repository ships a LICENSE file at the root. Whether your specific deployment triggers those obligations is a question for your own counsel; the material here does not resolve it, and I am not giving legal advice. The practical point is that this decision needs to be made before you build on InkOS, not after.
Editorial conclusion
InkOS fits writers and small studios who want a self-hosted, scriptable pipeline for long-form serial fiction, short pieces, scripts, storyboards or interactive film-games, and who are comfortable with a Node 22 CLI and an OpenAI-compatible model endpoint. It does not fit anyone who needs a permissive licence for a closed product, or who wants a polished consumer writing app with no configuration. Before adopting, verify three things against your own machine: that your Node version is 22 or higher, that your chosen model endpoint handles the streaming idle timeout the harness imposes, and that your deployment can satisfy AGPL-3.0 if you expose InkOS to users over a network.
Community notes