Welcome to the monorepo for Viv, an engine for emergent narrative in games and simulations.
In 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.
If you're new to Viv, check out the homepage for a proper introduction.
Viv is a source-available project, which means that:
- Anyone can view its full codebase (which lives here in this monorepo).
- Non-commercial use is freely permitted.
- Commercial use requires a license.
Below, 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 section providing a high-level map of the codebase, for folks who want to explore around in there.
Viv 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:
- Each system component is versioned independently, always under semantic versioning. The respective latest versions of the components will always be compatible with one another.
- Currently all components are in the
0.xseries and approaching1.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. - The system is backed by 1000+ tests across the component test suites, all of which run via CI on every push.
- Viv currently ships a single runtime, 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.
- Python 3.11+ (for the Viv compiler)
- Node.js 18+ (for the Viv JavaScript runtime)
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.
-
Install Claude Code.
-
Install the Viv Claude Code plugin:
claude plugin marketplace add siftystudio/claude-plugins claude plugin install viv@siftystudio
-
In Claude Code, run the
/viv:setupskill.- Claude takes it from there, installing Viv components, setting up your project, answering your questions, and proposing next steps.
-
Install the compiler, and verify it works:
pip install viv-compiler vivc --test
-
Install the runtime:
npm install @siftystudio/viv-runtime
-
Clone and run an example project:
npx degit siftystudio/viv/examples/hello-viv-ts my-viv-project # or hello-viv-js cd my-viv-project npm install && npm start
-
In your cloned project, try making a few edits to the simple Viv code in
src/content/source.viv, then recompile and re-run:vivc -i src/content/source.viv -o src/content/compiled_content_bundle.json npm start
-
Check out the full Quickstart guide for information on editor plugins and LLM-augmented authoring, and consult the language reference for details on the Viv syntax.
| Package | Description | Install |
|---|---|---|
| Compiler | Compiles .viv source files into JSON content bundles. |
PyPI |
| JavaScript Runtime | Action selection, planning, and story sifting from a content bundle. | npm |
| JetBrains Plugin | Full-featured IDE support for .viv files. This is the recommended tool for writing Viv code. |
JetBrains Marketplace |
| VS Code Extension | Editor support for .viv files. |
VS Marketplace |
| Sublime Text Package | Lightweight editor support for .viv files. |
GitHub |
| Claude Code Plugin | LLM-powered Viv expertise in your terminal. | GitHub |
| Resource | Description |
|---|---|
| Quickstart | Installation, editor plugins, and LLM-augmented authoring for those that want it. |
| Introduction | A complete introduction to Viv: features, design philosophy, and an extensive tour. |
| Language Reference | A complete specification of the Viv language. |
| Compiler Reference | Reference for the compiler: CLI, API, troubleshooting. |
| Runtime API Docs | Reference for the JavaScript runtime API. |
| Viv: A Brief History | A short overview of the intellectual and technical backdrop for the Viv project. |
| Curating Simulated Storyworlds | My PhD thesis, which serves as the intellectual basis for Viv. |
| Project | Description |
|---|---|
| hello-viv-ts | Minimal working example of using Viv in a TypeScript project. |
| hello-viv-js | Minimal working example of using Viv in a JavaScript project. |
viv/
├── compiler/ Viv compiler (Python)
├── runtimes/
│ └── js/ Viv JavaScript runtime (TypeScript)
├── plugins/
│ ├── vscode/ Viv VS Code extension
│ ├── jetbrains/ Viv JetBrains plugin
│ ├── sublime/ Viv Sublime Text package
│ └── claude/ Viv Claude Code plugin
├── syntax/ TextMate grammar and syntax examples
├── docs/ Language reference and background material
├── examples/
│ ├── hello-viv-ts/ Minimal TypeScript example project
│ └── hello-viv-js/ Minimal JavaScript example project
├── wizard/ Viv wizard (LLM-powered authoring tool)
│ ├── dapt/ Domain-adaptive pretraining for the Viv wizard (in development)
│ └── tool/ Viv wizard CLI (in development)
└── scripts/ Utility scripts
Viv is not currently accepting pull requests. It's a solo project, and at this stage I prefer to maintain full control over the codebase.
That said, bug reports, feature requests, and general feedback are certainly welcome. You can get in touch by filing an issue here on GitHub, or by sending an email to hello@sifty.studio.
Viv is freely available for non-commercial use, while commercial use requires a license from Sifty. See LICENSE.txt for the full details, or visit sifty.studio/licensing.
© 2025-2026 Sifty LLC. All rights reserved.
