VibeVM
Ctrl K
Contents
On this page
en
Publisher
org.vibevm.core
Version
1.0.0latest
Audiences
user
Reading time
3 min
Rendered
Read aloud
never

.md.xmlllms.txt

Create your first project

01A project is a folder your agent works in. This page creates one, adds the first shared rule set to it, and shows what appeared on disk and why the agent will now read it. Ten minutes, no prior knowledge.

02 
Create a VibeVM project named hello-vibe in the current folder, install the package org.vibevm.world/wal into it from the default registry, and show me the reading list the agent gets at session start.

the vibevm skill installed for your agent; network access to github.com/vibespecs, or the package already in the machine store

a folder hello-vibe with vibe.toml, vibe.lock, a vibevm/ directory, and CLAUDE.md, AGENTS.md and GEMINI.md ending with a <vibevm> block; vibe check reports no errors

  • test -f hello-vibe/vibe.toml
  • test -f hello-vibe/vibe.lock
  • grep -q "org.vibevm.world/wal" hello-vibe/vibe.lock
  • vibe check --path hello-vibe --quiet

What happens

03The agent runs vibe init hello-vibe, which creates the folder with a manifest, an empty lock file, the two boot files that are yours to edit, and the three agent instruction files. It then runs vibe install org.vibevm.world/wal --path hello-vibe. vibe reads the manifest's registries, finds the package, resolves a version, fetches it into the machine store, and shows a plan. On confirmation it copies the package into hello-vibe/vibevm/vibedeps/, writes the lock file, and generates the boot files the agent will read. Finally the agent runs vibe tree to show that reading list and vibe check to confirm the project is consistent.

04 Decision. For every entry-point node, vibe install generates two artifacts under the node's vibevm/vibespecs/boot/:

By hand

051. Create the project. The name becomes the folder:

06 
vibe init hello-vibe
Initializing project `hello-vibe` in `hello-vibe`
  ✓ created  vibevm/vibespecs/boot/00-core.md
  ✓ created  vibevm/vibespecs/boot/90-user.md
  ✓ created  vibe.toml
  ✓ created  vibe.lock
  ✓ created  .vibe/.gitignore
  ✓ created  .gitignore
  ✓ created  vibevm/vibespecs/boot/INDEX.md
  ✓ created  CLAUDE.md
  ✓ created  AGENTS.md
  ✓ created  GEMINI.md

Done. Project `hello-vibe`: 10 files created, 0 kept.

Next:
  • edit vibevm/vibespecs/boot/00-core.md and vibevm/vibespecs/common as your project takes shape
  • install packages with `vibe install <kind>:<name>` (e.g. flow:wal)

072. Install a package. The install shows a plan and asks for confirmation; --assume-yes skips the question in a script:

08 
vibe install org.vibevm.world/wal --path hello-vibe --assume-yes
Resolving 1 root package…

Materialising 1 package into vibedeps/:
  org.vibevm.world/wal@1.0.0

closure diff:
  → + org.vibevm.world/wal@1.0.0 (root-edge)
  → lane vibevm/vibespecs/boot/INDEX.md: 737 -> 854 B

Materialised 1 package into vibedeps/; regenerated boot artifacts for 1 node(s).

093. Look at what is recorded:

10 
vibe list --path hello-vibe
KIND  NAME  VERSION  ROLE     BOOT SNIPPET
flow  wal  1.0.0    package  —

1 package installed.

114. Look at the reading list the agent gets:

12 
vibe tree --plain --path hello-vibe
project: <TMP>/work/hello-vibe
STATIC.md: (none)
packages: 1   roots: 1
columns: load  T=transitive  C=condition  S=in STATIC.md

org.vibevm.world/wal  dynamic  .  .  .

135. Check the project:

14 
vibe check --path hello-vibe
vibe check: clean — every check passed against `<TMP>/work/hello-vibe`

What appeared on disk

15Open hello-vibe/vibe.toml: it names the project and, after the install, lists org.vibevm.world/wal under its requirements with a version range. Open hello-vibe/vibe.lock: it pins the exact version and the content fingerprint. Under hello-vibe/vibevm/vibedeps/ sits the package's published tree, unchanged. Under hello-vibe/vibevm/vibespecs/boot/ sit your two boot files and the generated INDEX.md; a generated STATIC.md appears beside it as soon as a package asks to be read first and in full, which wal does not. And at the end of CLAUDE.md, AGENTS.md and GEMINI.md stands the block that points an agent at them.

16 Decision. vibe owns exactly one managed block inside each agent instruction file — a contiguous region bounded by an opening and a closing marker.

17Open a new agent session in hello-vibe and ask it what rules it follows: it will name the package you installed a moment ago, because it read the lane before answering.

Edge cases and rules

18A repeated vibe install with no package names installs whatever the manifest requires; that is the command after cloning an existing project.

19If the folder already has a CLAUDE.md, vibe appends its block at the end and leaves your text alone. If it finds two blocks or a broken one, it stops with an error and changes nothing until you fix the file.

20 Malformed (§2.2) — vibe aborts the whole operation with an error naming the file and the exact defect, and changes nothing. It does not proceed until the user repairs the file by hand. vibevm never guesses which of two blocks is canonical and never auto-deletes a stray marker — a malformed managed block is always a human's call.

21Declining the install plan is not an error: nothing is written, and the store keeps what was fetched for next time.

For an agent

This page has a machine mirror. The citation carries the version rather than latest, so what an agent quotes does not move under it.

spec://org.vibevm.core/vibevm-docs@1.0.0/start/first-project

.md.xmlllms.txt