InkOS: Open-Source AI Agent for Novel Writing

1. Project Overview

InkOS is an open-source (AGPL-3.0) AI agent system for creative writing. It helps authors plan, draft, audit and revise long-form serial novels, short stories, scripts, fan fiction and interactive worlds, while keeping characters, plot threads and world state consistent across hundreds of chapters. Everything is managed from one workspace through three interfaces: a web Studio, a terminal TUI, and a CLI.

2. Background & Positioning

Why it was created

Long-form generation with a single prompt tends to drift: characters change, foreshadowing is forgotten, and earlier facts are contradicted. InkOS addresses this by splitting writing into specialized agents and by storing story state in a structured, rebuildable memory rather than relying on the model's context window alone.

How it differs from similar projects

Pipeline, not a single prompt: dedicated Planner, Composer, Writer, Settler, Auditor and Reviser agents.
Durable memory: canonical JSON state, human-readable Markdown projections and a rebuildable SQLite FTS5/BM25 search index.
Atomic commits: chapters, state, hooks and snapshots are committed together, so a failed run does not leave a half-updated book.
Broader than novels: short stories, screenplays, storyboards, interactive play, fan fiction, style imitation and long-text translation share one workspace.
Agent-native: ships 19 built-in skills in the standard SKILL.md format and can be driven from other agents such as Claude Code and OpenClaw.

3. Feature Categories

✍️ Long-Form Writing

About 6 cooperating agents (Planner, Composer, Writer, Settler, Auditor, Reviser)
Examples: inkos write next, batch writing with --count, inkos write rewrite, inkos review, inkos revise
Purpose: produce serial chapters with consistent plot and characters.

🧠 Memory & Control

Examples: canonical JSON state, Markdown projections, SQLite FTS5/BM25 index, author_intent.md and current_focus.md, per-chapter context traces
Purpose: keep long stories coherent and let the author steer direction.

📖 Short Stories & Covers

Examples: inkos short run, inkos short revise, outlines, review records, sales copy, cover prompts and optional cover images
Purpose: generate complete short pieces with their supporting material.

🎮 Interactive Play

Examples: open-world mode, branching stories, clickable choices, free-form actions, HUD, auto-illustration
Purpose: turn a story world into a playable experience.

🎨 Style, Fan Fiction & Import

Examples: inkos style analyze, inkos fanfic init (canon, AU, OOC, CP modes), inkos import chapters, inkos import canon
Purpose: imitate a style, extend existing works, or continue from existing chapters.

🔌 Models, Skills & Automation

19 built-in skills; multi-model routing per agent
Examples: OpenAI Chat/Responses, Anthropic Messages, Gemini, DeepSeek, OpenRouter, Ollama and LM Studio; daemon mode (inkos up); notifications via Telegram, Feishu, WeCom and signed webhooks
Purpose: fit InkOS into your own model setup and workflow.

4. Key Highlights

Multi-agent writing pipeline: each stage has a single responsibility, which makes output easier to review and repair.
Rebuildable memory: the search index can be regenerated from the canonical state, and the Markdown projections stay readable and editable.
Evidence-based auditing: the Auditor records observations with evidence; revisions happen only when you ask for them.
Three interfaces, one workspace: switch between Studio, TUI and CLI without changing projects.
Flexible model support: mix providers and route different agents to different models, including local ones.
Extensible skills: project, user and environment-specified skill directories are supported, and @skill-id forces a skill for a turn.

5. Use Cases by Role

General developers: script book creation and exports with the CLI (--json output is available on many commands) or embed InkOS in agent workflows through its skills.
Authors and creators: draft serial fiction, short stories and fan fiction with consistent world state.
Game and interactive-media designers: prototype branching narratives and open-world scenarios.
DevOps/SRE: run the daemon (inkos up / inkos down) and receive notifications through webhooks signed with HMAC-SHA256.
Researchers: study multi-agent long-context generation and structured memory designs.

6. Getting Started

Find what you need

inkos --help
inkos doctor

Browse the docs/ folder and the skills/ directory in the repository.

Install and integrate

Requires Node.js 22.16 or later.

npm i -g @actalk/inkos
inkos init my-novel
cd my-novel
inkos

Configure a model in the Studio settings, or via the CLI:

inkos config set-global --provider <provider> --base-url <url> --api-key <key> --model <model>

Typical CLI flow:

inkos book create --title "My Novel" --genre xuanhuan
inkos write next "My Novel" --count 5
inkos export "My Novel" --format epub

To use it as a skill in OpenClaw:

clawhub install inkos

Contribute

pnpm install
pnpm dev
pnpm test
pnpm typecheck

Read CONTRIBUTING.md, then open an issue or pull request.

7. Project Structure

inkos/
├── packages/        # Workspace packages (core, CLI, Studio)
├── skills/          # Built-in skills (SKILL.md format)
├── docs/            # Documentation
├── spec/            # Specifications
├── scripts/         # Maintenance scripts
├── test-project/    # Sample project for testing
├── assets/          # Images and static assets
├── README.md        # Chinese README
├── README.en.md     # English README
├── CONTRIBUTING.md
├── CHANGELOG.md
└── pnpm-workspace.yaml

8. Related Ecosystem

pi agent runtime (@mariozechner/pi-ai, @mariozechner/pi-agent-core): the harness InkOS 2.0 is built on.
Studio stack: Vite, React and Hono.
Storage and validation: SQLite FTS5/BM25 and Zod schemas.
Model providers: OpenAI-compatible, Anthropic, Google Gemini, DeepSeek, OpenRouter, Ollama, LM Studio and more.
Agent platforms: Claude Code and OpenClaw/ClawHub through the skill.

9. License

InkOS is released under AGPL-3.0.

✅ Use, modify and distribute the software, including for commercial purposes.
✅ Run it privately for your own writing projects.
❌ Distribute modified versions without making the corresponding source available under the same license.
ℹ️ If you offer a modified version as a network service, AGPL-3.0 requires you to provide its source to users.
ℹ️ Review LICENSE and consult legal counsel for commercial integrations.

10. FAQ

Q: Which Node.js version do I need?
A: Node.js 22.16 or later. Install the CLI with npm i -g @actalk/inkos.

Q: Does InkOS work in English?
A: Chinese is the primary language, and English is supported with the --lang en flag. See README.en.md.

Q: How do I check that my model setup works?
A: Run inkos doctor. API keys configured in Studio are stored in .inkos/secrets.json.

Q: Can I migrate a project from InkOS 1.x?
A: Yes. Preview with inkos work migrate --json, then apply with inkos work migrate --apply.

Q: Can I use local models?
A: Yes. Ollama and LM Studio are supported, along with custom endpoints.

11. Quick Links

Repository: https://github.com/Narcooo/inkos
Documentation: https://github.com/Narcooo/inkos/tree/master/docs
English README: https://github.com/Narcooo/inkos/blob/master/README.en.md
Contributing guide: https://github.com/Narcooo/inkos/blob/master/CONTRIBUTING.md
npm package: https://www.npmjs.com/package/@actalk/inkos
Issues and discussions: https://github.com/Narcooo/inkos/issues

12. Summary

InkOS turns AI-assisted writing into a structured, auditable workflow with persistent story memory, so long projects stay consistent. It suits authors, game designers and developers who want controllable long-form generation across novels, short stories and interactive worlds, with the freedom to choose their own models and interfaces.