Quickstart

Note

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.

Alright, let’s get started. First, make sure you’re up to date with the requirements. And then you can choose your own adventure below.

Requirements

• Python 3.11+ (for the Viv compiler)
• Node.js 18+ (for the Viv JavaScript runtime)

Getting started

☞ I do use LLMs

Unless you have ethical qualms surrounding LLM usage—and certainly such qualms have merit—the recommended interface between you and all things Viv is the Viv Claude Code plugin.

The plugin’s custom skills turn Claude into a Viv expert (with a copy of the Viv codebase) that can facilitate installation, building, debugging, and most pertinently, authoring. Even if you don’t want an LLM touching your content or code, this plugin can be an immense help for learning the system. It’s like having me in your terminal.

1. Install Claude Code.

2. Install the Viv Claude Code plugin:

   claude plugin marketplace add siftystudio/claude-plugins
   claude plugin install viv@siftystudio

3. Start using the plugin:

   • cd into the project where you intend to use Viv.
   • Boot up Claude Code there: claude.
   • Run the special setup skill: /viv:setup.
   • Claude Code will handle all installation and setup for you, and it will give you a tour of the Viv plugin (and the larger Viv project).

4. Now Claude Code will have deep Viv expertise any time you invoke it from your project directory, and there will also be a suite of Viv-specific Claude Code skills available there. See the plugin documentation for more information (or just ask Claude).

☞ I do not use LLMs

Alrighty, your Viv experience will be entirely LLM-free. It’s a symbolic AI system, after all.

1. Install the Viv compiler:

   pip install viv-compiler

2. Install the Viv JavaScript runtime:

   npm install @siftystudio/viv-runtime

3. Install the editor plugin of your choice:

   • The Viv JetBrains plugin is the recommended tool for authoring Viv code. Assuming your larger codebase is primarily JavaScript or TypeScript, you can use the WebStorm IDE, with our plugin exposing rich features for .viv files.
   • For more lightweight alternatives, there is also the Viv VS Code extension and the Viv Sublime Text package.

4. 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

5. 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

6. Consult the language reference for details on the Viv syntax, and start cooking up some constructs of your own!

   • If you’re using the Viv JetBrains plugin, you can get an interactive tutorial by pasting any Viv code (from the docs or another source) into your IDE and hovering over the keywords and other code.