vibex

vibeX

Your architecture diagram is a lie.

vibeX reads the thing that can't lie — your Prisma schema, your OpenAPI document, your GraphQL SDL, or the source itself — and renders the diagram that's actually true. Then it documents the system in claims that fail CI when the code moves underneath them.

One standalone HTML file. No server. Nothing leaves your network.

---

The diagram you have right now

• a whiteboard photo in a Slack thread
• a Confluence page last touched in 2023
• a Miro board nobody can find
• a Mermaid block that stopped rendering
• the one guy who knows

→ one command, run against the schema that actually ships.

npx skills add Raja0sama/vibex -g -a claude-code -a codex -y   # Claude Code + Codex, then just ask
npx @vibex/vibex demo out                                      # or look first: installs nothing

Watch the demo

Why "vibeX"

vibe — how code gets written now. Fast, AI-assisted, more of it than anyone can hold in their head. X — the crossings. Which table joins which. Which service calls which. What happens after approval.

You vibed it into existence. vibeX shows you what you actually built.

The mark is the same idea: two edges crossing. Everything interesting in a system is a line between two things, not the things themselves.

Five diagrams. One source of truth.

Each is a validated JSON spec plus a rendered viewer. The spec is the artifact you keep; the HTML is disposable. Documentation and changes are two more views over the same specs, all in one dashboard file. Every diagram also exports as Mermaid (vibex mermaid <spec>, or the button in the viewer) for Markdown that renders it.

Which service calls which. A *.links.json records each call once, anchored on both ends. vibex links checks it against the code:

vibex links system.links.json docs --repo bff=../bff --repo orders=../orders --check

It fails when a client or handler moved, an endpoint it names is gone, or a C4 arrow has no call behind it. It also lists endpoints nothing calls. In a monorepo, pass --repo ..

Three commands. No config file.

# 1. import — your schema becomes a draft spec
vibex import prisma  prisma/schema.prisma  docs/db.erd.json
vibex import openapi openapi.yaml          docs/api.endpoints.json
vibex import graphql schema.graphql        docs/api.endpoints.json

# 2. validate — dangling refs and unreachable states are errors that name the field
vibex validate docs/db.erd.json

# 3. render — one file, CSS and JS inlined, spec embedded
vibex render docs/db.erd.json --open
#    or --linked: the HTML is only a placeholder; data goes in db.erd.data.js
#    and the viewer in vibex-viewer.js/.css beside it (still opens from disk)

# every spec in the folder, one page, cross-linked
vibex dashboard docs/index.html docs --title "Payments platform" --repo .

No source schema? It reads the code — NestJS controllers, GraphQL resolvers, TypeORM entities, Express routers, SQL migrations — and writes the spec itself.

Install it as a skill and stop learning flags

vibeX is a Claude Code / Codex skill first and a CLI second. Installed as a skill, the whole command surface collapses into a sentence — the agent reads SKILL.md, finds your schema, picks the diagram type, writes the spec and renders it:

> show me the data model
  wrote db.erd.json · db.erd.html

> now the endpoints
  wrote api.endpoints.json · api.endpoints.html

> what happens after a request is approved?
  wrote request.lifecycle.json · request.lifecycle.html

> document the auth service and fail CI when it drifts
  wrote auth.docs.json · 41 claims, 38 verified

Install it. Pick your agent:

Then:

1. Restart the agent (or open a new session).
2. Ask: "show me the data model".

-g installs for your user, so every project sees it. Codex reads ~/.agents/skills; Claude Code gets a symlink in ~/.claude/skills. The plugin route updates through /plugin instead.

Check it landed:

node ~/.agents/skills/vibex/bin/vibex.mjs types

Per project, so the skill is checked in beside the code it documents. Drop -g and run it inside the repo:

cd my-project && npx skills add Raja0sama/vibex -a claude-code -a codex -y

Another agent (Cursor, Gemini CLI, OpenCode, Copilot and more): swap the -a values, or run npx skills add Raja0sama/vibex and pick from the list.

Pinned to a published version. SKILL.md ships inside the npm package, so a global install plus one symlink does it:

npm i -g @vibex/vibex
ln -s "$(npm root -g)/@vibex/vibex" ~/.claude/skills/vibex   # or ~/.agents/skills/vibex for Codex

Under nvm, npm root -g is scoped to the Node version you are on. Install a new Node and both the vibex binary and this symlink stop resolving, silently. skills add has no such problem.

From source, if you are changing vibeX itself. The symlink tracks your working copy, so edits apply the moment you save:

git clone https://github.com/Raja0sama/vibex && cd vibex
ln -s "$(pwd)" ~/.claude/skills/vibex

skills add and the plugin clone the repository, not the npm package, so they have no node_modules. Run npm install inside the skill folder only if you need YAML OpenAPI. The npm paths already have it.

---

Prose that can't quietly go stale

An AI wrote the sentence once. Arithmetic checks it forever.

A diagram can't drift from the schema, because it's generated from it. Prose can, and always does. So vibex docs documents a system the same way it draws one — the unit isn't a page, it's a claim: one sentence with a source attached.

vibex docs system.docs.json specs/ --repo . --check   # exit 1 on any claim that no longer holds

There is no model in the verification path — only fs, path, crypto and git. That is the whole point, and it is why a full drift check costs ~70ms and nothing per