Create your first project

A 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.

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

The agent runs `vibe init hello-vibe`, which creates the folder with a [manifest](../glossary/index.xml#manifest), an empty [lock file](../glossary/index.xml#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](../glossary/index.xml#registry), finds the package, resolves a version, fetches it into the machine [store](../glossary/index.xml#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.

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

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)

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

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).

3. Look at what is recorded:

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

4. Look at the reading list the agent gets:

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 . . .

5. Check the project:

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

Open `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](../glossary/index.xml#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.

Open a new [agent session](../glossary/index.xml#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.

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

If 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.

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