A DSL for agentic workflows where the LLM is the runtime

GitHub stars
60

Install

/plugin install vvm@vvm

Run it inside Claude Code after adding the marketplace with /plugin marketplace add karanchawla/vvm.

Contents

Discovered from source

Skills 1

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

FileRoleWhen to Read
SKILL.mdQuick reference, triggersAlways first
vvm.mdExecution semanticsWhen running programs
spec.mdLanguage specificationFor syntax/validation questions
memory-spec.mdAgent memory (portable)When using persistent agents
patterns.mdDesign patternsWhen writing programs
antipatterns.mdAnti-patternsWhen reviewing programs

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

#NameConcepts
01hello-worldMinimal program
02simple-agent-callAgent with input
03semantic-predicate? predicates
04match-statementPattern matching
05if-elif-elseConditionals
06while-loopWhile loops
07for-loopFor loops
08with-inputContext passing
09agent-optionsretry, timeout, backoff
10code-council.with() derived agents
11parallel-pmapParallel execution
12functionsdef and return
13skill-importsSkill imports
14module-importsModule imports
15error-valuesError value matching
16try-except-finallyRaised errors
17choose-statementAI-selected branching
18constrain-requireQuality constraints
19refine-loopIterative improvement
20collection-helpersmap, filter, reduce
21devils-advocateAdversarial debate
22full-research-pipelineComplex workflow
23ralph-wiggum-loopContinuous improvement
24agent-memory-basicMemory binding + digest/ledger
25agent-memory-modesmemory_mode: continue/dry_run/fresh
26agent-memory-multi-tenantPer-key isolation
27agent-memory-parallel-safepmap-safe persistence
28ref-compositionRef composition patterns
29ref-loop-accumulationAccumulating refs in loops
30materializer-patternMaterializing refs
31run-inspectorInspecting run state
32ouroborosSelf-modifying workflow
33wisdom-of-crowdsEnsemble voting
34hydraMulti-headed agents
35forgeAgent factory
36inputsInput declarations
37debateModule composition

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

Commands 6

VVM Boot

Read skills/vvm/SKILL.md for activation triggers, quick reference, and examples.

Then:

  1. Search for .vvm files in the current directory
  2. If found, list them and offer to run or create new
  3. If none found, ask what the user wants to build and generate an example

VVM Compile

Validate a VVM program without executing it. This is static analysis only.

Phases

  1. Parse — Tokenize and build AST per grammar (E001-E005)
  2. Load Imports — Resolve from "path" import ..., check files exist (E090, E032)
  3. Collect Declarations — Gather agents, functions, skill imports, inputs, and exports/output-contract keys (E010-E031, E110-E114)
  4. Validate References — Check @agent refs, {placeholders}, variables, and statically-known module output property access (E040-E052, E114)
  5. Validate Control Flow — Check return/break/continue/try structure (E050-E082)
  6. Warnings — Non-blocking issues like unused variables and contract hygiene checks (W001-W051)

Output

Success:

✅ <file.vvm> is valid

Contract:
  Inputs:
    topic (required): "The topic to research"
    depth (optional = "medium"): "Research depth"

  Outputs:
    report
    summary

Agents: <count>
Functions: <count>

Error:

❌ Validation failed

E0XX line N col C: description
  <source line>
  ^

If no file specified, search for .vvm files and prompt user to select.

Flags

FlagDescription
--offlineDisable network fetches for remote imports (cache-only mode)
--cache-onlyAlias for --offline

Contract Display

When compilation succeeds, the contract shows what inputs the module requires and what outputs it produces. In VVM, outputs are derived from export declarations. This allows you to inspect a workflow's requirements before running it.

For remote modules, fetch and cache first, then display the contract:

/vvm-compile "@alice/research"
/vvm-compile "https://example.com/research.vvm"

Same output — the contract is extracted from the parsed module.

For a dedicated registry discovery view (contract + cache metadata), use:

/vvm-registry-inspect "@alice/research"

Remote Compile Behavior

