VibeVM Manual

What it covers: what VibeVM is and how it gives a coding agent the right text to read; installing vibe; creating a project; packages, registries, the lock file and the machine store; installing, updating, publishing and working offline; giving an agent the vibevm skill and asking it to do the work; the lifecycle from validate to deploy; a full command, manifest, lock-file and settings reference; writing packages of every kind, including documentation and its translations. For whom: people who run vibe in their projects, people who write packages, and the agents that read on their behalf. What it assumes known: how to use a terminal and a text editor, what a coding agent is, and what a package manager does for a programming language. What it leaves out: the normative specifications themselves (this manual quotes them, never restates them), the internals of any one agent product, and the design history of vibe.

Что покрывает: что такое VibeVM и как он даёт агенту-кодеру нужный текст для чтения; установку vibe; создание проекта; пакеты, реестры, лок-файл и машинный store; установку, обновление, публикацию и работу без сети; навык vibevm для агента и работу через него; жизненный цикл от проверки до выкладки; полный справочник команд, манифеста, лок-файла и настроек; написание пакетов всех видов, включая документацию и её адаптации. Для кого: для тех, кто запускает vibe в своих проектах, для тех, кто пишет пакеты, и для агентов, которые читают за них. Что считает известным: как пользоваться терминалом и текстовым редактором, что такое агент-кодер и что делает менеджер пакетов для языка программирования. Чего не покрывает: сами нормативные спецификации (руководство их цитирует, а не пересказывает), внутреннее устройство отдельных агентов и историю проектирования vibe.

A coding agent starts every session knowing nothing about your project. VibeVM fixes that the way a package manager fixes missing libraries: you name what your project follows, and the agent gets the exact text to read at the start of each session. The text comes from packages, so a team, a company or a community can share it and improve it in one place.

You have a coding agent and a project. VibeVM gives that agent the right text to read before it starts working, and keeps that text in step with what your team decided. This page walks you from an empty folder to a project your agent understands, one short step at a time.

vibe is one program with no runtime to install. On Windows you download an archive and unpack it; on any platform with a Rust toolchain you build it from the source. When it is done, one command prints the version.

This page takes you from an empty folder to the first description of a program, written before the program exists. The program is Hello VibeVM, a small calculator for the command line. You give the folder a published set of working rules and look at what arrived. Then you describe the calculator, by hand or by asking your coding agent. Plan for about an hour, most of it the agent's; you install nothing but vibe and an agent.

After the first install, a project holds a handful of files you wrote and a larger set that vibe wrote for you. This page names each of them and says who is allowed to change it, so nothing you edit gets overwritten and nothing vibe generates gets edited by hand.

This page turns the calculator from [Create your first project](../start/first-project.xml) into a Rust program. It also ties each of the calculator's written rules to the code that keeps it and to the test that proves it. The tie comes from AI-Native Rust, a discipline you add to the project the way you added the redbook. The code stays ordinary Rust. The strictness moves around it: into types, into errors that name the rule they enforce, and into checks a machine runs. Plan for about an hour; the agent's part takes under ten minutes.

Many people keep what they teach their coding agent in one folder of Markdown notes, often an Obsidian vault. It holds rules for commits and reviews, notes on what a project must do, prompts that worked, a daily log. This page turns such a folder into a VibeVM project one step at a time, and Obsidian keeps working throughout. At the end, the part worth sharing is a package that your other projects, your other computer and your colleagues install with one command. Plan for about an hour.

This page takes a package you write in Markdown and shows you the XML your agent reads in its place. On the way you learn why VibeVM turns every text into XML, and why that costs an author nothing. You learn how to name a rule so that a machine can point at it. And you learn to split a long text into a short header and a long body, the way C and C++ programmers split a library. You build one small package by hand, watch it compile, and prove that the two forms are one. Plan for about half an hour, with no agent required.

