Karanchawla Vvm Vvm

VVM Skill

VVM (Vibe Virtual Machine) is a language for writing agentic programs where the LLM acts as the runtime.

When to Activate

Activate this skill when:

1. User runs /vvm-boot, /vvm-compile, /vvm-run, /vvm-run-inspect, /vvm-registry-inspect, or /vvm-generate
2. User opens or references a .vvm file
3. User asks about VVM syntax, semantics, or patterns
4. User wants to create an AI-powered workflow

Documentation Files

Quick Reference

Agent Definition

agent researcher(
  model="sonnet",
  prompt="thorough, cite sources",
  skills=["web-search"],
  permissions=perm(network="allow", bash="deny"),
)

Agent Call

result = @researcher `Find papers on {topic}.`(topic)
result = @researcher `Summarize.`(topic, retry=3, timeout="30s")

Agent Memory

agent assistant(model="sonnet", prompt="Helpful.", memory={ scope: "project", key: "user:alice" })
reply = @assistant `Continue.`(request)  # default: memory_mode="continue"
dry = @assistant `Read-only run.`(request, memory_mode="dry_run")
fresh = @assistant `Stateless run.`(request, memory_mode="fresh")

Semantic Predicate

ready = ?`production ready`(code)

if ?`needs more work`(draft):
  draft = @writer `Improve.`(draft)

Pattern Matching

match result:
  case ?`high quality`:
    publish(result)
  case error(kind="timeout"):
    result = @backup `Retry.`(request)
  case error(_):
    log_error(result)
  case _:
    pass

Choice

choose analysis by ?`best approach` as choice:
  option "quick":
    plan = @planner `Minimal plan.`()
  option "thorough":
    plan = @planner `Full plan.`()

Control Flow

# If/elif/else
if condition:
  do_something()
elif other:
  do_other()
else:
  do_default()

# While loop
while not ?`done`(result):
  result = @worker `Improve.`(result)

# For loop
for item in items:
  process(item)

Context Passing

# Implicit input (it)
with input data:
  result = @agent `Process.`()  # uses it == data

# Explicit input
result = @agent `Process.`(data)

Functions

def analyze(topic):
  research = @researcher `Find info on {topic}.`(topic)
  return @analyst `Analyze.`(research)

result = analyze("AI safety")

Error Handling

# Error values (match)
match result:
  case error(_):
    handle_error(result)

# Raised errors (try/except)
try:
  if ?`invalid`(input):
    raise "Invalid input"
except as err:
  log(err)
finally:
  cleanup()

Constraints

draft = @writer `Write report.`(data)

constrain draft(attempts=3):
  require ?`has citations`
  require ?`no hallucinations`

Imports/Exports

# Skill imports
import "web-search" from "github:anthropic/skills"

# Module value imports (agents are local)
from "./lib/research.vvm" import report

# Callable module import
from "./lib/research.vvm" import * as research
result = research(topic="AI", depth="deep")
report = result.report

# Exports (values only)
export result
export summary

Standard Library

# Parallel map
results = pmap(items, process)

# Sequential map/filter/reduce
mapped = map(items, transform)
filtered = filter(items, predicate)
def add(a, b):
  return a + b
total = reduce(items, add, init=0)

# Iterative refinement
final = refine(initial, max=5, done=is_ready, step=improve)

# Named fan-in
ctx = pack(research, analysis, topic=topic)

# Range
for i in range(10):
  process(i)

Examples

Commands

/vvm-boot

Initialize VVM for new or returning users. Detects existing files and provides onboarding.

/vvm-compile <file.vvm>

Validate a VVM program without executing. Reports errors and warnings with line numbers.

/vvm-run <file.vvm>

Execute a VVM program. You become the VVM runtime and execute statements sequentially, spawning subagents for agent calls.

/vvm-run-inspect

Inspect run state from filesystem, SQLite, or Postgres backends without re-running the workflow.

/vvm-registry-inspect <@handle/slug|https://...>

Inspect a remote module contract and cache metadata without executing the workflow.

/vvm-generate

Generate a VVM program from a natural language description. Analyzes intent, maps to VVM constructs, applies best practices, and produces well-structured code. Asks clarifying questions if the request is ambiguous.

Key Principles

1. Minimal syntax - Familiar indentation-based blocks
2. Explicit AI boundary - Agent calls are syntactically distinct (@agent)
3. Eager execution - No lazy evaluation, sequential by default
4. Semantic control flow - Branch on meaning, not just booleans
5. Two error channels - Values (match) vs raised (try/except)
6. Explicit parallelism - Only pmap runs concurrently

Source: karanchawla/vvm — distributed by TomeVault.