GETTING STARTED

From nothing to your first diagram

vibeX is a Claude Code / Codex skill with a CLI underneath. You install the skill once and ask for things in English; the CLI is what it runs, and it is printed at every step here so nothing is hidden from you. About ten minutes, most of it reading.

STEP 1

Install the skill

One command installs it for Claude Code and Codex. Claude Code can also take it as a plugin. Pick the tab that matches what you want.

Installs for your user, so every project on the machine sees it. Run it from anywhere.

$ npx skills add Raja0sama/vibex -g -a claude-code -a codex -y

Where it goes. The skill lands in ~/.agents/skills/vibex, which Codex reads, with a symlink at ~/.claude/skills/vibex for Claude Code. Using another agent? Swap the -a values, or drop them and pick from the list.

STEP 2

Check it landed

Before asking for anything, confirm the skill is where your agent looks for it.

$ ls ~/.agents/skills/vibex
SKILL.md bin renderers schemas examples ...
 
# and the CLI underneath it runs
$ node ~/.agents/skills/vibex/bin/vibex.mjs types
erd schemas/erd.schema.json
c4 schemas/c4.schema.json
endpoints schemas/endpoints.schema.json
lifecycle schemas/lifecycle.schema.json
sequence schemas/sequence.schema.json

Nothing listed? The installer probably ran without -g and wrote into the project you were in. Re-run step 1 with -g. Installed as a Claude Code plugin? Run /plugin instead: vibex@vibex should be enabled.

STEP 3

Your first diagram

Open your project in Claude Code or Codex and ask. Pick the tab for whatever your project already has — vibeX reads the thing that cannot lie in preference to the code around it.

> show me the data model
wrote db.erd.json · db.erd.html
 
# what the skill ran for you
$ vibex import prisma prisma/schema.prisma docs/db.erd.json
$ vibex render docs/db.erd.json --open

Every table, column, key and relationship comes from the schema, so the diagram cannot disagree with the database it describes.

STEP 4

Put them in one page

Once you have more than one spec, a dashboard collects them: a sidebar of every diagram, an overview, and cross-links so clicking an entity jumps to the endpoints that touch it.

$ vibex dashboard docs/index.html docs \
--title "Payments platform"
docs/index.html

Several repos side by side? Run vibex workspace from the folder above them for one site with a dashboard per repo, and --host to serve it behind a login. How the workspace works →

STEP 5

Documentation that fails CI

This is the part worth the effort. You write prose about the system; every factual sentence is pinned to a region of real code by content hash. When somebody moves that code, the claim stops matching and the build goes red.

> document Relay and fail CI when it drifts
wrote relay.docs.json · 153 claims, 150 verified
 
# the check, which is what you put in CI
$ vibex docs relay.docs.json . --repo . --check
153 claims — 150 verified, 3 asserted, 0 stale, 0 broken, 0 expired

What it does not do. It catches documentation going stale. It does not catch documentation that was wrong on day one — if the first draft misread the code, the hash still matches and CI stays green. Reading the draft once is the only thing that makes it true to begin with.

STEP 6

Keep the generated files honest

A generated file records which build produced it. When vibeX changes underneath — a new feature, or a fix to the viewer — the files you generated earlier are no longer what this version would render.

$ vibex outdated docs
docs/db.erd.html stale built by vibex 0.4.0
docs/api.html current
1 of 2 out of date. Regenerate them.

It exits non-zero when anything is stale, so CI can gate on it. A stale file and a broken feature look identical to whoever opens one — this is how you tell them apart.

HELP

When it does not work

Four things account for nearly every report.

The agent does not offer the skill, or says it cannot find it. Almost always the installer ran without -g, inside some project.

$ ls ~/.agents/skills/ ~/.claude/skills/
# no vibex? install for your user
$ npx skills add Raja0sama/vibex -g -a claude-code -a codex -y

Then restart the agent so it re-reads the skills folder.

NEXT

Where to go from here

The live demo

A whole parcel network, documented end to end — every diagram type and a fact graph.

Open it →

The spec formats

Four JSON schemas with examples. Write them by hand when you want exact control.

Read the README →

Ask for something

Missing an import format or a diagram type? The intake queue answers either way.

Open an issue →