A project keeps two kinds of text apart: the rules your team wrote, and the copies of shared rules that arrived with the packages you installed. Installing a package never edits your own text. Removing one never leaves a trace in it.

When an agent starts, it reads a short ordered list of files that vibe computed from everything the project depends on. The list has a fixed first file, read in full, and a list of the rest. Some entries are read always, some only when a condition holds, and nothing in the list is written by hand.

Everything vibe installs is a package: a folder with a small description file and the text or tools it delivers. Packages come in eight kinds, and the kind tells you what a package is for before you open it: a way of working, a feature, a technology, a tool, a language guide, an agent server, documentation, or an application.

Packages are published to a place vibe knows how to read: by default a public organisation on GitHub, one repository per package. A project lists such places in the order it trusts them. A catalogue beside each one answers searches without cloning anything.

You found a package your project should follow. This page adds it to the project, records the exact version, and shows how to check that your agent will now read it.

One file in your project records exactly which package versions it got, down to a checksum of their content, so a teammate installs the same bytes. One folder on your machine keeps those bytes once per computer, so a second project or an offline day costs nothing extra.

A version is a promise about behaviour, not a snapshot of files. Your project asks for a range, vibe records the one number it chose, and an update moves that number on purpose. vibe itself follows the same rule: one number stands for one contract, however often the binary behind it is rebuilt.

Packages change. This page shows which of yours have a newer version, moves one or all of them forward, and explains what vibe records during the move.

Removing a package takes its text out of the project and out of the agent's reading list, and leaves everything you wrote untouched.

On a plane or behind a firewall, vibe keeps working from what the machine already holds. This page fetches what you will need before you leave and installs from it without a network.

A company can keep its packages in its own place and still use vibe unchanged. This page points a project or a whole machine at that place, with or without a search catalogue beside it, and keeps the public one as a fallback.

Your agent works better when it knows what vibe is and how to call it. This page puts a short instruction file where the agent reads it, and, for agents that support it, starts a server the agent can query directly.

Every page in this manual that describes a task starts with the plain request you type to your agent. This page explains what those requests assume, how the agent proves the work is done, and what happens when vibe hands a job back to the agent instead of doing it itself.

Documentation of the packages you use, including private ones, can be read on your own machine with nothing sent anywhere. This page fetches the manual onto your machine and opens the reader in a browser.

This manual is published for machines as much as for people. An agent can fetch any page as plain text, ask where a rule lives, and load the whole corpus in one file sized to its budget.

Building software has a fixed order of steps, and vibe names them: check the tree, produce generated sources, build, test, let an agent create what only an agent can, verify, assemble, deploy. Each step runs only when something it depends on changed.

This page takes a project from source to a running deployment with three commands, shows what each leaves on disk, and how to take a deployment down again without guessing what it owned.

A package can plug into the build: run a step, transform a stage, or hand a task to an agent. This page explains how such plug-ins are declared, how a project turns them on, and how to see which ones ran and why.

When a project is finished and must leave without a trace of the tool that helped build it, one operation removes every vibe file and reference while keeping the product and its build intact.

A flow tells an agent how a team works: how to commit, what to check before pushing, how to keep notes between sessions. This page writes one from scratch, including the short text the agent reads at every session start.

The text in a package is only useful to an agent if every rule in it has an address. This page shows the shape of such text: named sections, one idea per unit, a status on each, and an address that never changes once published.

A spec is a list of promises, and each promise has a state: proposed, being built, done, abandoned. vibe reads that state from a small marker written next to the promise, in Markdown or in the XML form, and one command tells you when a marker is malformed or in the wrong place. This page is the grammar of those markers.

A feat says what to build without saying how; a stack says how a technology does it. This page writes one of each and connects them through the abilities one needs and the other provides.

A lang package teaches an agent how to write in a language or a notation: the idioms, the constraints, the shape of a good file. This page writes one and explains how vibe recognises it as a language discipline.

