Appearance

vmblu Installation Instructions ​

This document describes the current recommended installation paths for vmblu.

vmblu has three separate pieces:

  • the VS Code extension, used to inspect and edit vmblu models;
  • the npm packages, used to initialize projects, generate applications, and run generated apps;
  • optional coding-agent integration for Codex, Claude, and other agents.

The CLI, runtime, schemas, and capability generation are the canonical vmblu distribution. Agent skills/plugins are integration layers over that core.

Requirements ​

  • Visual Studio Code, if you want to use the vmblu editor.
  • Node.js 18 or newer.
  • A JavaScript or TypeScript project target. Generated apps can run in browser or Node.js environments depending on the model and runtime.
  • Optional: a coding agent such as Codex or Claude.

vmblu is coding-agent agnostic. It does not require a specific agent, but an agent can make model creation and code generation much faster.

Give This Guide To A Coding Agent ​

You can give this document to your coding agent as context and ask it to set up vmblu for you. The full document is useful context; the short prompt below is the part to copy into the agent conversation.

md
Use the attached vmblu installation instructions as context.

Set up vmblu for this project:

1. Install or verify the vmblu CLI and runtime packages.
2. Install the appropriate vmblu agent support for this coding agent.
3. Initialize the project with `vmblu init` if it is not already initialized.
4. Read `.vmblu/vmblu.prompt.md` before making project changes.
5. Use the root `.blu` entrypoint to find the model in `model/`.

Do not overwrite existing project files without checking first.

Install The VS Code Extension ​

Install the vmblu extension from VS Code:

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

Marketplace link:

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

Install The npm Packages ​

For a project that uses vmblu directly:

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

For one-off CLI usage without installing first:

bash
npx @vizualmodel/vmblu-cli --help

The runtime package exposes explicit runtime variants. Generated apps should import one of these subpaths:

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

Do not use the package root @vizualmodel/vmblu-runtime as a runtime import. New vmblu models should declare the runtime explicitly in the model header.

Install Agent Support ​

Codex ​

For Codex users, the preferred route is the vmblu Codex plugin when it is available. The plugin includes the vmblu skill plus plugin metadata, icons, starter prompts, and a place for future Codex-specific features.

The repo-local plugin source lives at:

text
plugins/vmblu/

During development, refresh it from the canonical Codex agent files with:

bash
node cli/bin/vmblu.js plugin build-codex

To assemble a distributable copy:

bash
node cli/bin/vmblu.js plugin build-codex --out ./dist/plugins/vmblu

If plugin installation is not available in a user's Codex environment, install the lightweight Codex skill instead:

bash
vmblu agent install codex

or, without a global vmblu command:

bash
npx @vizualmodel/vmblu-cli agent install codex

Both routes install the same core Codex guidance. The plugin is the more user-friendly and future-proof package; the skill installer remains the simple fallback and developer path.

Claude ​

Claude support is installed through the generic agent installer:

bash
vmblu agent install claude

or:

bash
npx @vizualmodel/vmblu-cli agent install claude

Claude support should stay Claude-native. It does not need to mirror the Codex plugin or Codex skill layout.

List Available Agent Installers ​

bash
vmblu agent list

or:

bash
npx @vizualmodel/vmblu-cli agent list

Create A New vmblu Project ​

The recommended project initialization command is:

bash
vmblu init my-new-application

or, without a global vmblu command:

bash
npx @vizualmodel/vmblu-cli init my-new-application

vmblu init creates the target folder if it does not exist.

Current default layout:

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 my-new-application.blu file is a small entrypoint manifest:

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

Open the root .blu file in the editor or pass it to CLI commands. The CLI resolves it to the real model file in model/.

Examples:

bash
vmblu make-app my-new-application.blu
vmblu make-capabilities my-new-application.blu
vmblu profile my-new-application.blu

Direct model paths are still accepted:

bash
vmblu make-app model/my-new-application.mod.blu

Using A Coding Agent ​

After installing the Codex plugin, Codex skill, or Claude support, tell the agent:

text
use vmblu

The agent should then:

  1. Detect or initialize the vmblu project.
  2. Read .vmblu/vmblu.prompt.md.
  3. Use the root .blu entrypoint to find the model.
  4. Treat model/ as the model file set.
  5. Treat nodes/ as model-owned source code.

If no agent support is installed, include the instructions explicitly:

md
We are making a new application with vmblu.

Initialize the project:

`vmblu init my-new-application`

If `vmblu` is not on PATH, use:

`npx @vizualmodel/vmblu-cli init my-new-application`

Before making changes, read:

`my-new-application/.vmblu/vmblu.prompt.md`

Use the root `my-new-application.blu` entrypoint to find the model file.

Running A Model ​

Most users should ask their coding agent to generate and run the app.

Manual generation:

bash
vmblu make-app my-new-application.blu

The generated app is written by convention under model/, for example:

text
model/my-new-application.app.js

The package's dev, build, and preview scripts depend on the application type and frontend/server tooling selected for the project.

Current Version Status ​

vmblu is still pre-1.0. The editor, CLI, runtime, and agent integration are usable, but project layout and distribution details may still evolve.

The current direction is:

  • root .blu entrypoints;
  • model files in model/;
  • slim .vmblu/ folders for local vmblu metadata only;
  • explicit runtime subpaths;
  • Codex plugin as the preferred Codex UX;
  • vmblu agent install <agent> as the generic fallback installer.

Feedback ​

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