InkOS Story Creation Workspace
A stateful writing agent system for novels, scripts, interactive fiction, and multilingual book translation.
- Source repo
- Narcooo/inkos
- Stars
- ★ 11k
- Last updated
- 13d ago
- License
- AGPL-3.0
- Primary language
- TypeScript
- FA score
- 50/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A serial-fiction author wants every new chapter checked against character knowledge, resources, hooks, and prior story state before publication.
- Not a fit if
- Users on Node.js below 22 who rely on SQLite temporal memory
- Teams expecting a fully automatic revision loop with no human review
- Source review
- 50/100 · Major gaps
What does this agent do, and when should you use it?
InkOS is a local, project-based creation system for serial novels, short fiction, scripts, interactive experiences, and long-form translation. It offers a Studio web workspace, terminal TUI, CLI, and the structured external-agent entry point inkos interact --json. Its long-form workflow plans, composes, drafts, audits, optionally revises, and synchronizes story state for each chapter. Projects retain structured state, human-readable Markdown projections, and, on Node.js 22+, optional SQLite temporal memory. The same workspace can produce short-story packages, cover prompts and optional cover images, or persistent open worlds with characters, items, evidence, and relationships. Studio-managed services and CLI environment or command-line overrides support multiple providers and OpenAI-compatible endpoints.
Create a book with inkos book create and an optional --brief; the Architect generates story settings, rules, and long-term control files. inkos write next normally runs plan -> compose -> write, then audits, revises according to configuration, and synchronizes story state; plan chapter, compose chapter, draft, audit, and revise expose those operations separately. Authoritative data is stored in story/state/*.json, readable projections in story/*.md, and Node.js 22+ projects can query story/memory.db for relevant facts, hooks, and chapter summaries. inkos import chapters imports existing work and rebuilds its state, while inkos translate init / run / export handles EPUB, text-based PDF, TXT, and Markdown translation with TXT, Markdown, or EPUB export. Studio Chat, inkos agent, and inkos interact share an action surface for books, short fiction, covers, Play worlds, and persistent text edits, with confirmation before consequential actions.
- A serial-fiction author wants every new chapter checked against character knowledge, resources, hooks, and prior story state before publication.
- A scriptwriter or narrative designer needs branching plots, variables, character relationships, endings, scenes, and selectable interactive choices.
- An author with an existing manuscript wants to import chapters, reconstruct settings and chapter state, then continue the work in the same project.
- A publishing or content team needs chapter-aware translation of an EPUB, text-based PDF, TXT, or Markdown manuscript, including terminology and bilingual review output.
- A Claude Code or OpenClaw workflow needs to invoke a structured writing interaction through
inkos interact --json --message "...".
How do you install or deploy this agent?
Install globally with npm i -g @actalk/inkos. Create a project with inkos init my-novel && cd my-novel, then start Studio using inkos. In Studio, choose a provider, enter its API key, test the connection, and select a model. For CLI or deployment use, configure inkos config set-global --provider <openai|anthropic|custom> --base-url <API address> --api-key <your API key> --model <model name>. Node.js 22+ automatically enables SQLite temporal memory.
How do you use this agent?
Create a book and write its next chapter with inkos book create --title "吞天魔帝" --genre xuanhuan followed by inkos write next 吞天魔帝; inspect it with inkos status and export it with inkos export 吞天魔帝 --format epub. To inspect writing controls first, run inkos plan chapter 吞天魔帝 --context "本章重点写师徒矛盾" and then inkos compose chapter 吞天魔帝. Generate a standalone story package with inkos short run --direction "都市短篇 婚姻反转 女主证据反杀" --chapters 12 --chars 1000. External agents can use inkos interact --json --message "继续当前书，但把节奏再收紧一点".
What are this agent's strengths and limitations?
- Provides a defined chapter pipeline—planning, composition, drafting, audit, revision, and state settlement—while retaining composable CLI operations for scripts and external agents.
- Combines validated structured JSON state, readable Markdown projections, and Node.js 22+ SQLite temporal memory to manage long-running facts and hooks beyond a chat window.
- Brings long-form fiction, short-story packages, scripts, interactive worlds, cover generation, and book translation into shared Studio, TUI, and CLI surfaces.
- Supports Studio service configuration, CLI overrides, per-agent model routing, multiple providers, and OpenAI-compatible endpoints.
- Output quality, availability, and cost depend on the selected model provider and API key; the supplied material makes no quality or cost guarantee for a particular model.
- SQLite temporal memory is only documented as automatically enabled on Node.js 22+; behavior on older Node.js versions is not evidenced.
- The default long-form flow performs at most one automatic revision; unresolved issues remain for human review or later commands.
- Translation support is explicitly listed for EPUB, text-based PDFs, TXT, and Markdown, with no evidence for scanned-PDF OCR.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| InkOS Story Creation Workspace This agent | 50 · Major gaps | CLIFree + model costs | ★ 11k | 13d ago | TypeScript | Claude Code · OpenAI API · Claude API |
| OH Story — All-in-One Skill Pack for Chinese Web Fiction | 75 · Good | Agent plugin / skillFree + model costs | ★ 8.3k | today | Python | Codex · Claude Code |
| AIWriteX Content Studio | 43 · Major gaps | Desktop appFree + model costs | ★ 2.2k | 10d ago | Python | — |
| Story Skills | 80 · Good | Agent plugin / skillFree | ★ 390 | 1d ago | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README mentions heavy actions require confirmation (e.g., generation, review, revision), and mentions backup/restore, rollback, concurrency control (BOOK_BUSY). However, no permission model details, API keys stored in .inkos/secrets.json and .env without encryption or least privilege. Dependency security has pnpm overrides pinning versions, but no vulnerability scanning evidence. External effects include network requests (LLM API, image generation), but data flow not described. Deductions: missing permission details, unencrypted key storage, insufficient dependency security evidence.
Evidence shows: README describes consistent architecture (Studio/CLI/TUI share execution surface), CI runs tests on multiple Node versions, but no test results or coverage provided. Dependency availability: npm publish workflow exists, but no availability guarantees. Failure messages: error codes like BOOK_BUSY mentioned, but no detailed failure handling docs. Deductions: insufficient test evidence, incomplete failure message documentation.
Evidence shows: README describes multiple scenarios (long-form, short, scripts, interactive film, translation), provides 10 English genres and 5 Chinese genres, capability boundaries clear (e.g., skills do not auto-execute scripts). Trigger precision: skills triggered by @skill-id or intent, not keyword matching. Environment fit: supports multiple OS and Node versions, but no detailed system requirements. Deductions: insufficient environment fit details.
Evidence shows: README provides installation, configuration, usage examples, clear information architecture (sections). Naming stability: CLI commands and config keys consistent. Known limitations: some mentioned (e.g., MiniMax M2.x thinking cannot be disabled), but not comprehensive. License AGPL-3.0, version 1.7.2, CI and release workflow, but no CHANGELOG file. Maintenance responsibility: GitHub repo and release workflow, but maintainers not explicit. Deductions: incomplete known limitations, no CHANGELOG, unclear maintenance responsibility.
Evidence shows: README describes output formats (EPUB, Markdown, TXT), provides usage examples, output usability good. Marginal value: multiple features (narrative forecast, translation workbench), but no comparison with alternatives. Cost-benefit: multi-model routing to balance cost, but no concrete cost data. Deductions: insufficient marginal value comparison, missing cost data.
Evidence shows: README feature descriptions lack implementation details or test evidence, claims are assertions. Cross-source corroboration: CI and release workflow, but no independent verification. Fact-inference separation: README distinguishes features and recommendations (e.g., kkaiapi), but not explicitly labeled. Deductions: claims lack traceability, insufficient cross-source verification, unclear fact-inference separation.
- API keys stored in .inkos/secrets.json and .env without encryption or least privilege, review key management.
- Dependency security relies only on pnpm overrides, no vulnerability scanning evidence, check dependencies.
- README feature claims lack traceability, verify via code and tests.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
- fix(core): normalize persisted paths across platforms (52075bb9) - fix(build): keep overrides compatible with pnpm 9 (de4e9fa5) - chore(release): prepare v1.8.0 documentation (b673c500) - fix(ci): align test matrix with node requirements (8922e3ab) - feat(tui): unify agent surfaces and confirmations (7c98a1eb) - refactor(core): unify production harness and context flow (e7c04465) - refactor: center creation workflows on pi harness (d1d6d8ec) - refactor(core): run production workers through pi harness (35bb2efd) - feat(skills): bind production modes to dedicated expertise (6651fa7e) …View on GitHub ↗ -
Release notes excerpt
- chore(release): prepare v1.7.2 (c7851b94) - refactor(skills): replace legacy capability system (6e4ce005) - docs: document AgentSkills compatibility (d674c214) - feat(studio): import external skill folders (41a1138f) - feat(core): add intent-driven AgentSkills runtime (4b81fbba) - chore: remove internal planning documents (1a2fd09b) - docs: lead v1.7 with model configuration (f19f428a) Full Changelog: https://github.com/Narcooo/inkos/compare/v1.7.1...v1.7.2View on GitHub ↗ -
Release notes excerpt
- docs: consolidate v1.7 highlights (a713a2e8) - chore(release): prepare v1.7.1 (6a16a619) - docs: keep product intro above sponsorship (9f194592) - docs: retain Kimi open source partner banners (ac776428) - docs: add Kimi sponsorship banners (6c6574ff) - test(core): use shared timeout for root import (d3f6ae7e) - fix(core): restore direct terminal tool cards (eb6c8f88) - docs: document narrative forecast workflow (6ac708a9) - feat(studio): compare narrative forecasts in book chat (b98252bb) - docs: design Studio narrative forecast comparison (b38f6039) …View on GitHub ↗
FAQ
Does InkOS send my manuscript to a fixed cloud service?
.inkos/secrets.json, while the CLI can use environment variables. Generation and web research call the model or network services you configure, so data exposure depends on the selected provider.Can it use a self-hosted or custom model endpoint?
--provider custom and OpenAI-compatible interfaces. inkos doctor reports effective configuration and attempts connectivity checks.Do forecast branches change the canonical story?
forecast create/show/select saves a candidate plan only; the documented behavior is that it does not modify prose, outlines, or canonical story state.Can I evaluate project inputs before calling a writing model?
inkos compose chapter [id] compiles local documents and state, and is documented as not requiring an online LLM.What happens if two writing operations conflict?
BOOK_BUSY, and also documents book backup/restore, latest-chapter deletion, and state rollback.