A package can deliver programs: command-line tools built on install, or a server your agent talks to. This page declares both, builds them in the package's own folder, and explains why a server pins the exact version of the tools it serves.

A package you depend on has dependencies of its own, and those can reach your project too. Whether they do is decided where each dependency is declared, one line at a time: everyone gets it, nobody gets it, or only the projects that have named the declaring package a friend. This page explains the three marks, the friendship that opens the middle one, what ends up in your tree as a result, and how to ask vibe why a package is there or missing.

Some text you want your agent to read lives in a repository whose author has never heard of vibe. A bridge package makes it installable anyway: you steward someone else's repository and publish an ordinary package that wraps it, with the original's authorship and licence kept apart from yours.

Several packages developed together can live in one repository and share one record of the versions they use. This page turns a folder into such a workspace and shows how members refer to each other by path.

Every VibeVM project can install packages from two public places: the organisation `vibespecs` on GitHub and the organisation of the same name on GitVerse. Only their administrators can add a package there, so to publish yours, you ask them. This page shows how to ask, and what can keep a package out.

You wrote a package and want others to install it. This page publishes it, as a repository of its own, to a place where you have full access, such as your own private repositories or your organisation's. It tags the version and checks that a fresh project can install it. Ordinary users have no power over the organisations `vibespecs` on GitHub and GitVerse, the central place every project installs from; to publish there, [ask for a place](publish-to-the-central-registry.xml) first.

A manual for a package is itself a package: it names what it documents, carries a title and a summary, and is read rather than installed. This page writes one, with examples that are run and rules quoted from the source they come from.

A translation is a separate package in the same shape as the original: same pages, same section names, same examples by reference, in another language. This page creates one and explains what makes it official.

This manual is a package, and it drifts like any code the day after it ships: the product adds a flag, a reader asks a question no page answers, a paragraph patched five times stops reading well. Nothing stops that on its own, so the manual is kept by a small set of loops with named triggers, a queue that measures the gaps, and a journal that records what each loop found. This page says what the loops are, what runs them, and what you owe when you change the product.

vibe is one binary built from a set of Rust libraries, each owning one concern: reading the description of a project, choosing versions, fetching from where packages are published, writing the tree on disk, talking to agents. This page maps the libraries, the seams between them, and the path an install takes through them.

Every public piece of code in vibe points at the rule it implements, and a generated map lets you ask in either direction: which code implements this rule, which rule does this code answer to.

Between July and September 2026 vibe grew from a package installer into a build system with an extension machine, a native ABI, a record of every deployment and a terminal export. This page tells that route as one system, what was decided on the way, and what was left for later.

Every command vibe accepts, with its options, in the words the program itself prints. Nothing on this page is written by hand.

`vibe.toml` is the one file you write to describe a project or a package: its name, what it depends on, where packages come from, and what it delivers. This page lists every table and field with its meaning.

`vibe.lock` is the file vibe writes and you commit: the exact versions the project got. This page explains every field so you can read a diff of it in a pull request and know what changed.

`vibe tree` draws the packages a project resolved as a tree, says for each one how its text reaches the agent, and explains why. On a terminal it opens an interactive screen; in a script it prints a plain tree or JSON. This page is that command, its screen, and the way an agent can look at the screen without a terminal.

vibe keeps its own files in one folder in your home directory and reads a few environment variables. This page lists the folder's contents, every variable, and which wins when they disagree.

Every command can answer in JSON for scripts and agents. This page lists the documents, their schemas and the envelope fields that every document carries.

vibe's error messages name the rule they enforce. This page lists the messages you are likely to meet, what each means, and the shortest way out, in the order they tend to appear.

Real questions people asked, each answered in a few sentences with a link to the page that explains the mechanism.

This page says which law governs dealings with the VibeVM project, such as publishing a package for everyone to install, and how the project treats personal data. Read it before you publish, and before you use VibeVM in work bound by strict rules on data protection.

One definition per term, and the only place a term is defined. Every other page links here the first time it uses a word from this list.