# Remove a package {#root}

@status:doc/work @audience:user

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

[p02]
```prompt
Remove the package org.vibevm.world/wal from the VibeVM project in the current folder and confirm that nothing of it remains in the reading list.
```

- needs: the vibevm skill installed for your agent; a project in which the package is installed

outcome: the requirement is gone from `vibe.toml`, the entry is gone from `vibe.lock`, the package's folder is gone from `vibevm/vibedeps/`, and `vibe tree` no longer lists its snippet; `vibe check` reports no errors

- assert: `test ! -e vibevm/vibedeps/org.vibevm.world.wal`
- assert: `vibe check --quiet`

## What happens {#what-happens}

[p03] The agent runs `vibe uninstall org.vibevm.world/wal`. vibe shows what will leave: the requirement line in the [manifest](../glossary/index.xml#manifest), the lock entry, the package's folder in the dependency tree, and any dependency that only this package needed. On confirmation it removes them and regenerates the boot files, so the next [agent session](../glossary/index.xml#agent-session) no longer reads the package's snippet. Your own files, including the two boot files you own and anything in `vibevm/vibespecs/`, are never touched.

> [p04] Authored `spec/` — written only by the node's author. Unchanged definition.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-009#TREE-AUTHORED>

## By hand {#by-hand}

[p05] 1. Remove by [coordinate](../glossary/index.xml#coordinate); the version is not needed:

[p06]
```sh
vibe uninstall org.vibevm.world/wal --path hello-vibe --assume-yes
```

```output

Uninstall org.vibevm.world/wal@1.0.0 — remove `vibevm/vibedeps/org.vibevm.world.wal/1.0.0` and regenerate boot.
  - removed  vibevm/vibedeps/org.vibevm.world.wal/1.0.0

Uninstalled org.vibevm.world/wal@1.0.0 — removed its vibedeps/ slot, regenerated boot.
```

[p07] 2. Check the reading list:

[p08]
```sh
vibe tree --plain --path hello-vibe
```

```output
project: <TMP>/work/hello-vibe
STATIC.md: (none)
packages: 0   roots: 0
columns: load  T=transitive  C=condition  S=in STATIC.md
```

## Removing derived state without removing packages {#derived-state}

[p09] Sometimes you want a clean slate rather than a smaller graph: before a build, after a tool upgrade, or to prove the tree can be rebuilt. `vibe clean` deletes the dependency tree and the generated boot files and keeps the manifest, the [lock file](../glossary/index.xml#lock-file), everything you wrote and the machine [store](../glossary/index.xml#store). `vibe clean install` chains the two steps.

> [p10] **`vibe clean` removes exactly the derived prompt state** of the workspace it runs in: (a) the dependency world — the whole `vibevm/vibedeps/` root of the workspace; (b) the generated boot artifacts — `vibevm/vibespecs/boot/STATIC.*`, `INDEX.md` and `INLINE.*`, each carrying the generated-by-vibe marker. That is the mvn-clean analogue: what an install writes, clean deletes.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-053#CLEAN-REMOVES-DERIVED>

[p11] The command refuses to run outside a project, so it cannot sweep an unrelated folder by mistake.

> [p12] Clean refuses to run outside a vibe project (no `vibe.toml` at or above the cwd) — a guard against sweeping an unrelated directory.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-053#CLEAN-NEEDS-A-PROJECT>

## Edge cases and rules {#edge-cases}

[p13] Uninstalling a package that another installed package requires leaves the shared dependency in place; only packages nothing else needs are removed.

[p14] The machine store keeps the package's bytes after an uninstall. Reinstalling it later costs no network; `vibe cache clean --package` reclaims the space if you want it gone from the machine.

> [p15] The cache is **accretive**: a package version, once cached, is never evicted automatically.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-registry/PROP-010#CACHE-ACCRETIVE>

[p16] Removing a package does not undo what its install script did, if it had one: [hook](../glossary/index.xml#hook) effects are not tracked, by design.

> [p17] Only a hook's edits
>   to materialiser-owned recorded payload are ephemeral: reinstall, update or
>   integrity repair restores those bytes per
>   [PROP-022](PROP-022-materialization-modes.xml), then reruns hooks exactly
>   when that payload diff is nonempty. Hook-created unrecorded state is outside
>   `.vibe-slot.toml` ownership and survives by design; a rerun may compound it,
>   so hooks must be idempotent until a separate hook-output ownership contract
>   exists.
>
> <spec://org.vibevm.core/vibevm/modules/vibe-workspace/PROP-020#EFFECTS-EPHEMERAL>