For URL/registry imports, /vvm-compile uses the same resolver, cache, trust controls, and integrity checks as runtime module loading.

  1. Resolve source (@handle/slug or https://...) to a URL.
  2. If --offline/--cache-only is set:
    • Cache hit: compile from cache
    • Cache miss: fail with E095
  3. If online mode and cache is missing/expired, fetch and cache first.
  4. Parse module and extract contract without executing top-level statements or spawning agents.

Files to Read

  • skills/vvm/spec.md - Complete grammar and error definitions (Section 16)
  • skills/vvm/vvm.md - Contract extraction algorithm (Section 4.4.3)

VVM Generate

Generate well-structured VVM programs from natural language descriptions. This command helps users transition from natural language prompting to VVM's structured agent orchestration, including modern VVM features (parallel blocks, artifact-backed state modes, registry imports, and callable module contracts).

Phases

Phase 1: Understand Intent

Read the user's natural language description and infer:

  • The core goal (what should the program accomplish?)
  • Input requirements (what data does it need?)
  • Output expectations (what should it produce?)
  • Quality requirements (any constraints or standards?)

Do not ask clarifying questions. Make reasonable assumptions based on the description and generate the program immediately.

Phase 2: Analyze Requirements

Map the user's intent to VVM constructs:

User IntentVVM Construct
"Call an AI to do X"@worker \prompt`(request)`
"Check if X is true"?\condition`(value)`
"Route based on content type"match value: case ?\pattern`:`
"AI picks best approach"choose value by ?\criterion` as choice:`
"If X then Y else Z"if/elif/else
"Repeat until done"while with bounds or refine()
"Process each item"for item in items:
"Process items in parallel"pmap(items, function)
"Run different tasks concurrently"parallel(...) as results: with named branches
"Race multiple strategies"parallel(join="first", on_fail="continue")
"Need N-of-M consensus"parallel(join="any", count=N, on_fail="continue")
"Set context for operations"with input value:
"Handle failures gracefully"match on error(_)
"Guaranteed cleanup"try/except/finally
"Create agent variants".with() or inline @{...}
"Reuse logic"def function(params):
"Use external tools"import + skills= + permissions=
"Reusable workflow API"input ... + export ... + callable module import (* as)
"Use shared remote workflow"from "@handle/slug" import ... or from "https://..." import ...
"Transform a list"map(items, fn)
"Filter a list"filter(items, predicate)
"Aggregate results"reduce(items, fn, init=value)
"Combine multiple values"pack(a, b, c)
"Iteratively improve"refine(seed, max=N, done=check, step=improve)
"Enforce quality standards"constrain value(): require ?\criterion``
"Large outputs or long workflows"Keep agent boundaries ref-friendly (portable across --state= backends)

Phase 3: Design Architecture

  1. Identify agent roles — Each agent should have focused expertise
  2. Choose model tiers — Match model to task complexity:
    • haiku: Simple formatting, validation, extraction, classification
    • sonnet: Research, analysis, standard generation (default)
    • opus: Complex reasoning, synthesis, critical decisions
  3. Decide program shape — Script-style run vs callable module contract (input + export)
  4. Plan data flow — How does data move between stages? Keep it structured/ref-friendly
  5. Identify parallelism — Use pmap for homogeneous list work; use parallel() for heterogeneous branches/races/voting
  6. Plan state mode portability — Author code that works in in-context and artifact-backed modes
  7. Plan error handling — What can fail? Add retry=, match on error(), and fallbacks
  8. Add quality and observability hooks — Use constrain/require; include outputs useful for run inspection

Phase 4: Generate Code

Apply these patterns (from skills/vvm/patterns.md):

  • Agent Specialization: Each agent has one clear purpose
  • Pipeline Composition: Clear I/O at each stage
  • Model Tiering: Right model for task complexity
  • State Mode Selection: Keep workflows portable across in-context|filesystem|sqlite|postgres
  • Parallel Block Patterns: parallel() for heterogeneous concurrent work, races, and N-of-M voting
  • Explicit Data Flow: Don't over-rely on implicit it
  • Graceful Degradation: Handle failures with fallbacks
  • Bounded Iteration: Always set max limits on loops
  • Contract-Safe Composition: Use explicit input/export surfaces and guard optional outputs when needed

Avoid these anti-patterns (from skills/vvm/antipatterns.md):

  • God Agent: One agent doing everything (split into specialists)
  • Context Explosion: Passing all data everywhere (pass only what's needed)
  • Unbounded Loops: No max iterations (always add bounds)
  • Model Inflation: Using opus for simple tasks (tier appropriately)
  • Silent Failures: Not handling errors (match on error(_))
  • Large artifact workflows in in-context mode when scale/inspection matters
  • Blind remote imports without trust/inspect/cache policy
  • Assuming module output keys always exist across evolving contracts

Code structure:

# 1. Skill imports (if external tools needed)
import "skill-name" from "source"

# 2. Module imports (optional local/registry/URL workflows)
from "./lib/workflow.vvm" import * as workflow

# 3. Inputs (for reusable/callable workflows)
input request: "What this workflow needs"

# 4. Agent definitions (specialized, model-tiered)
agent worker(model="tier", prompt="Focused expertise.")

# 5. Helper functions (for reusable patterns)
def helper(params):
  return result

# 6. Optional heterogeneous parallel work
parallel(join="all", on_fail="continue") as branches:
  a = @worker `Task A.`(request)
  b = @worker `Task B.`(request)

# 7. Main workflow logic
result = @worker `task`(request)

# 8. Quality constraints (if needed)
constrain result():
  require ?`quality criterion`

# 9. Exports (workflow contract surface)
export result

Phase 5: Output

Output ONLY the VVM program code. No explanations, no design decisions, no markdown formatting, no code fences. Just the raw VVM program text that can be directly saved to a .vvm file.

Output Format

Output the VVM program directly with no surrounding text or formatting. The response should start with the first line of VVM code (typically a comment or import) and end with the last line (typically an export).

Files to Read

  • skills/vvm/spec.md — Language specification and grammar
  • skills/vvm/patterns.md — Design patterns to follow
  • skills/vvm/antipatterns.md — Patterns to avoid
  • commands/vvm-run.md — State modes, registry/offline options
  • commands/vvm-run-inspect.md — Inspect UX for filesystem/sqlite/postgres runs
  • commands/vvm-registry-inspect.md — Contract inspection for remote modules
  • examples/ — Reference examples for similar patterns (especially 33, 34, 38, 39)

Example

User: /vvm-generate Create a program that reviews pull requests for security issues

Response:

PR Security Review Pipeline

agent diff_analyzer(model="sonnet", prompt="Code change analyst. Understand what changed and why.") agent security_reviewer(model="opus", prompt="Security expert. Find vulnerabilities, injection risks, auth issues.") agent report_writer(model="sonnet", prompt="Technical writer. Create clear, actionable reports.")

analysis = @diff_analyzer Analyze these code changes: {}(pr_diff)

security_findings = @security_reviewer Review for security vulnerabilities.(analysis)

match security_findings: case error(_): security_findings = "Security review unavailable. Manual review recommended."

report = @report_writer Create a security review report with findings and recommendations.( pack(analysis, security_findings) )

constrain report(attempts=2): require ?has specific recommendations require ?mentions severity levels

export report

VVM Registry Inspect

Inspect a remote workflow without running it. This command resolves a registry/URL module, applies cache and trust policy, and shows its input/output contract.

Usage

/vvm-registry-inspect "@alice/research"
/vvm-registry-inspect "https://example.com/workflows/research.vvm"

Flags

FlagDescription
--offlineDisable network fetches for remote imports (cache-only mode)
--cache-onlyAlias for --offline

Behavior

  1. Resolve the source to a URL (registry shorthand uses VVM_REGISTRY_BASE_URL).
  2. Enforce trust rules (VVM_REGISTRY_REQUIRE_HTTPS, allowlist/denylist).
  3. Resolve module from cache/fetch policy:
    • Offline/cache-only: cache hit required, otherwise E095
    • Online: use fresh cache or fetch + cache
  4. Validate cache integrity (meta.json hash vs module.vvm); mismatch is E094.
  5. Parse module and extract contract from input and export declarations.

No top-level execution occurs. No agent calls are spawned.

Output

✅ Registry module inspect

Source:
  Requested: @alice/research
  Resolved URL: https://vvm.dev/alice/research.vvm

Cache:
  Status: hit (fresh)
  Path: .vvm/registry/https_vvm.dev__alice__research.vvm/a7b3c9d2e1f0/module.vvm
  Content hash: a7b3c9d2e1f0456789abcdef...
  Fetched at: 2026-03-14T09:12:44Z

Contract:
  Inputs:
    topic (required): "Topic to investigate"
    depth (optional = "medium")

  Outputs:
    report
    summary

Common Errors

  • E091: URL fetch failure or domain blocked
  • E092: insecure http:// import rejected
  • E093: invalid URL format
  • E094: cache integrity check failed
  • E095: offline/cache-only cache miss
  • E090: requested export/contract parse dependency could not be resolved

Files to Read

  • skills/vvm/spec.md - URL imports, cache policy, and error codes
  • skills/vvm/vvm.md - Resolver and contract extraction semantics

VVM Run Inspect

Inspect a prior VVM run without executing the program again.

Usage

/vvm-run-inspect 20260127-143052-a7f3b2

Backend Selection

Inspection backend resolution:

  1. --state=<filesystem|sqlite|postgres> (if provided)
  2. VVM_STATE_BACKEND from .vvm/.env or env
  3. filesystem fallback for inspect

Flags

FlagDescription
--state=filesystemInspect .vvm/runs/<run-id>/state.md and bindings directory
--state=sqliteInspect .vvm/runs/<run-id>/state.db via sqlite3
--state=postgresInspect Postgres run tables via psql

What to Show

Always summarize:

  1. Run metadata: status, started/updated timestamps, state mode
  2. Execution summary: total statements, completed, failed, cancelled
  3. Binding summary: names, size, mime, attachment path
  4. Failure list: statement index/text + error details

Backend-Specific Recipes

Filesystem

Read:

  • .vvm/runs/<run-id>/state.md
  • .vvm/runs/<run-id>/attachments/ (if present)

SQLite

Run queries like:

sqlite3 -header -column ".vvm/runs/<run-id>/state.db" "SELECT id, status, started_at, updated_at FROM run;"
sqlite3 -header -column ".vvm/runs/<run-id>/state.db" "SELECT statement_index, status, error_message FROM execution ORDER BY id;"
sqlite3 -header -column ".vvm/runs/<run-id>/state.db" "SELECT name, execution_id, summary, bytes, attachment_path FROM bindings ORDER BY updated_at;"

Postgres

Run queries like:

psql "$VVM_POSTGRES_URL" -c "SELECT id, status, started_at, updated_at FROM vvm.run WHERE id = '<run-id>';"
psql "$VVM_POSTGRES_URL" -c "SELECT statement_index, status, error_message FROM vvm.execution WHERE run_id = '<run-id>' ORDER BY id;"
psql "$VVM_POSTGRES_URL" -c "SELECT name, execution_id, summary, bytes, attachment_path FROM vvm.bindings WHERE run_id = '<run-id>' ORDER BY updated_at;"

Common Errors

  • E096: unknown/unsupported backend
  • E097: sqlite backend unavailable
  • E098: postgres backend unavailable
  • E099: state backend read failure

Files to Read

  • skills/vvm/vvm.md - state backend semantics and inspectability rules
  • skills/vvm/spec.md - backend diagnostics and runtime error kinds

VVM Run

Execute a VVM program. You ARE the VVM runtime.

Execution

  1. Parse & Validate — Run /vvm-compile checks; stop on errors, proceed on warnings
  2. Collect — Gather agents, functions, skill imports, exports (hoisted)
  3. Execute — Process statements in source order:
    • @agent ...(...) → Spawn subagent via Task tool, wait for result
    • ?...(...) → Evaluate semantic predicate locally (no spawn)
    • Control flow (if/while/for/match/choose) → Follow program structure
    • Assignments, try/except, raise → Standard execution
  4. Return — Output exported values as { name: value, ... }

Rules

  • Sequential execution only (no implicit parallelism)
  • Track it binding through scopes
  • Agent calls spawn subagents; predicates evaluate locally
  • Two error channels: error values (returned) vs raised errors (abort flow)
  • Never execute non-chosen branches in match/choose

State Modes

VVM supports four execution state modes:

In-Context Mode (default)

  • All state kept in token context
  • Agent calls return strings
  • No filesystem artifacts
  • Use for: quick iteration, small workflows

Filesystem Mode

  • Agent outputs written to .vvm/runs/<run-id>/bindings/
  • Agent calls return ref values (pointers + summaries)
  • Saves tokens for long workflows
  • Use for: production runs, long workflows, large outputs

SQLite Mode

  • Run state written to .vvm/runs/<run-id>/state.db
  • Subagents write binding rows directly via sqlite3
  • Full outputs written to local attachments; refs point to attachment paths
  • Use for: local SQL inspection and portable single-file state

Postgres Mode

  • Run state written to configured Postgres schema
  • Subagents write binding rows directly via psql
  • Full outputs written to local attachments; refs point to attachment paths
  • Use for: team observability and high-parallel workflows

Flags

FlagDescription
--state=filesystemFilesystem artifact-backed state
--state=sqliteSQLite-backed run state (.vvm/runs/<run-id>/state.db)
--state=postgresPostgres-backed run state (VVM_POSTGRES_URL required)
--input name="value"Provide input values for the program
--offlineDisable network fetches for remote imports (cache-only mode)
--cache-onlyAlias for --offline

DB Backend Configuration

Set in .vvm/.env or environment:

VVM_STATE_BACKEND=in-context
VVM_POSTGRES_URL=postgresql://user:pass@host:5432/db
VVM_POSTGRES_SCHEMA=vvm
VVM_STATE_ATTACHMENT_THRESHOLD_BYTES=65536

Notes:

  • VVM_POSTGRES_URL is required for --state=postgres.
  • DB mode credentials are visible to subagents in direct-write mode. Use least-privilege roles.
  • Attachments are local-only in this version.

Registry Shorthand

Programs can import modules using a registry path:

from "@alice/research" import deep_research

This resolves to https://vvm.dev/alice/research.vvm by default (@ stripped, .vvm appended).

Configure: Set VVM_REGISTRY_BASE_URL in .vvm/.env or as an environment variable.

URL Module Imports

Programs can also import modules from full HTTPS URLs:

from "https://raw.githubusercontent.com/example/vvm-libs/main/research.vvm" import deep_research

findings = deep_research("quantum computing")
export findings

Behavior:

  1. Check .vvm/registry/ for cached copy
  2. If --offline/--cache-only is set:
    • Cache hit: use cached module (including stale entries, with warning)
    • Cache miss: halt with E095
  3. If online mode and cache is missing or expired (> 1 hour), fetch via HTTPS
  4. Cache with content hash for reproducibility
  5. Parse and execute as local module

Security: Only HTTPS URLs are allowed. HTTP is rejected by default with E092.

Cache location: .vvm/registry/<escaped_url>/<hash>/module.vvm

Domain Trust Controls

Configure allowed/blocked domains in .vvm/.env:

# Allow only specific domains
VVM_REGISTRY_ALLOWLIST_DOMAINS=vvm.dev,raw.githubusercontent.com

# Or block specific domains
VVM_REGISTRY_DENYLIST_DOMAINS=untrusted-site.com

# Custom registry base URL
VVM_REGISTRY_BASE_URL=https://registry.mycompany.com/

Blocked imports produce E091 with reason="domain_blocked".

Narration Protocol

Use emoji markers to track execution state:

📍 start | 📦 bind | ✅ success | ❌ error | 🔄 loop | ⏳ waiting | 🎯 decision | ⚡ parallel

If no file specified, search for .vvm files and prompt user to select.

Files to Read

  • skills/vvm/vvm.md - Complete execution semantics
  • skills/vvm/spec.md - Language specification

Sponsors

Details

Marketplace
karanchawla/vvm
Category
Community