{
  "markdown": "# Viv: An Engine for Emergent Narrative\n\n[![last release][last-release-badge]][last-release-link] [![last commit][last-commit-badge]][last-commit-link] [![CI][ci-badge]][ci-link]\n\n[![docs][docs-badge]][docs-link] [![license][license-badge]][license-link] [![mailing list][mailing-list-badge]][mailing-list-link]\n\n[![pypi][pypi-badge]][pypi-link] [![npm][npm-badge]][npm-link] [![claude code][claude-badge]][claude-link]\n\n[![jetbrains][jetbrains-badge]][jetbrains-link] [![vs code][vscode-badge]][vscode-link] [![sublime text][sublime-badge]][sublime-link]\n\n## Welcome\n\nWelcome to the **monorepo** for Viv, an engine for emergent narrative in games and simulations. If you're new to Viv, check out the [**homepage**](https://viv.sifty.studio) for a proper introduction.\n\nIn *emergent narrative*, stories arise from the bottom up, as characters take action in a simulated storyworld, rather than being authored from the top down. Viv offers (aspiring) narrative designers a custom programming language affording rich specifications of character actions, as well as constructs to drive *story sifting*—the task of identifying emergent storylines in a given simulation instance, such as a videogame playthrough.\n\nViv is a **source-available project**, which means that:\n\n* Anyone can view its full codebase (which lives here in this monorepo).\n* Non-commercial use is freely permitted.\n* Commercial use requires a [license](#license).\n\nBelow, you'll find a high-level overview of the project, mostly in the form of links to the published packages and to various docs. There is also a [monorepo layout](#monorepo-layout) section providing a high-level map of the codebase, for folks who want to explore around in there.\n\n\n## Table of Contents\n\n- [Status](#status)\n- [Requirements](#requirements)\n- [Quickstart](#quickstart)\n- [Packages](#packages)\n- [Docs](#docs)\n- [Example Projects](#example-projects)\n- [Monorepo Layout](#monorepo-layout)\n- [Contributing](#contributing)\n- [License](#license)\n\n\n## Status\n\nViv is in **open beta**. After several months of active development and a few years of more sporadic work, the project is ready for experimentation and real-world use. Here's where things stand:\n\n* Each system [component](#packages) is versioned independently, always under [semantic versioning](https://semver.org/). The respective latest versions of the components will always be compatible with one another.\n* Currently all components are in the `0.x` series and approaching `1.0`, but for the time being I'm leaving the door open for breaking changes. These are expected to be infrequent, small in scope (e.g., a syntax tweak in the DSL), and clearly documented. Most ongoing changes will be additive and driven by feature requests.\n* The system is backed by 1000+ tests across the component test suites, all of which run via CI on every push.\n* Viv currently ships a single [runtime](runtimes/js/README.md), targeting JavaScript (and TypeScript) codebases. A C# runtime tailored for Unity is planned. If you can't run JavaScript in your project, you likely can't use Viv today.\n\n\n## Requirements\n\n* Python 3.11+ (for the Viv compiler)\n* Node.js 18+ (for the Viv JavaScript runtime)\n\n\n## Quickstart\n\n*Note that currently there is a single Viv runtime, aimed at JavaScript (and TypeScript) codebases. If you can’t run JavaScript in your project, you likely won’t be able to use Viv right now. A C# runtime tailored for Unity projects is planned.*\n\n### I use LLMs\n\n* Install [Claude Code](https://code.claude.com/).\n\n* Install the [Viv Claude Code plugin](https://github.com/siftystudio/viv/tree/main/plugins/claude):\n\n  ```sh\n  claude plugin marketplace add siftystudio/claude-plugins\n  claude plugin install viv@siftystudio\n  ```\n\n* In Claude Code, run the `/viv:setup` skill.\n\n  * Claude takes it from there, installing Viv components, setting up your project, answering your questions, and proposing next steps.\n\n### I do not use LLMs\n\n* Install the compiler, and verify it works:\n\n  ```sh\n  pip install viv-compiler\n\n  vivc --test\n  ```\n\n* Install the runtime:\n\n  ```sh\n  npm install @siftystudio/viv-runtime\n  ```\n\n* Clone and run an example project:\n\n  ```sh\n  npx degit siftystudio/viv/examples/hello-viv-ts my-viv-project  # or hello-viv-js\n\n  cd my-viv-project\n  npm install && npm start\n  ```\n\n* In your cloned project, try making a few edits to the simple Viv code in `src/content/source.viv`, then recompile and re-run:\n\n  ```sh\n  vivc -i src/content/source.viv -o src/content/compiled_content_bundle.json\n\n  npm start\n  ```\n\n* Check out the full [Quickstart guide](https://viv.sifty.studio/quickstart/) for information on editor plugins and LLM-augmented authoring, and consult the [language reference](https://viv.sifty.studio/reference/language/) for details on the Viv syntax.\n\n\n## Packages\n\n| Package | Description                                                                                    | Install |\n|---------|------------------------------------------------------------------------------------------------|---------|\n| [Compiler](compiler/README.md) | Compiles `.viv` source files into JSON content bundles.                                        | [PyPI][pypi-link] |\n| [JavaScript Runtime](runtimes/js/README.md) | Action selection, planning, and story sifting from a content bundle.                           | [npm][npm-link] |\n| [JetBrains Plugin](plugins/jetbrains/README.md) | Full-featured IDE support for `.viv` files. This is the recommended tool for writing Viv code. | [JetBrains Marketplace][jetbrains-link] |\n| [VS Code Extension](plugins/vscode/README.md) | Editor support for `.viv` files.                                                               | [VS Marketplace][vscode-link] |\n| [Sublime Text Package](plugins/sublime/README.md) | Lightweight editor support for `.viv` files.                                                   | [GitHub][sublime-link] |\n| [Claude Code Plugin](plugins/claude/README.md) | LLM-powered Viv expertise in your terminal.                                                    | [GitHub][claude-link] |\n\n\n## Docs\n\n| Resource                                                                                                   | Description                                                                                    |\n|------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|\n| [Quickstart](https://viv.sifty.studio/quickstart/)                                                         | Installation, editor plugins, and LLM-augmented authoring for those that want it.              |\n| [Introduction](https://viv.sifty.studio/introduction/)                                                     | A complete introduction to Viv: features, design philosophy, and an extensive tour.            |\n| [Language Reference](https://viv.sifty.studio/reference/language/)                                         | A complete specification of the Viv language.                                                  |\n| [Compiler Reference](https://viv.sifty.studio/reference/compiler/)                                         | Reference for the compiler: CLI, API, troubleshooting.                                         |\n| [Runtime API Docs](https://viv.sifty.studio/reference/runtimes/js/)                                        | Reference for the JavaScript runtime API.                                                      |\n| [Viv: A Brief History](https://viv.sifty.studio/background/history-of-viv/)                                | A short overview of the intellectual and technical backdrop for the Viv project.               |\n| [*Curating Simulated Storyworlds*](https://viv.sifty.studio/background/curating_simulated_storyworlds.pdf) | My PhD thesis, which serves as the intellectual basis for Viv.                                 |\n\n\n## Example Projects\n\n| Project | Description |\n|---------|-------------|\n| [hello-viv-ts](examples/hello-viv-ts) | Minimal working example of using Viv in a TypeScript project. |\n| [hello-viv-js](examples/hello-viv-js) | Minimal working example of using Viv in a JavaScript project. |\n\n\n## Monorepo Layout\n\n```\nviv/\n├── compiler/              Viv compiler (Python)\n├── runtimes/\n│   └── js/                Viv JavaScript runtime (TypeScript)\n├── plugins/\n│   ├── vscode/            Viv VS Code extension\n│   ├── jetbrains/         Viv JetBrains plugin\n│   ├── sublime/           Viv Sublime Text package\n│   └── claude/            Viv Claude Code plugin\n├── syntax/                TextMate grammar and syntax examples\n├── docs/                  Language reference and background material\n├── examples/\n│   ├── hello-viv-ts/      Minimal TypeScript example project\n│   └── hello-viv-js/      Minimal JavaScript example project\n├── wizard/                Viv wizard (LLM-powered authoring tool)\n│   ├── dapt/              Domain-adaptive pretraining for the Viv wizard (in development)\n│   └── tool/              Viv wizard CLI (in development)\n└── scripts/               Utility scripts\n```\n\n\n## Contributing\n\nViv is not currently accepting pull requests. It's a solo project, and at this stage I prefer to maintain full control over the codebase.\n\nThat said, bug reports, feature requests, and general feedback are certainly welcome. You can get in touch by filing an issue [here on GitHub](https://github.com/siftystudio/viv/issues), or by sending an email to [hello@sifty.studio](mailto:hello@sifty.studio).\n\n\n## License\n\nViv is freely available for non-commercial use, while commercial use requires a license from [Sifty](https://sifty.studio). See [LICENSE.txt](LICENSE.txt) for the full details, or visit [sifty.studio/licensing](https://sifty.studio/licensing).\n\n*© 2025-2026 Sifty LLC. All rights reserved.*\n\n[docs-badge]: https://img.shields.io/badge/docs-online-blue?logo=astro&logoColor=white\n[docs-link]: https://viv.sifty.studio/quickstart/\n[ci-badge]: https://img.shields.io/github/actions/workflow/status/siftystudio/viv/ci.yml?branch=main&label=CI&logo=githubactions&logoColor=white\n[ci-link]: https://github.com/siftystudio/viv/actions/workflows/ci.yml\n[last-release-badge]: https://img.shields.io/github/release-date/siftystudio/viv?label=last%20release&logo=github&logoColor=white\n[last-release-link]: https://github.com/siftystudio/viv/releases\n[last-commit-badge]: https://img.shields.io/github/last-commit/siftystudio/viv?logo=git&logoColor=white\n[last-commit-link]: https://github.com/siftystudio/viv/commits/main\n[license-badge]: https://img.shields.io/badge/license-source--available-blue?logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxwYXRoIGQ9Ik0xMiAzdjE4Ii8%2BPHBhdGggZD0iTTMgN2w5LTQgOSA0Ii8%2BPHBhdGggZD0iTTMgMTNsMi02aDBsMiA2Ii8%2BPHBhdGggZD0iTTMgMTNoNCIvPjxwYXRoIGQ9Ik0xNyAxM2wyLTZoMGwyIDYiLz48cGF0aCBkPSJNMTcgMTNoNCIvPjxjaXJjbGUgY3g9IjEyIiBjeT0iMjEiIHI9IjEiLz48L3N2Zz4%3D\n[license-link]: https://github.com/siftystudio/viv/blob/main/LICENSE.txt\n[mailing-list-badge]: https://img.shields.io/badge/mailing%20list-subscribe-blue?logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjxyZWN0IHg9IjMiIHk9IjUiIHdpZHRoPSIxOCIgaGVpZ2h0PSIxNCIgcng9IjIiLz48cGF0aCBkPSJNMyA3bDkgNiA5LTYiLz48L3N2Zz4%3D\n[mailing-list-link]: https://siftystudio.kit.com/\n[pypi-badge]: https://img.shields.io/pypi/v/viv-compiler?logo=python&logoColor=white\n[pypi-link]: https://pypi.org/project/viv-compiler/\n[npm-badge]: https://img.shields.io/npm/v/%40siftystudio%2Fviv-runtime?logo=npm&logoColor=white\n[npm-link]: https://www.npmjs.com/package/@siftystudio/viv-runtime\n[jetbrains-badge]: https://img.shields.io/jetbrains/plugin/v/31012?label=jetbrains&logo=jetbrains&logoColor=white\n[jetbrains-link]: https://plugins.jetbrains.com/plugin/31012-viv\n[vscode-badge]: https://img.shields.io/github/v/release/siftystudio/viv?filter=vscode-v*&label=vs%20code&color=orange&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0yMy4xNSAyLjU5IDE4LjIuMmExLjUgMS41IDAgMCAwLTEuNy4yOUw3LjA0IDkuMTMgMi45MyA2YTEgMSAwIDAgMC0xLjI4LjA2TC4zMyA3LjI2YTEgMSAwIDAgMCAwIDEuNDhMMy45IDEyIC4zMiAxNS4yNmExIDEgMCAwIDAgMCAxLjQ4bDEuMzMgMS4yYTEgMSAwIDAgMCAxLjI4LjA2bDQuMTItMy4xMyA5LjQ2IDguNjNjLjQ0LjQ1IDEuMTMuNTcgMS43LjI5bDQuOTQtMi4zOGMuNTItLjI1Ljg1LS43Ny44NS0xLjM1VjMuOTRjMC0uNTgtLjMzLTEuMS0uODUtMS4zNlpNMTggMTcuNDUgMTAuODIgMTIgMTggNi41NXYxMC45WiIvPjwvc3ZnPg%3D%3D\n[vscode-link]: https://marketplace.visualstudio.com/items?itemName=siftystudio.viv\n[sublime-badge]: https://img.shields.io/github/v/release/siftystudio/viv?filter=sublime-v*&label=sublime%20text&color=orange&logo=sublimetext&logoColor=white\n[sublime-link]: https://github.com/siftystudio/viv/blob/main/plugins/sublime/README.md#getting-started\n[claude-badge]: https://img.shields.io/github/v/release/siftystudio/viv?filter=claude-v*&label=claude%20code&color=orange&logo=claude&logoColor=white\n[claude-link]: https://github.com/siftystudio/viv/blob/main/plugins/claude/README.md#getting-started\n",
  "bytes": 13460,
  "sha": "9561b9ababdaf5700171c71cf74387e0154075b48b53ee8cb91bbc90f3d43456",
  "repo_slug": "siftystudio/viv",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_siftystudio_viv_viv_617bb0ff/readme"
}