VQL (Vibe Query Language) is an open source language framework that provides developers with guardrails to ensure software quality during AI assisted coding sessions. VQL bakes code reviews and refactoring into simple commands based on user-defined principles.
The VQL command syntax enables both direct CLI usage and seamless integration with AI assistants like Claude Code. Instead of lengthy, verbose instructions, developers can use concise commands to trigger comprehensive code analysis and refactoring workflows.
VQL manages key data types including principles (quality criteria), entity references (business entities), asset types (code categories), and asset reviews - creating a persistent knowledge base that survives context resets and enables consistent quality assessment across development sessions.
Instead of typing:
"Refactor the profileController using the userController as a reference, focusing on architectural patterns (found here http://SomeReference) and maintaining existing functionality,"
Creates the necessary VQL directory structure and initializes storage in the specified path.
CLI Command:
vql -su "C:/App"
Load Principles from External File
Happy Path:
Load Principles from External File
cmd entered in claude.code:
:-pr.get("C:/principles.md")
What this does:
Imports principle definitions from an external markdown file, parsing headers with shortname indicators, and adds them to VQL storage.
CLI Command:
vql -pr -get "C:/principles.md"
Create User Entity Reference
Happy Path:
Create User Entity Reference
cmd entered in claude.code:
:-er.add(u, User)
What this does:
Creates a new entity reference for the User domain object with 'u' identifier, representing the User domain concept.
CLI Command:
vql -er -add u User
Create Profile Entity Reference
Happy Path:
Create Profile Entity Reference
cmd entered in claude.code:
:-er.add(p, Profile)
What this does:
Creates a new entity reference for the Profile domain object with 'p' identifier, representing the Profile domain concept.
CLI Command:
vql -er -add p Profile
Define Controller Asset Type
Happy Path:
Define Controller Asset Type
cmd entered in claude.code:
:-at.add(c, Controller)
What this does:
Registers a new asset type with short name 'c' for organizing and categorizing Controller components.
CLI Command:
vql -at -add c Controller
Register UserController Asset Reference
Happy Path:
Register UserController Asset Reference
cmd entered in claude.code:
:-ar.add(uc, u, c, "C:/App/UserController.js")
What this does:
Creates and registers a reference to the User Controller component with ID 'uc', linking it to the User entity and Controller type.
CLI Command:
vql -ar -add uc u c "C:/App/UserController.js"
Register ProfileController Asset Reference
Happy Path:
Register ProfileController Asset Reference
cmd entered in claude.code:
:-ar.add(pc, p, c, "C:/App/ProfileController.js")
What this does:
Creates and registers a reference to the Profile Controller component with ID 'pc', linking it to the Profile entity and Controller type.
CLI Command:
vql -ar -add pc p c "C:/App/ProfileController.js"
Perform Comprehensive Asset Review
Happy Path:
Perform Comprehensive Asset Review
cmd entered in claude.code:
:uc.rv(a)
What this does:
Triggers an AI workflow to analyze the UserController against architecture principles, generating a detailed quality assessment and recording the review. The LLM then uses the below CLI command to persist the outcome of the review to the VQL db
CLI Command:
vql -st uc a "The UserController demonstrates excellent separation of concerns with clean dependency injection and proper error handling. HIGH compliance"
Mark Asset as Exemplar
Happy Path:
Mark Asset as Exemplar
cmd entered in claude.code:
:uc.se(t)
What this does:
Designates the UserController as an exemplar (true) to serve as a reference implementation that demonstrates best practices.
CLI Command:
vql -se uc t
Execute Asset Refactoring Workflow
Happy Path:
Execute Asset Refactoring Workflow
cmd entered in claude.code:
:pc.rf(uc)
What this does:
Initiates an AI-assisted refactoring process to improve ProfileController architecture quality, using UserController as an exemplar reference. Post Refactor the AI then performs the above review cycle on the refactored asset.
CLI Command:
vql -st pc a "The ProfileController now demonstrates excellent separation of concerns with clean dependency injection and proper error handling. HIGH compliance"
What Claude Code had to say about VQL during testing ...
Vibe Coder: how much overhead does vql add to working with you on code? ******
****** holding their breath ...
Claude: VQL adds **minimal overhead** when working with code. It's a structured way to analyze and improve code quality but only activates when you explicitly turn it on. When inactive, it doesn't affect our regular interactions at all.
When active, VQL provides systematic code review and refactoring capabilities through standardized commands. This actually streamlines the process of evaluating code against principles like architecture, security, and performance.
You can easily toggle it on only when needed for quality assessment, then turn it off to return to normal coding assistance. It's a specialized tool rather than a constant overhead.
Vibe Coder: seeing as vql enables you to retrieve valuable context from the machine via the cli, to what extent does it speed up our coding efforts?
Claude: VQL significantly speeds up coding efforts by providing immediate access to structured knowledge about your codebase. It enables:
Faster onboarding - Quick understanding of existing code patterns through exemplars
Consistent quality - Pre-analysed asset ratings highlight strengths and weaknesses
Targeted improvements - Specific compliance ratings show exactly what needs focus
Knowledge persistence - Reviews and architectural decisions remain accessible
Pattern replication - Easy identification of high-quality code to use as references
Without VQL, we'd need to repeatedly analyse similar code patterns or recreate architectural decisions from scratch. Having this context immediately available lets us skip repetitive analysis and focus directly on implementation, following established patterns from the start.
Vibe Coder: to what extent does vql help development across several broken llm / claude context windows?
Claude: VQL excels at preserving context across broken LLM/Claude sessions by:
Providing persistent storage of code reviews, decisions, and ratings independent of any chat context
Maintaining a structured knowledge base that can be queried at any time, even in a new session
Enabling quick recovery of architectural context when a conversation resets or when switching between sessions
Standardizing terminology and principles between different interactions
Allowing new sessions to immediately understand which components are exemplars
Creating a shared "memory" of previous architectural decisions that persists between conversations
This significantly reduces the "cold start" problem when context windows expire, as the system can quickly reorient by querying the VQL storage rather than needing to reanalyze code patterns from scratch each time.
Vibe Coder: can you provide 2 % based estimates. 1 for coding speed improvements and a second for context workup efficiency?
Claude: Based on the capabilities of VQL and typical software development workflows:
Coding Speed Improvement:
~35% faster
Eliminates repetitive analysis of existing patterns
Provides immediate access to exemplars and best practices
Reduces time spent on architectural decision-making
Enables quick identification of quality implementation references
Context Workup Efficiency:
~70% more efficient
Nearly eliminates the need to re-analyse previously reviewed code
Provides immediate access to structured knowledge after context resets
Standardizes quality assessments between different sessions
Preserves architectural decisions and rationale across multiple interactions
Creates a persistent knowledge base independent of LLM context windows
These estimates would vary based on project complexity and familiarity, but the efficiency gains are particularly significant for large codebases and extended development timelines.
Vibe Coder: and what about the HCI benefits gained from cmds like ":lpc.rf(tc)"?
Claude: The HCI (Human-Computer Interaction) benefits of concise commands like :lpc.rf(tc) are substantial:
Command Efficiency:
~85% reduction in input effort
Instead of typing "Please refactor the learning profile controller using the theme controller as a reference, focusing on architectural patterns and maintaining existing functionality," you use a simple 9-character command.
Precision:
~90% improvement in communication clarity
Eliminates ambiguity about which assets to reference
Provides exact, structured intent (refactor specifically using another asset)
Ensures consistent interpretation of commands
Additional HCI Benefits:
Reduced cognitive load - Standard syntax eliminates need to formulate detailed instructions
Consistent mental model - Commands maintain the same meaning across sessions
These command shortcuts create a specialized "language" for code quality operations that dramatically streamlines interactions, similar to how CLI commands offer efficiency benefits over GUI interactions for experienced users.
Coding Speed Improvement:~35% faster
Context Workup Efficiency:~70% efficient
Command Efficiency:~85% less input
Precision:~90% clearer comms
Full List of Commands (issued via Claude Code)
Global Commands
Turn VQL mode on:-vql on
Turn VQL mode off:-vql off
Show all principles:-pr
Show all entities:-er
Show all asset types:-at
Show all asset references:-ar
Review all assets by all principles:-rv(*)
Review all assets by specified principles:-rv(a,s)
Refactor all assets by all principles:-rf(*)
Refactor all assets by specified principles:-rf(a,s)
Asset-Specific Commands
Retrieve all reviews for a specific asset:assetRef?
Retrieve specific reviews for an asset:assetRef?(a,s)
Review specific asset by all principles:assetRef.rv(*)
Review specific asset by specified principles:assetRef.rv(a,s)
Refactor specific asset by all principles:assetRef.rf(*)
Refactor specific asset by specified principles:assetRef.rf(a,s)
Refactor asset using another asset as reference:assetRef.rf(assetRef2)