GETTING STARTED
From nothing to your first diagram
vibeX is a Claude Code / Cursor 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.
Install the skill
skills add installs relative to the directory you run it in. That one detail is what people get wrong, so pick the tab that matches what you want.
Run it from your home directory and the skill is available in every project on the machine. This is what most people want.
Why home? The installer writes ~/.agents/skills/vibex and symlinks it into ~/.claude/skills/. Run the same command inside a project and it writes into that project instead, which is why the skill sometimes seems to disappear.
Run it in a repository and the skill is checked in beside the code it documents, so everyone who clones gets the same version.
It lands in .agents/skills/vibex with a symlink at .claude/skills/vibex. Commit both, or add them to .gitignore and let each person install their own — but decide, because half-committed skill folders confuse everybody.
Prefer a published release over a clone of main? SKILL.md ships inside the npm package, so a global install plus one symlink does it — and you get the vibex command on your PATH.
Under nvm this breaks silently. npm root -g is scoped to the Node version you are on, so installing a new Node leaves both the vibex command and that symlink pointing at nothing. Re-run both lines after a Node upgrade, or use the first tab instead.
If you are changing vibeX itself. The symlink tracks your working copy, so edits apply the moment you save.
Run npm test before you trust a local change — the suite needs no network and takes under a second.
Check it landed
Before asking for anything, confirm the skill is where your agent looks for it.
Nothing listed? You almost certainly ran the installer somewhere other than your home directory. Check the project you were in, or re-run step 1 from ~.
Your first diagram
Open your project in Claude Code or Cursor 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.
Every table, column, key and relationship comes from the schema, so the diagram cannot disagree with the database it describes.
A YAML document needs the optional yaml package. If the import fails, run npm install inside the skill folder, or convert the document to JSON.
Queries, mutations and subscriptions become groups; the object types become the catalogue behind them.
No schema file is not a blocker. The skill reads the source — NestJS controllers and resolvers, TypeORM or Prisma entities, Express routers, SQL migrations — and writes the spec itself.
Read this one before you trust it. A spec written from source is the agent's reading of your code, not a mechanical translation of a schema. It is a first draft to check, which is exactly what step 5 is about.
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.
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.
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.
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.
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.
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 in the wrong directory.
Then restart the agent so it re-reads the skills folder.
YAML OpenAPI needs the optional yaml package, which a skills add install does not bring — it clones the repository rather than the npm package, so there is no node_modules.
Or convert the document to JSON, which needs nothing installed at all.
vibex: command not found means the global npm install is not on your PATH — most often because you changed Node versions since installing.
That path contains the Node version. Install a new Node and the command is gone. Re-run npm i -g @vibex/vibex, or run the CLI through the skill folder, which does not care: node ~/.claude/skills/vibex/bin/vibex.mjs.
The unscoped vibex on npm is an unrelated package by another author. Installing it gets you something that is not this.
The scope is the whole difference. Check with npm ls -g --depth=0.
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 →