A DSL for agentic workflows where the LLM is the runtime
- GitHub stars
- 60
Install
/plugin install vvm@vvmRun it inside Claude Code after adding the marketplace with /plugin marketplace add karanchawla/vvm.
Contents
Discovered from sourceSkills 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:
- User runs
/vvm-boot,/vvm-compile,/vvm-run,/vvm-run-inspect,/vvm-registry-inspect, or/vvm-generate - User opens or references a
.vvmfile - User asks about VVM syntax, semantics, or patterns
- User wants to create an AI-powered workflow
Documentation Files
| File | Role | When to Read |
|---|---|---|
SKILL.md | Quick reference, triggers | Always first |
vvm.md | Execution semantics | When running programs |
spec.md | Language specification | For syntax/validation questions |
memory-spec.md | Agent memory (portable) | When using persistent agents |
patterns.md | Design patterns | When writing programs |
antipatterns.md | Anti-patterns | When 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
| # | Name | Concepts |
|---|---|---|
| 01 | hello-world | Minimal program |
| 02 | simple-agent-call | Agent with input |
| 03 | semantic-predicate | ? predicates |
| 04 | match-statement | Pattern matching |
| 05 | if-elif-else | Conditionals |
| 06 | while-loop | While loops |
| 07 | for-loop | For loops |
| 08 | with-input | Context passing |
| 09 | agent-options | retry, timeout, backoff |
| 10 | code-council | .with() derived agents |
| 11 | parallel-pmap | Parallel execution |
| 12 | functions | def and return |
| 13 | skill-imports | Skill imports |
| 14 | module-imports | Module imports |
| 15 | error-values | Error value matching |
| 16 | try-except-finally | Raised errors |
| 17 | choose-statement | AI-selected branching |
| 18 | constrain-require | Quality constraints |
| 19 | refine-loop | Iterative improvement |
| 20 | collection-helpers | map, filter, reduce |
| 21 | devils-advocate | Adversarial debate |
| 22 | full-research-pipeline | Complex workflow |
| 23 | ralph-wiggum-loop | Continuous improvement |
| 24 | agent-memory-basic | Memory binding + digest/ledger |
| 25 | agent-memory-modes | memory_mode: continue/dry_run/fresh |
| 26 | agent-memory-multi-tenant | Per-key isolation |
| 27 | agent-memory-parallel-safe | pmap-safe persistence |
| 28 | ref-composition | Ref composition patterns |
| 29 | ref-loop-accumulation | Accumulating refs in loops |
| 30 | materializer-pattern | Materializing refs |
| 31 | run-inspector | Inspecting run state |
| 32 | ouroboros | Self-modifying workflow |
| 33 | wisdom-of-crowds | Ensemble voting |
| 34 | hydra | Multi-headed agents |
| 35 | forge | Agent factory |
| 36 | inputs | Input declarations |
| 37 | debate | Module 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
- Minimal syntax - Familiar indentation-based blocks
- Explicit AI boundary - Agent calls are syntactically distinct (
@agent) - Eager execution - No lazy evaluation, sequential by default
- Semantic control flow - Branch on meaning, not just booleans
- Two error channels - Values (match) vs raised (try/except)
- Explicit parallelism - Only
pmapruns concurrently
Commands 6
VVM Boot
Read skills/vvm/SKILL.md for activation triggers, quick reference, and examples.
Then:
- Search for
.vvmfiles in the current directory - If found, list them and offer to run or create new
- 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
- Parse — Tokenize and build AST per grammar (E001-E005)
- Load Imports — Resolve
from "path" import ..., check files exist (E090, E032) - Collect Declarations — Gather agents, functions, skill imports, inputs, and exports/output-contract keys (E010-E031, E110-E114)
- Validate References — Check
@agentrefs,{placeholders}, variables, and statically-known module output property access (E040-E052, E114) - Validate Control Flow — Check return/break/continue/try structure (E050-E082)
- 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
| Flag | Description |
|---|---|
--offline | Disable network fetches for remote imports (cache-only mode) |
--cache-only | Alias 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.
- Resolve source (
@handle/slugorhttps://...) to a URL. - If
--offline/--cache-onlyis set:- Cache hit: compile from cache
- Cache miss: fail with
E095
- If online mode and cache is missing/expired, fetch and cache first.
- 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 Intent | VVM 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
- Identify agent roles — Each agent should have focused expertise
- Choose model tiers — Match model to task complexity:
haiku: Simple formatting, validation, extraction, classificationsonnet: Research, analysis, standard generation (default)opus: Complex reasoning, synthesis, critical decisions
- Decide program shape — Script-style run vs callable module contract (
input+export) - Plan data flow — How does data move between stages? Keep it structured/ref-friendly
- Identify parallelism — Use
pmapfor homogeneous list work; useparallel()for heterogeneous branches/races/voting - Plan state mode portability — Author code that works in in-context and artifact-backed modes
- Plan error handling — What can fail? Add
retry=, match onerror(), and fallbacks - 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/exportsurfaces 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 grammarskills/vvm/patterns.md— Design patterns to followskills/vvm/antipatterns.md— Patterns to avoidcommands/vvm-run.md— State modes, registry/offline optionscommands/vvm-run-inspect.md— Inspect UX for filesystem/sqlite/postgres runscommands/vvm-registry-inspect.md— Contract inspection for remote modulesexamples/— 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
| Flag | Description |
|---|---|
--offline | Disable network fetches for remote imports (cache-only mode) |
--cache-only | Alias for --offline |
Behavior
- Resolve the source to a URL (registry shorthand uses
VVM_REGISTRY_BASE_URL). - Enforce trust rules (
VVM_REGISTRY_REQUIRE_HTTPS, allowlist/denylist). - Resolve module from cache/fetch policy:
- Offline/cache-only: cache hit required, otherwise
E095 - Online: use fresh cache or fetch + cache
- Offline/cache-only: cache hit required, otherwise
- Validate cache integrity (
meta.jsonhash vsmodule.vvm); mismatch isE094. - Parse module and extract contract from
inputandexportdeclarations.
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 blockedE092: insecurehttp://import rejectedE093: invalid URL formatE094: cache integrity check failedE095: offline/cache-only cache missE090: requested export/contract parse dependency could not be resolved
Files to Read
skills/vvm/spec.md- URL imports, cache policy, and error codesskills/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:
--state=<filesystem|sqlite|postgres>(if provided)VVM_STATE_BACKENDfrom.vvm/.envor envfilesystemfallback for inspect
Flags
| Flag | Description |
|---|---|
--state=filesystem | Inspect .vvm/runs/<run-id>/state.md and bindings directory |
--state=sqlite | Inspect .vvm/runs/<run-id>/state.db via sqlite3 |
--state=postgres | Inspect Postgres run tables via psql |
What to Show
Always summarize:
- Run metadata: status, started/updated timestamps, state mode
- Execution summary: total statements, completed, failed, cancelled
- Binding summary: names, size, mime, attachment path
- 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 backendE097: sqlite backend unavailableE098: postgres backend unavailableE099: state backend read failure
Files to Read
skills/vvm/vvm.md- state backend semantics and inspectability rulesskills/vvm/spec.md- backend diagnostics and runtime error kinds
VVM Run
Execute a VVM program. You ARE the VVM runtime.
Execution
- Parse & Validate — Run
/vvm-compilechecks; stop on errors, proceed on warnings - Collect — Gather agents, functions, skill imports, exports (hoisted)
- 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
- Return — Output exported values as
{ name: value, ... }
Rules
- Sequential execution only (no implicit parallelism)
- Track
itbinding 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
| Flag | Description |
|---|---|
--state=filesystem | Filesystem artifact-backed state |
--state=sqlite | SQLite-backed run state (.vvm/runs/<run-id>/state.db) |
--state=postgres | Postgres-backed run state (VVM_POSTGRES_URL required) |
--input name="value" | Provide input values for the program |
--offline | Disable network fetches for remote imports (cache-only mode) |
--cache-only | Alias 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_URLis 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:
- Check
.vvm/registry/for cached copy - If
--offline/--cache-onlyis set:- Cache hit: use cached module (including stale entries, with warning)
- Cache miss: halt with
E095
- If online mode and cache is missing or expired (> 1 hour), fetch via HTTPS
- Cache with content hash for reproducibility
- 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 semanticsskills/vvm/spec.md- Language specification
Sponsors
Details
- Marketplace
- karanchawla/vvm
- Category
- Community
