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 22 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 November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Narcooo/inkos11,217 ★ · +1,498
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| Narcooo/inkos | 9.7k | 11.2k |
1,498 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial 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. 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
The README describes this consolidation under InkOS 2.0, a development branch ahead of the latest v1.8.0 release. It states that InkOS 2.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
The README describes a unified local retrieval layer for InkOS 2.0. 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 README 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: sources do not bind themselves, 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 says planning, context assembly, writing and review are dispatched by the same harness action and are no longer exposed as parallel entry points. 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. 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. 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.
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. The README's 2.0 section describes the Studio chat, TUI, `inkos interact` and worker paths converging on one tool loop, and describe the older pipelines as demoted rather than removed. 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; this is not 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.
Frequently asked questions
What is inkos quirk?
The InkOS in this repository is a story-creation AI agent for long novels, short fiction, screenplays, interactive worlds and multilingual translation, distributed on npm as @actalk/inkos and licensed AGPL-3.0-only.
how to install inkos
Install the global package with npm i -g @actalk/inkos and have Node.js 22.16 or newer available, since the manifest requires node >=22.16.0. For agents that speak the OpenClaw skill format there is also clawhub install inkos, though the README notes that skills/SKILL.md already ships inside both the npm package and a clone. Note that the newest published release is v1.8.0 while the repository describes a 2.0 development branch.
what is inkos job
InkOS manages the working state of a story rather than generating text on its own: idea, setting, characters, memory, review, revision, covers, interactive state and cross-language delivery. Work can start from Studio, a TUI or the CLI, and formats include long serialized novels, standalone short fiction, screenplays, storyboards and branching interactive worlds.
inkos alternative
The README names options at the layers it depends on: kkaiapi or OpenRouter as model aggregators, custom OpenAI Chat Completions, OpenAI Responses or Anthropic Messages endpoints, an LM Studio local service, and OpenClaw as the agent host for the published skill.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/narcooo-inkos)Star history chart for your README
[](https://hysenlabs.com/projects/narcooo-inkos)Was this useful?