Appearance

Installing vmblu ​

vmblu is a toolkit for building node- and message-based applications that can be inspected, generated, run, and exposed to agents through controlled capabilities.

vmblu is agent-independent: it does not require a specific coding agent, LLM provider, agent SDK or orchestration framework. At the same time, vmblu is strongly agent-oriented. It is designed for modern software workflows where agents help write code, applications expose standard agent-facing interfaces, and runtime guardrails make those applications safer to operate.

You normally install three things:

  • the VS Code extension to inspect and edit vmblu models;
  • the npm packages to create, generate and run vmblu applications;
  • agent support when you want a coding agent to understand the vmblu workflow.

Requirements ​

  • Node.js 18 or newer.
  • Visual Studio Code if you want to use the vmblu editor.
  • A JavaScript or TypeScript project target.
  • A coding agent such as Codex or Claude if you want agent-assisted project creation and development.

Generated vmblu applications can run in browser or Node.js environments, depending on the runtime selected in the model.

Installation ​

Ask your agent ​

Let your agent read this file and ask it to set up the project, or do it yourself:

Install The Editor ​

Install the vmblu extension from the VS Code Marketplace:

text
https://marketplace.visualstudio.com/items?itemName=vizualmodel.vmblu

In VS Code:

  1. Open the Extensions view with Ctrl+Shift+X.
  2. Search for vmblu.
  3. Install the extension.

Install The npm Packages ​

In a project that uses vmblu directly, install the CLI and runtime:

bash
npm install @vizualmodel/vmblu-cli @vizualmodel/vmblu-runtime

The CLI also installs @vizualmodel/vmblu-core as a dependency. The core package contains the shared model loading and compilation code used by vmblu tooling.

For one-off CLI usage:

bash
npx @vizualmodel/vmblu-cli --help

The examples below use the short vmblu command. If vmblu is not installed as a command in your project or shell, use npx @vizualmodel/vmblu-cli instead.

Install Agent Support ​

Agent support installs guidance files so a coding agent can work with vmblu projects more reliably. vmblu is agent-independent, so this support is agent-specific guidance over the same vmblu CLI, model and runtime architecture.

Install Codex support:

bash
vmblu agent install codex

Install Claude support:

bash
vmblu agent install claude

You can get the list of supported agents as follows.

bash
vmblu agent list

When the support files are installed, tell the agent:

text
use vmblu

The agent should then follow the vmblu workflow for the project.

Create A Project With An Agent ​

The most natural way to start a vmblu project is to tell your coding agent:

text
use vmblu

or give it a more explicit instruction:

text
Create a new vmblu application called my-new-application.

With vmblu support installed, the agent should:

  1. install or verify the vmblu CLI and runtime packages;
  2. initialize the project with vmblu init if needed;
  3. read .vmblu/vmblu.prompt.md;
  4. use the root .blu entrypoint to find the model in model/;
  5. treat nodes/ as the model-owned source code folder;
  6. generate the profile, application and capabilities when appropriate.

Create A Project Manually ​

You can also create the project yourself:

bash
vmblu init my-new-application

The generated project uses a root .blu entrypoint and keeps model files under model/:

text
my-new-application/
  my-new-application.blu
  package.json
  model/
    my-new-application.mod.blu
    my-new-application.mod.viz
  nodes/
  .vmblu/
    vmblu.prompt.md
    overrides/
    cache/
    logs/

The root entrypoint points to the actual model file:

json
{
  "kind": "vmblu.entrypoint",
  "version": 1,
  "model": "model/my-new-application.mod.blu"
}

Open the root .blu file in the editor.

Generate And Run ​

The runtime is selected in the vmblu model, normally through the editor. Users should not edit generated application files to change runtime imports.

The available runtime choices are:

text
@vizualmodel/vmblu-runtime/rt-base
@vizualmodel/vmblu-runtime/rt-als
@vizualmodel/vmblu-runtime/rt-browser-agent
@vizualmodel/vmblu-runtime/rt-nodejs-agent

The selected runtime determines which model-wide and node-level runtime settings are meaningful. The model stores those settings; the runtime normalizes and enforces them when the application runs.

A coding agent can usually choose the right dev or build command for the selected environment, such as browser or Node.js. See the User Guide for manual workflows.

Try The Examples ​

The examples live in a separate repository:

text
https://github.com/vizualmodel/vmblu-examples

Version Status ​

vmblu is pre-1.0. The editor, CLI, core package, runtime, and agent integration are usable, but project layout, package boundaries and distribution details may still evolve while the public API is being stabilized.

Feedback ​

  • Issues: https://github.com/vizualmodel/vmblu/issues
  • Discussions: https://github.com/vizualmodel/vmblu/discussions
  • Website: https://vmblu.dev