# @vodmal/vdx-cli — vdx evaluator + MCP server

Native predicate evaluator for `vdx-rubric-vodmal` + MCP stdio server for the
Claude Code `vdx` plugin. Decision basis: [docs/decisions.md](../docs/decisions.md)
D10 (native evaluator, not OPA).

Published on npm as **[@vodmal/vdx-cli](https://www.npmjs.com/package/@vodmal/vdx-cli)**.

## Install

Two equally supported paths:

```bash
# A. Daily-use install — recommended when you run `vdx <verb>` many times per session
npm install -g @vodmal/vdx-cli
vdx audit /path/to/project

# B. Zero-install via npx — recommended for CI runners, one-shot trial, or fresh envs
npx -y -p @vodmal/vdx-cli vdx audit /path/to/project
```

Same binary, same behavior. `npx` adds ~200–500 ms resolve overhead per
invocation; pick global when you'll run `vdx` repeatedly, npx when you
don't want anything in your global `node_modules` or you're in an
ephemeral environment.

**First command after install: `vdx doctor`** — it inspects your environment
(Node version, `vdx` on PATH, git, mise, npm auth, container runtime, Claude
Code plugin; in a project — whether its git hooks are on in this clone, and the
commit author; with a profile — whether your personal hooks run on this machine)
and points to remedies for everything that's missing or sub-optimal.

## Use

```bash
# Lifecycle verbs (pass-through to `mise run <verb>`; requires mise + mise.toml)
vdx up | down | build | test | check | fix

# Maturity audit against the owner baseline rubric
vdx audit [project-path] [--format=ansi|markdown|json] [--rubric <path>] [--stack <id>]   # default: cwd

# Generate mise.toml for a project (no AGENTS.md — vdx-discover skill covers Claude Code; pick your own format for other agents)
vdx init  [project-path] [--baseline github.com/org/repo@vX.Y] [--stack <id>] [--dry-run] [--force]   # default: cwd

# Publish a library (Node MVP; PHP/Python coming in Y.3)
vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]

# Push the branch; one that requires checks on GitHub takes the commit once they pass
vdx push [project-path] [--dry-run]   # default: cwd

# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project; the GitHub token vdx asks with)
vdx doctor [project-path] [--format=ansi|markdown|json]   # default: cwd
vdx doctor --staged                 # pre-commit guard: Claude Code memory goes into a commit only where nobody but
                                    # you reads every place it reaches (origin, mirrors; GitHub asked with gh's token)
vdx doctor --check [project-path]   # one line per hook declared but not running here, and one when the memory is
                                    # not inside — the plugin's SessionStart hook tells the agent
vdx doctor --fix [project-path]     # write the profile's personal hooks (git.hooks) into ~/.gitconfig, and put
                                    # the project's Claude Code memory inside it: .claude/memory/ (after a
                                    # folder move, its path and conversations follow; notes a session that
                                    # started before the move wrote at the old place come in)

# Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
vdx ai[@host] [project-path] [--new | --conversation <id>] [--focused [<topic>] | --intercom | --hq] [--restart] [--detach] [-y | --yes | --no-input] [--dry-run | --list]   # default: cwd; @host: over ssh, in tmux there; --intercom: the project's intercom session; --yes: vdx answers every question, --no-input: none is put (agents)
vdx ai --restore [--dry-run]   # whatever fell (tmux, cmux, the machine): every agent a fallen tmux server took down on this machine, back where it was (an intercom session — only one you started or attached to), then the profile's other machines, then the cmux tabs that lost their sessions (0.59); at login it waits for a volume not mounted yet — Claude Code's transcripts (`~/.claude/projects`) or a project on it — and a project that has not come keeps its record (0.62)
vdx ai --tab   # in a cmux tab's shell after cmux restarted: back into the session the tab showed (vdx ai notes it in ~/.local/state/vdx/cmux-tabs/ while it holds the attach); after a reboot it waits while a restore brings the session back (0.59); without a note, the tmux attach cmux noticed in the tab before it started; cmux's own "cmux restore --surface" is read off the terminal first, so it never reaches the agent (0.61)
vdx ai [project-path] --focused "<topic>"   # a focused session about <topic> (tmux option @vdx_topic), which opens with it as its first prompt; run by that session's agent: a new topic, nothing started
vdx ai [project-path] --focused "<topic>" --prompt "<what to do>"   # the same, its first message apart from the topic (0.60)
vdx ai --hq [project-path]   # the project's HQ session, for what comes from outside (VDX_HQ=1, tmux session <name>-hq, first prompt agent.hq_args): one per project and machine, you keep it running; --hq only narrows the choice: a plain start's list numbers it (0.52), Enter and a start without a terminal leave it; --restore brings it back; in a hand (echelon hq names another project its HQ) it asks to open that one's instead, without a terminal refuses with its line, exit 2 (0.66); the profile's agent.when[] rules with session: hq hold only here (0.67)
vdx ai --close [--waiting <n>]   # inside the intercom session or a focused one (0.56): it ends itself (one you started or attached to from a terminal stays); n questions to you still unanswered show on the project's other tmux sessions
vdx ai --check [project-path]   # this session against the profile and the installed Claude Code and plugins — what the plugin's SessionStart hook tells the agent
vdx ai --state [project-path] [--conversation <id>]   # the tmux option @vdx_state of this agent's session (empty | finished) for the cmux sidebar — the plugin's Stop hook; prints nothing

# Move projects into a folder on every machine of the profile (session.machines), with what Claude Code keeps by
# the folder's path: memory path, conversations, trust; idle sessions are closed and started again there.
# Within, into, out of or beside Syncthing: its folders pause while it moves; copies Syncthing would merge — one goes
vdx move <project-path>... <folder> [--dry-run]

# What a command does and takes; nothing runs (ai: also where launch flags live)
vdx <command> --help

# Print the installed version
vdx --version

# MCP stdio server consumed by the Claude Code plugin
vdx-mcp   --project <path>
```

**Three quick examples**

```bash
# 1. Score the project I'm standing in (no arg → cwd)
vdx audit

# 2. Wire native scripts into the 6 lifecycle verbs, then run one
vdx init --stack node
vdx test            # → mise run test (which calls `vitest run` or whatever was detected)

# 3. Ship a new minor release of a Node lib
vdx publish minor   # npm login if expired → bump package.json + lock → npm publish (OTP or browser) → commit + tag → push → wait for the registry
                    # in your own terminal: without one it releases nothing (--force goes on)

# 4. Start the agent here, continuing its last conversation (--new: a new one,
#    next to a running agent; another machine's conversation is continued on
#    that machine);
#    re-run to attach; an agent without the profile's flags is a question:
#    Enter attaches as is, r restarts it; --restart applies a changed profile
vdx ai

# 5. The same on another machine (an ssh host with vdx), attaching from here
vdx ai@m3
```

`vdx push` pushes the current branch to its upstream. When the upstream is on
GitHub and requires checks (branch protection or a ruleset), the commit goes to
`vdx-gate/<branch>` first; CI checks it there — its workflow has to run on
`vdx-gate/**` — and vdx waits for the checks, then pushes the same commit to the
branch with its annotated tags. A failed check leaves the branch as it was and
names the check. Without required checks, or off GitHub, it is a plain
`git push`. Its pushes through the checks carry `VDX_GATE_PUSH=1`, so a pre-push
hook that runs what CI runs can step aside. `vdx publish` sends its release
commit the same way, after `npm publish`, and then refuses local commits not
pushed yet: npm would get them before CI.

`vdx ai` reads a personal profile, never a bundled one: `$VDX_ENVIRONMENT`, else
`~/.vdx-environment.yaml`, else a plain `claude`/`codex` with no flags. Format:
[docs/specs/environment-format.md](../docs/specs/environment-format.md).
The session's `{project}` is `[_.vdx] name` (or the older `[vdx]`) from the project's `mise.toml`, else the
first file in the profile's `session.project_names` that has one, else the repo
name. `vdx ai@<host>` runs the same command on `<host>` over ssh — that machine's vdx,
profile and tmux, the path taken under its home directory, and a terminal that machine has no
entry for (cmux's `xterm-ghostty`) as `xterm-256color` (0.61); `--detach` only
starts it, and not in a folder Claude Code does not trust yet: nobody would answer
its trust window (exit 4; start once without `--detach`). The machine's own label (`$VDX_HOST`) runs here. Where git knows no
commit author, `vdx ai` proposes one (Enter writes it into `.git/config`).
For Claude Code `vdx ai` picks the conversation: each one is marked with the
machine it was last started on (`vdx ai --check`, run by the plugin's hook, writes
the label in), the running ones are asked of the other machines over ssh, and
another machine's conversation is continued there. Unless the choice is plain
(0.44+: one agent on all the machines that no terminal at your seat shows; or
none running and this machine's newest conversation not finished) it shows one
list of the agents on every machine and the conversations nobody runs, with
their state — each group under its title, its rows in columns (0.55+); Enter
never takes one your seat already shows; without a terminal, this machine's.
With `fzf` on PATH the list at a terminal has a cursor (0.55+): move over the
rows, type to filter them, read the row under the cursor in a panel, `ctrl-s`
searches what was said, `ctrl-y` prints the row's command; `VDX_PLAIN_LIST=1` keeps the numbered list and a typed
answer. `vdx ai --list` prints the list and starts nothing; in `~` (no project) the list holds every tmux session of the machines, `NOT OPEN HERE` first, and a session's row only attaches to it (`vdx ai --attach <session>`, 0.65). `vdx ai --find
"<phrase>"` (or `/<phrase>` at the list's question, 0.45+) lists the conversations
whose replies — yours and the agent's — have the phrase: a piece of a screen left
after tmux fell finds its conversation. After the tmux server fell (0.46+), a plain
start opens the list with what it took down, and Enter (`r`) brings those agents
back — each in its tmux session, conversation, mode and topic; `vdx ai --restore`
brings back every one on the machine without a question — from 0.59 with the other machines'
agents and the cmux tabs here that lost their sessions, and in a cmux tab `r` brings those tabs
back too (0.61: the row is `↩ bring back … and return N cmux tabs to their sessions: <names>`;
a tab counts as shown only by a terminal of this machine) — and `vdx ai --restore
--forget` (0.55+) drops them instead, naming each with whether work was in it;
agents of other projects that went down are one note under the list (0.55+); a
terminal `vdx ai` attached waits for its session and attaches again (0.47+). The plugin's
session-start hook keeps the record of each agent pane for it, in
`~/.local/state/vdx/`.

Every command takes `--help` (`-h`) and runs nothing with it. An unknown option,
a stray argument or a value flag without its value is refused with exit 2
before anything runs. In 0.16.0 and earlier the commands other than `vdx ai`
dropped such arguments, and `vdx init --help` wrote `mise.toml`.

By default the bundled `rubric/vdx-rubric.yaml` is used (a mirror of canonical
[vdx-rubric-vodmal](https://github.com/VoDmAl/vdx-rubric-vodmal) at the time of
each CLI release). Override via `--rubric <path>` or the env var `VDX_RUBRIC`.

`branch-protection` is the one axis the files cannot answer: `vdx audit` asks
the hosting of `origin` whether its default branch takes changes only after a
check required of everyone, admins included. GitHub: protection or a ruleset
nobody bypasses; a public repo needs no token, a private one takes it from
`GH_TOKEN`, `GITHUB_TOKEN` or `gh auth token`. GitLab (a host with `gitlab` in
its name, or one glab has a token for): nobody may push to the branch directly,
and a merge request needs a passing pipeline; the token is glab's for that
host, or `GITLAB_TOKEN` when the host is `GITLAB_HOST` (`gitlab.com` unless
set) — vdx never sends a token to a host it does not belong to. Bitbucket
Server (a host `BITBUCKET_HOST` names, one with `bitbucket` in its name, or one
git keeps an https login for — and that says it is Bitbucket): a restriction
lets nothing into the branch but a pull request and exempts nobody, and a pull
request needs a successful build ("Minimum successful builds"); the login is
the one git keeps for that host (`git credential fill`, never a prompt — log in
once with `git ls-remote https://<host>/scm/<project>/<repo>.git`, a personal
access token as the password), or `BITBUCKET_TOKEN` when the host is
`BITBUCKET_HOST`. Branch restrictions are visible to a repository admin only.
A login the server refuses (a revoked token) is unknown with the command that
erases it: vdx leaves git's store alone, and sends the login again each audit
until it is gone.
Not met comes with the reason; another hosting, no network or no token
where one is needed leave the axis unknown, with the reason too;
`VDX_OFFLINE=1` does not ask at all.

## Dev

```bash
git clone https://github.com/VoDmAl/vdx
cd vdx/cli
npm install
npm run audit -- /path/to/project --json
npm run smoke      # gauge against 3 calibration references
npm run typecheck
```

## Structure

- `src/rubric.ts`     — types + YAML loader
- `src/manifest.ts`   — parser for the `[_.vdx]` block in `mise.toml` (the older `[vdx]` too) + `.vdx-overrides.yml`
- `src/facts.ts`      — fact source loaders (tasks, packages, configs, sub-package detection)
- `src/predicates.ts` — predicate registry; true / false / unknown with a reason (schema 0.3)
- `src/evaluator.ts`  — recursive evaluator + sugar notation
- `src/scoring.ts`    — delta-style levels, `not_required` levels, flags for orthogonal axes
- `src/gha.ts`        — GitHub Actions workflows as the `ci` axis reads them
- `src/vocabulary.ts` — which project tasks a command calls through the project's runner
- `src/hooks.ts`      — one recognizer of hook frameworks for audit and doctor
- `src/clone-checks.ts` — clone checks printed by doctor and next to an axis in audit
- `src/personal-hooks.ts` — the profile's personal hooks in ~/.gitconfig: check and `--fix`
- `src/audit.ts`      — orchestrator: overrides + applies_to filter + subpackage-ctx
- `src/init.ts`       — `vdx init` planner (`selectVerbTask` + mise.toml renderer)
- `src/run.ts`        — `resolveLifecycleVerb` + error renderer (pure logic for `vdx <verb>`)
- `src/publish.ts`    — `planPublish` (pre-flight) + `executePublish` (bump → npm → git)
- `src/ai.ts`         — `vdx ai`: profile loader, launch plan, tmux session handling
- `src/cmux.ts`       — the focused topic as the cmux workspace description while `vdx ai` holds the attach (`bin/vdx-cmux-topic.cjs` watches it)
- `src/move.ts`       — `vdx move`: checks on every machine (Syncthing folders and peers, copies, containers, processes), Syncthing paused for the mv on each, memory path, conversations and trust follow
- `src/report.ts`     — markdown / JSON output
- `src/index.ts`      — CLI entry
- `src/mcp-server.ts` — MCP stdio server (9 tools)
- `src/defaults.ts`   — bundled rubric resolution
- `bin/vdx.cjs`, `bin/vdx-mcp.cjs` — Node wrappers (tsx ESM loader in-process)
- `bin/node-guard.cjs` — under a project's older node (`.nvmrc` with fnm, nvm, mise), runs the wrapper again on the node beside its bin link

## Not implemented yet

- Above L1 the `ci` axis reads GitHub Actions only; other CI systems answer
  "unknown". `branch-protection` reads GitHub, GitLab and Bitbucket Server;
  other hostings (gitolite, Bitbucket Cloud) answer "unknown", and so do
  Bitbucket restrictions by pattern or branching model.
- Baseline loading from a git ref is documented but evaluator still reads file
  paths only — `baseline:` in `mise.toml` is recorded but does not auto-fetch.
- Watermark drift (phase 2 of `drift-algorithm.md`).
- `vdx publish` only ships for Node (MVP). PHP/Python in Y.3; Cargo/Ruby/Go/Java
  in Y.4.
- Open items: O25 (mock-infra delta for Node), O26 (TOML round-trip), O27 (real
  shared-infra precheck), O32 (multi-subpackage monorepo). See
  [docs/decisions.md](../docs/decisions.md).
