{"id":47300606,"url":"https://github.com/Narcooo/inkos","last_synced_at":"2026-03-26T03:01:13.862Z","repository":{"id":343874246,"uuid":"1179413000","full_name":"Narcooo/inkos","owner":"Narcooo","description":"Autonomous novel writing CLI agent — AI agents write, audit, and revise novels with human review gates","archived":false,"fork":false,"pushed_at":"2026-03-19T15:02:42.000Z","size":1364,"stargazers_count":1788,"open_issues_count":40,"forks_count":372,"subscribers_count":14,"default_branch":"master","last_synced_at":"2026-03-19T21:27:08.696Z","etag":null,"topics":["agent","ai-writing","aigc-detection","automated-storytelling","chinese-novel","cli-tool","creative-writing-ai","novel-generation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Narcooo.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T02:12:54.000Z","updated_at":"2026-03-19T21:05:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Narcooo/inkos","commit_stats":null,"previous_names":["narcooo/inkos"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Narcooo/inkos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Narcooo%2Finkos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Narcooo%2Finkos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Narcooo%2Finkos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Narcooo%2Finkos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Narcooo","download_url":"https://codeload.github.com/Narcooo/inkos/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Narcooo%2Finkos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30948159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-26T02:38:33.265Z","status":"ssl_error","status_checked_at":"2026-03-26T02:36:10.435Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai-writing","aigc-detection","automated-storytelling","chinese-novel","cli-tool","creative-writing-ai","novel-generation"],"created_at":"2026-03-17T01:38:19.999Z","updated_at":"2026-03-26T03:01:12.711Z","avatar_url":"https://github.com/Narcooo.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.svg\" width=\"120\" height=\"120\" alt=\"InkOS Logo\"\u003e\n  \u003cimg src=\"assets/inkos-text.svg\" width=\"240\" height=\"65\" alt=\"InkOS\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eAutonomous Novel Writing Cli AI Agent\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@actalk/inkos\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@actalk/inkos.svg?color=cb3837\u0026logo=npm\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg\" alt=\"Node.js\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-5.x-3178C6.svg?logo=typescript\u0026logoColor=white\" alt=\"TypeScript\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003e中文\u003c/a\u003e | English\n\u003c/p\u003e\n\n---\n\nOpen-source CLI agent that autonomously writes, audits, and revises novels — with human review gates that keep you in control. Supports LitRPG, Progression Fantasy, Isekai, Romantasy, Sci-Fi, and more. Continuation, spinoff, fanfic, and style imitation workflows built in.\n\n**Native English novel writing now supported！** — 10 built-in English genre profiles with dedicated pacing rules, fatigue word lists, and audit dimensions. Set `--lang en` and go.\n\n## Quick Start\n\n### Install\n\n```bash\nnpm i -g @actalk/inkos\n```\n\n### Use via OpenClaw 🦞\n\nInkOS is published as an [OpenClaw](https://clawhub.ai) Skill, callable by any compatible agent (Claude Code, OpenClaw, etc.):\n\n```bash\nclawhub install inkos          # Install from ClawHub\n```\n\nIf you installed via npm or cloned the repo, `skills/SKILL.md` is already included — 🦞 can read it directly without a separate ClawHub install.\n\nOnce installed, Claw can invoke all InkOS atomic commands (`draft`/`audit`/`revise`/`write next`) via `exec`, with `--json` output for structured decision-making. You can also browse it on [ClawHub](https://clawhub.ai) by searching `inkos`.\n\n### Configure\n\n**Option 1: Global config (recommended, one-time setup)**\n\n```bash\ninkos config set-global \\\n  --lang en \\\n  --provider \u003copenai|anthropic|custom\u003e \\\n  --base-url \u003cAPI endpoint\u003e \\\n  --api-key \u003cyour API key\u003e \\\n  --model \u003cmodel name\u003e\n\n# provider: openai / anthropic / custom (use custom for OpenAI-compatible proxies)\n# base-url: your API provider URL\n# api-key: your API key\n# model: your model name\n```\n\n`--lang en` sets English as the default writing language for all projects. Saved to `~/.inkos/.env`. New projects just work without extra config.\n\n**Option 2: Per-project `.env`**\n\n```bash\ninkos init my-novel     # Initialize project\n# Edit my-novel/.env\n```\n\n```bash\n# Required\nINKOS_LLM_PROVIDER=                               # openai / anthropic / custom (use custom for any OpenAI-compatible API)\nINKOS_LLM_BASE_URL=                               # API endpoint\nINKOS_LLM_API_KEY=                                 # API Key\nINKOS_LLM_MODEL=                                   # Model name\n\n# Language (defaults to global setting or genre default)\n# INKOS_DEFAULT_LANGUAGE=en                        # en or zh\n\n# Optional\n# INKOS_LLM_TEMPERATURE=0.7                       # Temperature\n# INKOS_LLM_MAX_TOKENS=8192                        # Max output tokens\n# INKOS_LLM_THINKING_BUDGET=0                      # Anthropic extended thinking budget\n```\n\nProject `.env` overrides global config. Skip it if no override needed.\n\n**Option 3: Multi-model routing (optional)**\n\nAssign different models to different agents — balance quality and cost:\n\n```bash\n# Assign different models/providers to different agents\ninkos config set-model writer \u003cmodel\u003e --provider \u003cprovider\u003e --base-url \u003curl\u003e --api-key-env \u003cENV_VAR\u003e\ninkos config set-model auditor \u003cmodel\u003e --provider \u003cprovider\u003e\ninkos config show-models        # View current routing\n```\n\nAgents without explicit overrides fall back to the global model.\n\n### Write Your First Book\n\nEnglish is the default for English genre profiles. Pick a genre and go:\n\n```bash\ninkos book create --title \"The Last Delver\" --genre litrpg     # LitRPG novel (English by default)\ninkos write next my-book          # Write next chapter (full pipeline: draft → audit → revise)\ninkos status                      # Check status\ninkos review list my-book         # Review drafts\ninkos review approve-all my-book  # Batch approve\ninkos export my-book --format epub  # Export EPUB (read on phone/Kindle)\n```\n\nLanguage is set per-genre by default. Override explicitly with `--lang en` or `--lang zh`. Use `inkos genre list` to see all available genres and their default languages.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshot-terminal.png\" width=\"700\" alt=\"Terminal screenshot\"\u003e\n\u003c/p\u003e\n\n---\n\n## English Genre Profiles\n\nInkOS ships with 10 English-native genre profiles. Each includes genre-specific rules, pacing, fatigue word detection, and audit dimensions:\n\n| Genre | Key Mechanics |\n|-------|--------------|\n| **LitRPG** | Numerical system, power scaling, stat progression |\n| **Progression Fantasy** | Power scaling, no numerical system required |\n| **Isekai** | Era research, world contrast, cultural fish-out-of-water |\n| **Cultivation** | Power scaling, realm progression |\n| **System Apocalypse** | Numerical system, survival mechanics |\n| **Dungeon Core** | Numerical system, power scaling, territory management |\n| **Romantasy** | Emotional arcs, dual POV pacing |\n| **Sci-Fi** | Era research, tech consistency |\n| **Tower Climber** | Numerical system, floor progression |\n| **Cozy Fantasy** | Low-stakes pacing, comfort-first tone |\n\nAlso supports 5 Chinese web novel genres (xuanhuan, xianxia, urban, horror, other) for bilingual creators.\n\nEvery genre includes a **fatigue word list** (e.g., \"delve\", \"tapestry\", \"testament\", \"intricate\", \"pivotal\" for LitRPG) — the auditor flags these automatically so your prose doesn't read like every other AI-generated novel.\n\n---\n\n## Key Features\n\n### 33-Dimension Audit + De-AI-ification\n\nThe Continuity Auditor checks every draft across 33 dimensions: character memory, resource continuity, hook payoff, outline adherence, narrative pacing, emotional arcs, and more. Built-in AI-tell detection automatically catches \"LLM voice\" — overused words, monotonous sentence patterns, excessive summarization. Failed audits trigger an automatic revision loop.\n\nDe-AI-ification rules are baked into the Writer agent's prompts: fatigue word lists, banned patterns, style fingerprint injection — reducing AI traces at the source. `revise --mode anti-detect` runs dedicated anti-detection rewriting on existing chapters.\n\n### Style Cloning\n\n`inkos style analyze` examines reference text and extracts a statistical fingerprint (sentence length distribution, word frequency patterns, rhythm profiles) plus an LLM-readable style guide. `inkos style import` injects this fingerprint into a book — all future chapters adopt the style, and the Reviser audits against it.\n\n### Creative Brief\n\n`inkos book create --brief my-ideas.md` — pass your brainstorming notes, worldbuilding doc, or character sheets. The Architect agent builds from your brief (generating story_bible.md and book_rules.md) instead of inventing from scratch.\n\n### Continuation Writing\n\n`inkos import chapters` imports existing novel text, auto reverse-engineers all 7 truth files (world state, character matrix, resource ledger, plot hooks, etc.), supports `Chapter N` and custom split patterns, and resumable import. After import, `inkos write next` seamlessly continues the story.\n\n### Fan Fiction\n\n`inkos fanfic init --from source.txt --mode canon` creates a fanfic book from source material. Four modes: canon (faithful continuation), au (alternate universe), ooc (out of character), cp (ship-focused). Includes a canon importer, fanfic-specific audit dimensions, and information boundary controls to keep lore consistent.\n\n### Multi-Model Routing\n\nDifferent agents can use different models and providers. Writer on Claude (stronger creative), Auditor on GPT-4o (cheaper and fast), Radar on a local model (zero cost). `inkos config set-model` configures per-agent; unconfigured agents fall back to the global model.\n\n### Daemon Mode + Notifications\n\n`inkos up` starts an autonomous background loop that writes chapters on a schedule. The pipeline runs fully unattended for non-critical issues, pausing for human review when needed. Notifications via Telegram and Webhook (HMAC-SHA256 signing + event filtering). Logs to `inkos.log` (JSON Lines), `-q` for quiet mode.\n\n### Local Model Compatibility\n\nSupports any OpenAI-compatible endpoint (`--provider custom`). Stream auto-fallback — when SSE isn't supported, InkOS retries with sync mode automatically. Fallback parser handles non-standard output from smaller models, and partial content recovery kicks in on stream interruption.\n\n### Reliability\n\nEvery chapter creates an automatic state snapshot — `inkos write rewrite` rolls back any chapter to its pre-write state. The Writer outputs a pre-write checklist (context scope, resources, pending hooks, risks) and a post-write settlement table; the Auditor cross-validates both. File locking prevents concurrent writes. Post-write validator enforces 11 hard rules with auto spot-fix.\n\n---\n\n## How It Works\n\nEach chapter is produced by five agents in sequence:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshot-pipeline.png\" width=\"800\" alt=\"Pipeline diagram\"\u003e\n\u003c/p\u003e\n\n| Agent | Responsibility |\n|-------|---------------|\n| **Radar** | Scans platform trends and reader preferences to inform story direction. Pluggable via `RadarSource` interface — skip it or bring your own data source |\n| **Architect** | Plans chapter structure: outline, scene beats, pacing targets |\n| **Writer** | Produces prose from the plan + current world state (two-phase: creative writing → state settlement) |\n| **Continuity Auditor** | Validates the draft against 7 canonical truth files, 33-dimension check |\n| **Reviser** | Fixes issues found by the auditor — auto-fixes critical problems, flags others for human review |\n\nIf the audit fails, the pipeline automatically enters a revise → re-audit loop until all critical issues are resolved.\n\n### Canonical Truth Files\n\nEvery book maintains 7 truth files as the single source of truth:\n\n| File | Purpose |\n|------|---------|\n| `current_state.md` | World state: character locations, relationships, knowledge, emotional arcs |\n| `particle_ledger.md` | Resource accounting: items, money, supplies with quantities and decay tracking |\n| `pending_hooks.md` | Open plot threads: foreshadowing planted, promises to readers, unresolved conflicts |\n| `chapter_summaries.md` | Per-chapter summaries: characters, key events, state changes, hook dynamics |\n| `subplot_board.md` | Subplot progress board: A/B/C line status tracking |\n| `emotional_arcs.md` | Emotional arcs: per-character emotion tracking and growth |\n| `character_matrix.md` | Character interaction matrix: encounter records, information boundaries |\n\nThe Continuity Auditor checks every draft against these files. If a character \"remembers\" something they never witnessed, or pulls a weapon they lost two chapters ago, the auditor catches it.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/screenshot-state.png\" width=\"800\" alt=\"Truth files snapshot\"\u003e\n\u003c/p\u003e\n\n### Writing Rule System\n\nThe Writer agent has ~25 universal writing rules (character craft, narrative technique, logical consistency, language constraints, de-AI-ification), applicable to all genres.\n\nOn top of that, each genre has dedicated rules (prohibitions, language constraints, pacing, audit dimensions), and each book has its own `book_rules.md` (protagonist personality, numerical caps, custom prohibitions) and `story_bible.md` (worldbuilding), auto-generated by the Architect agent.\n\n## Usage Modes\n\nInkOS provides three interaction modes, all sharing the same atomic operations:\n\n### 1. Full Pipeline (One Command)\n\n```bash\ninkos write next my-book              # Draft → audit → auto-revise, all in one\ninkos write next my-book --count 5    # Write 5 chapters in sequence\n```\n\n### 2. Atomic Commands (Composable, External Agent Friendly)\n\n```bash\ninkos draft my-book --context \"Focus on the dungeon boss encounter and party dynamics\" --json\ninkos audit my-book 31 --json\ninkos revise my-book 31 --json\n```\n\nEach command performs a single operation independently. `--json` outputs structured data. Can be called by external AI agents via `exec`, or used in scripts.\n\n### 3. Natural Language Agent Mode\n\n```bash\ninkos agent \"Write a LitRPG novel where the MC is a healer class in a dungeon world\"\ninkos agent \"Write the next chapter, focus on the boss fight and loot distribution\"\ninkos agent \"Create a progression fantasy about a mage who can only use one spell\"\n```\n\n13 built-in tools (write_draft, audit_chapter, revise_chapter, scan_market, create_book, get_book_status, read_truth_files, list_books, write_full_pipeline, web_fetch, import_style, import_canon, import_chapters), with the LLM deciding call order via tool-use.\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `inkos init [name]` | Initialize project (omit name to init current directory) |\n| `inkos book create` | Create a new book (`--genre`, `--chapter-words`, `--target-chapters`, `--brief \u003cfile\u003e`, `--lang en/zh`) |\n| `inkos book update [id]` | Update book settings (`--chapter-words`, `--target-chapters`, `--status`, `--lang`) |\n| `inkos book list` | List all books |\n| `inkos book delete \u003cid\u003e` | Delete a book and all its data (`--force` to skip confirmation) |\n| `inkos genre list/show/copy/create` | View, copy, or create genres |\n| `inkos write next [id]` | Full pipeline: write next chapter (`--words` to override, `--count` for batch, `-q` quiet mode) |\n| `inkos write rewrite [id] \u003cn\u003e` | Rewrite chapter N (restores state snapshot, `--force` to skip confirmation) |\n| `inkos draft [id]` | Write draft only (`--words` to override word count, `-q` quiet mode) |\n| `inkos audit [id] [n]` | Audit a specific chapter |\n| `inkos revise [id] [n]` | Revise a specific chapter |\n| `inkos agent \u003cinstruction\u003e` | Natural language agent mode |\n| `inkos review list [id]` | Review drafts |\n| `inkos review approve-all [id]` | Batch approve |\n| `inkos status [id]` | Project status |\n| `inkos export [id]` | Export book (`--format txt/md/epub`, `--output \u003cpath\u003e`, `--approved-only`) |\n| `inkos fanfic init` | Create a fanfic book from source material (`--from`, `--mode canon/au/ooc/cp`) |\n| `inkos config set-global` | Set global LLM config (~/.inkos/.env) |\n| `inkos config set-model \u003cagent\u003e \u003cmodel\u003e` | Per-agent model override (`--base-url`, `--provider`, `--api-key-env`) |\n| `inkos config show-models` | Show current model routing |\n| `inkos doctor` | Diagnose setup issues (API connectivity test + provider compatibility hints) |\n| `inkos detect [id] [n]` | AIGC detection (`--all` for all chapters, `--stats` for statistics) |\n| `inkos style analyze \u003cfile\u003e` | Analyze reference text to extract style fingerprint |\n| `inkos style import \u003cfile\u003e [id]` | Import style fingerprint into a book |\n| `inkos import chapters [id] --from \u003cpath\u003e` | Import existing chapters for continuation (`--split`, `--resume-from`) |\n| `inkos analytics [id]` / `inkos stats [id]` | Book analytics (audit pass rate, top issues, chapter ranking, token usage) |\n| `inkos up / down` | Start/stop daemon (`-q` quiet mode, auto-writes `inkos.log`) |\n\n`[id]` is auto-detected when the project has only one book. All commands support `--json` for structured output. `book create` supports `--brief \u003cfile\u003e` to pass a creative brief — the Architect builds from your ideas instead of generating from scratch.\n\n## Roadmap\n\n- [ ] `packages/studio` Web UI for review and editing (Vite + React + Hono)\n- [ ] Partial chapter intervention (rewrite half a chapter + cascade truth file updates)\n- [ ] Novel-to-comic pipeline (truth files → storyboard → manga pages)\n- [ ] Custom agent plugin system\n\n## Contributing\n\nContributions welcome. Open an issue or PR.\n\n```bash\npnpm install\npnpm dev          # Watch mode for all packages\npnpm test         # Run tests\npnpm typecheck    # Type-check without emitting\n```\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNarcooo%2Finkos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNarcooo%2Finkos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNarcooo%2Finkos/lists"}