vx | Releases

vx speaks to agents

Fri, 09 Oct 2026 09:00:00 GMT

vx 0.0.626 to 0.0.632 shipped on 2026-10-08 and 2026-10-09. This batch makes vx easy for an AI agent to drive: results as JSON, errors with stable codes, failed output an agent can act on, and an MCP server that runs and plans tasks. It also makes vx init the one command to adopt a Turbo or Nx repo.

In this release

vx run speaks JSON
Stable error codes
Failed output agents can act on
vx mcp runs and plans tasks
Why a task is affected
vx init adopts Turbo and Nx
One ordered log on a cache hit
Remote execution: TLS by default

vx run speaks JSON

vx run --format json prints one result object on stdout: each task’s status, exit code, duration and key, plus the time the cache saved and the critical path. An agent reads one value instead of parsing a log.

$ vx run build --all --format json 2>/dev/null
{
  "runId": "01a11f0d-014c-700d-a4ad-59e93a00a129",
  "ok": true,
  "exitCode": 0,
  "savedMs": 1270,
  "tasks": [
    { "id": "@demo/api#build", "status": "cache-hit", "durationMs": 3, ... }

PRs #3271, #3296. Deep dive: Built for agents

Stable error codes

Every refusal now carries a VX_E_ code that does not change between versions, so a script or an agent branches on the code, not the wording. Unknown verbs, usage mistakes and the reading verbs’ refusals are coded too.

$ vx run biuld --all --format json
{"ok":false,"error":{"code":"VX_E_UNKNOWN_TASK","message":"vx run: no projects declare task(s): biuld. Did you mean build?"}}

PRs #3298, #3321, #3324. Deep dive: Error codes

Failed output agents can act on

A failed task’s output is kept for vx last --failed, and every file:line:col in it becomes a location an agent can open and a terminal can click.

$ vx last --failed --format json | jq '.tasks[] | select(.output != "") | {status, locations}'
{
  "status": "failed",
  "locations": [
    { "file": "/work/demo/packages/ui/src/index.ts", "line": 3, "col": 7 }
  ]
}

vx last --log <task> prints one task’s output from a recorded run, so an agent reads only the log it needs. vx also ships an agent skill (skills/vx/SKILL.md) and the JSON schemas the docs point at.

PRs #3273, #3264, #3325, #3288

vx mcp runs and plans tasks

@vzn/vx-mcp gained new tools: runTasks runs tasks and returns the JSON result, planTasks returns what a run would do without running it, listTasks narrows by --filter and --affected, getConfig returns a task’s resolved config, getTaskLog returns one task’s output, and whyDidThisRerun answers like vx why, root cause included. mcp({ run }) limits runTasks to named tasks or turns it off.

flowchart LR
  A[agent] -->|planTasks| P[what would run]
  A -->|runTasks| R[JSON result]
  A -->|whyDidThisRerun| W[root cause]
  style R stroke:#c6f84e,stroke-width:2px

PRs #3289, #3303, #3320, #3300, #3338, #3330. Deep dive: Agents and MCP

Why a task is affected

--dry now prints, under each task --affected kept, the changed file that kept it and the dependency it came through.

$ vx run build --all --affected=HEAD --dry
would run:
  ▶  @demo/docs#build  cache miss — would exec   e50d7ee9  ~309ms
                       affected: packages/ui/src/index.ts changed (an input), via @demo/ui#build
  ▶  @demo/ui#build    cache miss — would exec   e212d097  ~312ms
                       affected: packages/ui/src/index.ts changed (an input)

PR #3276. Deep dive: See inside a run

vx init adopts Turbo and Nx

In a repo with turbo.json or nx.json, vx init runs @vzn/vx-migrate. It asks whether to write native config (a vx.config.ts per package) or keep the repo’s own config live; --native and --keep answer up front. A Turbo remote cache or a self-hosted Nx cache the repo already uses is kept.

vx init --native

PRs #3258, #3237. Deep dive: From Turborepo

One ordered log on a cache hit

A task’s stdout and stderr are now stored as one ordered log, so a cache hit replays stderr too, in the order the task wrote it. Live and on a hit, a task’s output prints as one section.

PRs #3251, #3248. Deep dive: Inside a cache hit

Remote execution: TLS by default

@vzn/vx-reapi connects an endpoint with no scheme over TLS, as Bazel does; plaintext takes grpc:// or tls: false. A remote result can now write only the outputs the task declares.

reapi({ endpoint: 'grpc://localhost:8980' })

PRs #3265, #3256. Deep dive: Remote execution

Breaking changes

The cache format is now vx-cache-v42: every cached task misses once after upgrading (#3251).
@vzn/vx-reapi: an endpoint with no scheme now uses TLS; a plaintext server needs grpc:// (#3265).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

Runs that explain themselves

Thu, 08 Oct 2026 19:00:00 GMT

vx 0.0.590 to 0.0.625 all shipped on 2026-10-08. This batch is about answers: how long a run has left, why a task re-ran, and where a config is wrong. It also brings Vite Task and Lerna migration, a dev server that stays up under vx watch, and faster warm runs on large workspaces.

In this release

Live run end forecast
vx why walks to the root cause
Config errors point at the line
Time the cache saved
Dev server stays up in vx watch
Migrate from Vite Task
Better Nx and Lerna migration
vx show takes filters
Faster warm runs

Live run end forecast

A second into a live run, the time row says what is left. The forecast comes from each unfinished task’s median run time in local history, so it needs no setup. Worker rows mark the task on the critical path and say how many tasks wait on each (blocks N). In Ghostty, iTerm2, WezTerm and Windows Terminal, vx also draws progress in the tab and posts a desktop notification when a run of 10 s or more ends.

     1.40s running          web#build  critical path · blocks 3
     1.10s running          docs#build
  time      1.41s · ~3s left

PR #3246

vx why walks to the root cause

When a task re-ran only because a dependency moved, vx why used to stop at that dependency and tell you which vx why to run next. It now follows the chain inside the same run down to the task whose own inputs changed, and prints it under root cause. --format json carries the chain as roots.

$ vx why app#build
  verdict    cache key changed: upstream lib#build

  what changed (1 component, 5 unchanged):
    changed upstream  lib#build  dcdf2a600ba2194d → 921ea5200e280cc9

  root cause:
    app#build ← lib#build ← file packages/lib/src/index.ts

flowchart LR
  F["file packages/lib/src/index.ts"] -->|changed| L["lib#build"] -->|key moved| A["app#build"]
  style F stroke:#c6f84e,stroke-width:2px

PR #3245. Deep dive: Why did this re-run?

Config errors point at the line

A config refusal now names the file at line:col, relative to your directory, so a terminal can open it on click. Below the message it prints the lines leading up to the field with a caret under it.

vx: packages/app/vx.config.ts:8:47: tasks.build.cache.outputs must be an object (fields: files, workspaceFiles), not an array — did you mean `{ files: [...] }`?

  6 |       dependsOn: ['^build'],
  7 |       exec: { command: 'sleep 0.6 && mkdir -p dist && cp src/index.ts dist/' },
> 8 |       cache: { inputs: { files: ['src/**'] }, outputs: ['dist/**'] },
    |                                               ^

PR #3247

Time the cache saved

The result line now says how much time the cache saved. The figure is the sum of the stored run times of the tasks it restored, not the time the restore took.

  info      4 workers · local cache
  time      39ms
  result    2 tasks · all cached · 928ms saved · 39ms

Two tasks, all cached

stored run time928 ms

restore took39 ms

PR #3242

Dev server stays up in vx watch

vx watch dev restarted the dev server on every cycle, even for an edit inside the app, so the dev tool’s own hot reload never got a chance. The server now stays up while its task config is unchanged. Each cycle rebuilds only the libraries an edit reaches, and the dev tool reloads what changed. A config change or a crash still restarts it.

vx watch dev

flowchart LR
  E["edit in lib"] --> L["lib#build reruns"] --> D["dev server stays up"] --> H["hot reload"]

PR #3243. Deep dive: Watch mode

Migrate from Vite Task

npx @vzn/vx-migrate now reads a repo that uses vite-plus. It loads each vite.config as vp run does and writes a vx.config.ts per package from run.tasks and the package scripts. A nested vp run becomes a dependsOn edge instead of a second runner inside vx. vx run also accepts the vp run flags you already type: -r reads as --all, -w as --filter //, --concurrency-limit as --concurrency, and --ignore-depends-on as --exclude-dependencies.

npx @vzn/vx-migrate
vx run build -r

PRs #2908, #2965. Guide: Vite Task

Better Nx and Lerna migration

A Lerna repo whose root scripts call lerna run now migrates through nx(), since Lerna runs Nx’s task runner underneath. nx.json’s parallel, defaultBase and maxCacheSize are written into vx.workspace.ts as concurrency, affectedBase and cacheRetention.maxSize, where they used to be notes. A run-commands line that starts with nx <target> <project> becomes a dependsOn edge instead of a todo. And -p 'apps/*' selects by directory, as Nx does.

npx @vzn/vx-migrate
vx run build -p 'apps/*'

PRs #3072, #3007, #2956, #2887. Guide: Nx

vx show takes filters

vx show and vx show <task> now select projects the same way vx run does. This is the vx form of turbo ls --affected and nx show projects --affected.

$ vx show --affected
app  packages/app  1 task
lib  packages/lib  1 task

PR #2986

Faster warm runs

Four changes cut the overhead of a warm run on the 1,090-package bench. An all-hit run went from 752 ms to 708 ms by reusing group keys. A restore went from 2,356 ms to 2,019 ms by walking outputs once. The scheduler dropped about 25 ms of per-task bookkeeping, and a frozen run loads its configs 2.9× faster. A new check on every PR now holds spawn, hash and SQLite counts on these paths to a baseline.

vx run build --all

All-hit run, 1,090 packages

before752 ms

after708 ms

Restore, 1,090 packages

before2,356 ms

after2,019 ms

PRs #3235, #3241, #3239, #3240, #3238

Breaking changes

The cache format is now vx-cache-v41: every cached task misses once after upgrading (#3030).
exec.env define and passThrough names must be shell identifiers; others are refused at load (#2958).
A tag that --filter tag: cannot select (**, an upper-case glob) is refused at load (#2966).
Config array fields are typed readonly; copy a resolved list before mutating it (#2938).
Cache.storeFallback, Cache.storeMoved and Cache.orphansBeforeReset are removed; open a Cache in 'preview' mode instead of the last (#2976, #3041).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

Every cache key known before a task runs

Wed, 07 Oct 2026 12:00:00 GMT

vx 0.0.521 to 0.0.589 shipped on 2026-10-07. The theme is fewer surprises: the graph refuses configs that would delete files or slow every run, a fully cached run boots nothing it does not need, and telemetry tells you why a task rebuilt.

In this release

Keys known before anything runs
One output path, one task
Outputs that would delete your sources
Servers only cache hits need stay off
Live OpenTelemetry export
vx-migrate declares and installs plugins
Faster all-cached runs
vx watch follows what you asked for
Forwarded args reach the command
Cache correctness fixes

Keys known before anything runs

A task whose input globs could match another task’s outputs used to get a preliminary key: vx could not probe, prefetch or restore it ahead of the schedule. The new rules.upfrontKeys refuses such a task at load and names the ! entry that fixes it. It is on by default. The producer’s key already reaches the reader through dependsOn, so excluding its outputs loses nothing. rules: { upfrontKeys: false } in vx.workspace.ts keeps the old waiting path.

vx: app#test reads "**/*" in cache.inputs.files, which matches app#build's
output "dist/**": a task's key must not read another task's outputs (the
dependency's key already cascades through dependsOn). Exclude it: add
"!dist/**" to app#test's cache.inputs.files, or set rules: { upfrontKeys:
false } in vx.workspace.ts to let it wait for its producer.

PR #2846. Docs: Workspace config.

One output path, one task

Two tasks whose outputs overlapped were allowed when a dependsOn edge ordered them. That was correct, but every run of the dependant paid for a stamp, a diff and a clean. rules.exclusiveOutputs, on by default, refuses the ordered pair too. Give each task its own output path, or set rules: { exclusiveOutputs: false } to keep the additive path. Output globs that overlap without sharing a prefix, such as dist/**/*.js beside dist/sth/**, are now caught as well.

vx: app#types and app#build both declare the output "dist/**" in
cache.outputs.files: vx cleans a task's declared outputs before it runs
and before a cache-hit restore, so whichever of these runs second DELETES
the other's output. Give each task its own output path, or set rules: {
exclusiveOutputs: false } in vx.workspace.ts to let a dependant add to its
upstream's outputs.

flowchart LR
  B["app#build"] -->|writes| D[("dist/**")]
  T["app#test"] -.->|"reads **/*"| D
  D -.- X["refused: add !dist/**"]

PRs #2845, #2841. Deep dive: Strict output ownership.

Outputs that would delete your sources

vx removes a task’s outputs before it runs. A formatter that declared src/** as both inputs and outputs had every committed file under src deleted. The graph now refuses it, whatever the rules, and says what to do instead.

vx: app#fmt: every file "src/**" in cache.inputs.files selects is also its
own output: vx removes a task's outputs before it runs, so the task would
delete its own sources. A task that rewrites files in place (a formatter)
declares no outputs.

PR #2847.

Servers only cache hits need stay off

A persistent task pulled in as a dependency booted on every run, and its dependants waited for it to be ready even when they were cache hits. Now vx holds such a server dormant. It starts only if a dependant misses, and otherwise never spawns. A fully cached vx run e2e#test over web#dev went from 2.2 s to under 190 ms. Dependants in the server’s own project still wait for it.

vx run e2e#test

Cached vx run e2e#test over web#dev

before2.2 s

afterunder 190 ms

PR #2851. Deep dive: Dev servers in the graph.

Live OpenTelemetry export

@vzn/vx-otel now sends each task as it ends, batched once a second, so a dashboard follows a CI run while it runs. live: false sends it all at the end. Traces, metrics and logs share one resource key. Task spans gain the command, queue wait, input file count, artifact size, save and fetch time, and for a miss, what its key changed since the last saved entry. On CI, every signal links back to the run and the pull request.

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 vx run build --all

PRs #2786, #2787, #2792, #2794. Docs: OpenTelemetry.

vx-migrate declares and installs plugins

A migrated repo used to end with a note asking you to declare the lockfile plugin yourself. @vzn/vx-migrate now writes the plugins into vx.workspace.ts and installs them at its own version: the lockfile’s @vzn/vx-lockfile plugin, scheduleHistoryPlugin(), and github() from @vzn/vx-ci when .github/workflows exists. Written files no longer carry a “Generated by” header. vx also stops printing cache upkeep notices on upgrade.

npx @vzn/vx-migrate

PR #2777. Docs: One command.

Faster all-cached runs

Several cuts to the warm path. Task globs match through one RegExp per side instead of a dozen Bun.Glob calls per file. @vzn/vx-lockfile, @vzn/vx-ci and @vzn/vx-mcp load their internals only when used, and @vzn/vx-otel imports in 1.4 ms instead of 9.6 ms. A repo with no remote no longer spawns two git commands on the run path. Together they make the all-cached run of the vx repo itself 25% faster.

vx run build --all

@vzn/vx-otel import

before9.6 ms

after1.4 ms

PRs #2785, #2788, #2842.

vx watch follows what you asked for

vx watch lib#build watched every project; it now watches lib and the projects other pkg#task arguments name. vx watch --affected re-runs tasks for edits made after it started, not only those in the starting diff. An edit inside a nested project no longer triggers a cycle on the root project.

vx watch lib#build

PRs #2828, #2827, #2832.

Forwarded args reach the command

Args after -- now reach a command that ends in a heredoc or a trailing newline, where before they never arrived or ran as a command of their own (--watch: not found). The $ line in the output shows the command with the args, as it ran.

vx run test -- --watch

PRs #2790, #2802, #2831.

Cache correctness fixes

Several runs could store or replay wrong bytes under a green result. A file added under an input glob while the command ran is now caught and the save withheld. Committed files under a node_modules directory, such as test fixtures, are part of the key again. The clean before a run no longer follows an output directory linked to another directory in the project. A dependant that deletes its upstream’s files no longer gets them restored on every hit.

vx run build --all

PRs #2854, #2793, #2795, #2822, #2823.

Breaking changes

CACHE_VERSION is now vx-cache-v40: every cached task misses once after the upgrade (#2825).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

One cache for every checkout

Tue, 06 Oct 2026 12:00:00 GMT

vx 0.0.496 to 0.0.520 shipped from October 4 to October 6, 2026. The theme is less setup and less noise: every clone and worktree of a repo now shares one cache, --affected picks tasks instead of packages, one command moves a Turbo or Nx setup to vx, and the run summary is the last thing a run prints.

In this release

One cache for every checkout
Affected runs follow task edges
vx-migrate does the whole adoption
The summary is the last line
Restored and up-to-date hits everywhere
@vzn/vx-github is now @vzn/vx-ci
Task metrics and linked spans in OpenTelemetry
Less CPU per cold miss
Fixes

One cache for every checkout

Cache entries now live in ~/.vx/<id>/cache, like Nx. The id comes from the git remote and the workspace’s path in the repo (or the first commit when there is no remote), so clones and worktrees of one repo hit each other’s entries. cacheDir, VX_CACHE_DIR or --cache-dir still keep the whole cache in one directory of your choosing. A store or index from another schema version is now reset instead of refusing the run, and its artifacts are indexed again on their next hit, so a schema change no longer throws the artifacts away.

import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({
  cacheDir: 'build/.vx', // unset: ~/.vx/<id>/cache, shared by checkouts
})

flowchart LR
  A["~/code/app"] --> C[("~/.vx/&lt;id&gt;/cache")]
  R["worktree: app-review"] --> C
  H["worktree: app-hotfix"] --> C

PRs #2773, #2775. Docs: Workspace config.

Affected runs follow task edges

--affected now selects tasks, not packages. A changed file seeds the tasks whose declared inputs match it, and a requested task runs when its dependsOn closure holds a seeded one. A package with no build task gets a default build group behind ^build, keyed on every file of the package. So a package consumed as source still moves its dependants’ keys: here ui has no tasks, and an edit to it re-runs app#test.

echo 'x' >> packages/ui/src/i.ts
vx run test --affected=HEAD

 ⏺︎     7ms success miss     app#test

PR #2770.

vx-migrate does the whole adoption

npx @vzn/vx-migrate now asks whether to migrate natively (a vx.config.ts per package) or keep turbo.json / nx.json as the source. --native or --keep answer it; without a terminal it is native. It installs vx with the repo’s own package manager (--no-install skips that) and leaves your package.json scripts alone.

npx @vzn/vx-migrate --native

PRs #2771, #2772. Docs: One command.

The summary is the last line

Nothing prints below the end-of-run summary anymore. Aborted and unstarted tasks are rows in the task list with their own status, a skipped task names its blocker, and a flaky task carries a note on its row. Warnings from uploads, plugin teardown and history land above the summary. The failure recap is gone: each failure’s output already prints above it.

 ◼︎    11ms failed  miss     a#build
 ⊘         skipped          b#build • blocked by a#build

┌─ a#build > failed (exit 1)

$ mkdir -p dist && cp src/i.ts dist/ && exit 1

└─ a#build ── (11ms) failed (exit 1)


─ vx 0.0.0 ───────────────────────────────────────────────────
  projects  ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            2 in run · 2 total
  tasks     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            1 failed · 1 skipped · 2 total
  cache     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            1 miss · 1 skipped

  info      4 workers · local cache
  time      56ms · max 11ms · avg 11ms · min 11ms
  result    2 tasks · 1 failed · 0 cached (0%) · 56ms

PRs #2752, #2757, #2780, #2781.

Restored and up-to-date hits everywhere

A hit either found its outputs in place (up-to-date) or restored them from the cache. Only the live summary told them apart before. The run history now stores the split, so vx last, vx info, vx why, the markdown report, vx mcp and the plugins all show it.

$ vx last
  2 tasks · 2 hits (0 up-to-date, 2 restored: 2 local, 0 remote)

  restored-local    a#build      17ms  73b25577a99ad2f8
  restored-local    b#build      13ms  4935028bcd991dbd

Commit f336e9f.

@vzn/vx-github is now @vzn/vx-ci

The GitHub Actions plugin has a new package name. The github() export is unchanged, so only the import moves.

import { defineWorkspace } from '@vzn/vx/config'
import { github } from '@vzn/vx-ci'

export default defineWorkspace({ plugins: [github()] })

PR #2782. Docs: GitHub Actions.

Task metrics and linked spans in OpenTelemetry

@vzn/vx-otel now sends per-task metrics: duration, CPU time and peak memory at each task’s end, and CPU usage and memory each second while it runs, so a metrics backend can chart them. A task span links to the tasks it waited on, records each failed attempt as a vx.task.retry event, and each VX_TIMING stage is a child span of the run.

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 vx run build --all

PRs #2783, #2784. Docs: OpenTelemetry.

Less CPU per cold miss

A cold run does less work per task: no deferred closure walk when nothing is deferred, upstream outputs read only for a plugin executor, and small artifacts packed on the calling thread. On macOS tasks run under dash when it is on PATH. vx’s own cold CPU on 1,090 packages went from 6.85 s to 5.7 s.

vx run build --all --force

vx cold CPU, 1,090 packages

before6.85 s

after5.7 s

PR #2767.

Fixes

An extglob such as src/@(x|y).ts in a task glob matched no file, so an edit replayed a stale hit. vx now refuses it at load and suggests the brace form (#2768).
Tasks get npm_execpath for the repo’s package manager, so tools like npm-run-all call back pnpm or bun instead of a global npm (#2774).
On macOS a wildcard write grant in the sandbox now covers what is inside the directories it matches, which pnpm’s lock files need (c931a09).

cache: { inputs: { files: ['src/{x,y}.ts'] }, outputs: { files: ['dist/**'] } }

Breaking changes

@vzn/vx-github is now @vzn/vx-ci; github() is unchanged.
The cache moves to ~/.vx/<id>/cache; existing entries miss once.
The run history gains hit counts; an older index is dropped once.
Cache.getMany and CacheLayer.getMany take an optional get context.
The end-of-run failure recap and formatFailureRecap are removed.

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

Ready for Docker and pull requests

Sat, 03 Oct 2026 12:00:00 GMT

vx 0.0.361 to 0.0.495 all shipped on 2026-10-03. The theme is closing gaps people hit when they move a Turbo or Nx repo over: a Docker prune, tags, interactive tasks, Turbo’s range spelling, and a remote cache a PR cannot poison. Dev servers, the sandbox and remote execution also tell you more when something goes wrong.

In this release

Prune a workspace for Docker
Project tags
Interactive tasks
Per-PR remote cache scope
Colour in task output and help
Dev servers that die or stall
Turbo-style affected ranges
A sandbox that names hidden reads
Remote execution falls back past a queue bound
Nx: your own executors as commands

Prune a workspace for Docker

Declaring pnpm(), bun(), npm() or yarn() from @vzn/vx-lockfile now adds vx prune, vx’s answer to turbo prune. It copies the named projects and their workspace dependencies to out/, and cuts each lockfile to what that subset installs, so it still installs frozen. --docker splits the copy into json/ (manifests and lockfile, the cacheable install layer) and full/ (everything).

$ vx prune web --docker
vx prune: 2 projects → out (json/ + full/), bun.lock pruned
  ui (packages/ui)
  web (packages/web)

flowchart LR
  W["workspace"] -->|"vx prune web --docker"| O["out/"]
  O --> J["json/ package.json files + lockfile"]
  O --> F["full/ ui and web sources"]

PR #2750

Project tags

A project config can carry tags, and --filter tag:<pattern> selects the projects holding a match, as Nx’s tag: does. vx show and vx mcp list them, and the Nx adoption carries Nx tags over. Tags are in no cache key.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tags: ['frontend'],
  tasks: { build: { exec: { command: 'vite build' } } },
})

$ vx run build --filter tag:frontend
 ⏺︎     7ms success no-cache ui#build
 ⏺︎     8ms success no-cache web#build

PR #2749

Interactive tasks

exec.interactive: true marks a task that reads the terminal: a prompt, a REPL, a watch mode’s keys. On a TTY it gets vx’s stdin, stdout and stderr, and nothing else starts while it runs. It always runs on this machine and is never cached or sandboxed. Off a TTY, on CI, it runs like any task. The Turbo adoption maps Turbo’s interactive: true to it.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: { repl: { exec: { command: 'bun repl', interactive: true } } },
})

PR #2748

Per-PR remote cache scope

cacheScope decides where a run’s remote cache writes land. 'trusted' reads and writes the shared keys and is the default on CI. 'read-only' writes nothing and is the default off CI. Any other name, such as 'pr-123', reads its own keys then the trusted ones, and writes only its own, so a pull request never writes what the default branch reads. Set it in vx.workspace.ts, with VX_CACHE_SCOPE, or let the github() plugin (now @vzn/vx-ci) set it on Actions. It is a client-side convention: real isolation needs a server that scopes writes by token.

VX_CACHE_SCOPE=pr-123 vx run build --all

PR #2746. See Cache poisoning.

Colour in task output and help

A task’s stdout is a pipe, so tools printed plain under vx. Tasks now get FORCE_COLOR=1 unless they already see FORCE_COLOR or NO_COLOR, as under Nx and Turbo. When vx’s own output is plain, it strips the escapes from task output, live and replayed. vx help on a terminal now has bold headings and cyan verbs, flags and examples; piped help stays plain.

NO_COLOR=1 vx run build --all

PRs #2742, #2744

Dev servers that die or stall

A dependency server that crashed mid-run was named only at the end, while its dependants failed with no word of why. vx now says so when it happens, and dependants not yet started skip, named for the server. A server whose readyWhen never matches no longer waits in silence: after 10 seconds vx says what it waits for and whether anything bounds the wait.

$ vx run web#e2e
┌─ web#e2e > $ sleep 1; echo e2e done
vx: web#dev exited with code 3 while the run went on
e2e done
└─ web#e2e ── (1.01s) success

PRs #2152, #2338, #2463. Deep dive: Dev servers in the graph.

Turbo-style affected ranges

Turbo’s CI spelling --filter=[origin/main...HEAD] was refused as a range. vx diffs a base against the working tree, so a range that ends at HEAD means the same set plus any uncommitted edit. <base>...HEAD and <base>..HEAD now work in --filter and --affected; a range that ends anywhere else is still refused.

vx run test --affected=origin/main...HEAD

PRs #2149, #2373

A sandbox that names hidden reads

A sandboxed task that failed on a read the sandbox hid saw only its tool’s “File not found”: tsc extending a root tsconfig.base.json was the common case. A failed task now names the hidden paths that exist on the host and the grant to add. Separately, the host’s credential stores (~/.ssh, ~/.aws, ~/.npmrc and the like) are now denied to sandboxed tasks unless allow.read names one, so a dependency cannot copy a key into a cached output.

vx: the sandbox hid paths outside the project that exist on this machine,
which are not reported as violations: /repo/tsconfig.base.json. If the
task reads one, grant it, e.g. `allow: { read: ['../../tsconfig.base.json'] }`.

PRs #2387, #2344, #2451. See the sandboxing guide.

Remote execution falls back past a queue bound

With @vzn/vx-reapi, an action no worker picked up waited without bound unless the task set exec.timeout, and then it failed as timed out. The new queueTimeoutMs bounds the wait for a worker. Past it, vx cancels the remote operation, runs the task on this machine, and says why once. A task placed exec.remote: 'only' fails with that reason instead.

import { defineWorkspace } from '@vzn/vx/config'
import { reapi } from '@vzn/vx-reapi'

export default defineWorkspace({
  plugins: [
    reapi({
      endpoint: 'grpcs://grpc.example.com:443',
      execute: true,
      queueTimeoutMs: 60_000,
    }),
  ],
})

PRs #2716, #2723. Deep dive: Remote execution.

Nx: your own executors as commands

nx() runs every Nx executor through nx-exec, a Node boot per task. A workspace’s own executor that only wraps a shell command can now skip that: nx({ executors }) takes a function per executor name that returns { command, timeout?, env? }, or undefined to leave the target to nx-exec. Each function’s source text keys the cached mapping, so an edit re-maps. Also, an Nx output that starts with a wildcard (**/*.d.ts) now stays cached instead of turning the target uncached.

import { defineWorkspace } from '@vzn/vx/config'
import { nx } from '@vzn/vx-migrate'

export default defineWorkspace({
  plugins: [
    nx({
      executors: {
        '@acme/tools:shell': (t) => ({ command: String(t.options.command) }),
      },
    }),
  ],
})

PRs #2733, #2736. Deep dive: From Nx.

Breaking changes

Core SCHEMA_VERSION v29 to v30: an older cache index is dropped on first open (#2246).
nx() migrations write nx-exec lines where they wrote executor commands (#2632).
vx init keeps existing configs and exits 0 instead of refusing with 1 (#2546).
reapi() refuses onWarn, tlsCaPem, tlsClientCertPem and tlsClientKeyPem; use the file options (#2535).
@vzn/vx-reapi’s plugin-api record drops the WireOnly type (#2541).
refuseUnknownOptions takes a PluginOptionKinds record, and a plugin option of the wrong kind is refused (#2475).
@vzn/vx-reapi stops exporting its wire and Merkle internals (#2521).
@vzn/vx-migrate exports only its four plugins (#2520).
@vzn/vx-lockfile stops exporting its parser namespaces (#2512).
@vzn/vx-otel stops exporting its OTLP builders (#2508).
@vzn/vx-github stops exporting its Checks API helpers (#2503).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

The Turbo and Nx flags you already type

Fri, 02 Oct 2026 12:00:00 GMT

vx 0.0.326 to 0.0.360 all shipped on 2 October 2026. The theme is moving in: migrations write configs that run without Nx or Turbo installed, the CLI takes the selections you already know, and long-running dev servers behave. Windows is now supported through WSL only.

In this release

Nx targets migrate as plain commands
Cleaner Turbo migrations
Filters and flags from Turbo, pnpm and Nx
Affected runs compare with the trunk
Dev servers you can rely on
Faster scoped runs
Secrets masked in run history
vx init maps more repos
Sandboxed tasks run once
Reftable repositories

Nx targets migrate as plain commands

bunx @vzn/vx-migrate used to write every Nx executor target as an nx-exec line, so the migrated config still needed Nx to run. It now writes the command the executor drives, with the defaults Nx applies: jest, vitest, vite build, eslint, tsc, playwright, esbuild, swc, Next.js, Cypress, Storybook, and the Vite dev and preview servers. @nx/js:node becomes node on the build output, as a persistent task. Webpack and Rollup targets name Nx’s convert-to-inferred generator in their TODO, and nx-release-publish gets one note instead of a failing task per package. nx() still runs executors through nx-exec.

bunx @vzn/vx-migrate
vx run build --all

PRs #2298, #2333. Guide: Nx.

Cleaner Turbo migrations

A task env that several packages share is now one export in vx-preset.ts instead of a copy in every config: vercel/ai’s output is 2× smaller, with every key unchanged. The .env probes are named exports too (dotenvFiles). Framework variables Turbo infers, such as Next’s NEXT_PUBLIC_*, are written out from the names your source and its workspace dependencies spell, so a migrated Next build no longer inlines them empty. The report also names the @vzn/vx-lockfile plugin your lockfile needs, and says when turbo() is redundant once the configs are written.

npx @vzn/vx-migrate

PRs #2207, #2217, #2218, #2225, #2319. Guide: Turborepo.

Filters and flags from Turbo, pnpm and Nx

--filter now reads Turbo’s <name>...[ref] and ...x... forms as Turbo does, matches a name without its scope as pnpm does (cart finds @shop/cart), and lets a trailing ** in a path match its base directory. vx run takes Nx’s camelCase flags (--skipNxCache, --nxBail) and Nx short project names in cart:build. Every flag in Turbo 2.11’s run help now either works or is refused with the vx way to do it.

$ vx run build --heap
vx run: --heap (turbo): use `--profile[=<path>]` for vx's own trace (see `vx run --help`)

PRs #2015, #2016, #2017, #2018, #2041, #2055.

Affected runs compare with the trunk

With no origin/HEAD (no remote, or the fetch actions/checkout does), a bare --affected compared with HEAD~1 and saw only a branch’s last commit. It now compares with the first trunk branch that is not HEAD, as Turbo and Nx do. On a one-commit shallow clone, vx says the history is missing instead of only that the ref did not resolve. Under turbo() on GitHub Actions, the base is the pull request’s base or the push’s before, as Turbo picks it.

vx run test --affected

PRs #2088, #2122, #2287.

Dev servers you can rely on

A server vx keeps after the summary now streams its output line by line instead of showing nothing. One that crashes after the summary counts as failed in --summarize and --report. When another task in the run fails, vx stops the servers and exits 1 instead of holding them forever. vx run app#dev over a dependsOn: ['^dev'] group now keeps the servers it stands for.

vx run dev --all

PRs #2030, #2039, #2054, #2096. Deep dive: Dev servers in the graph.

Faster scoped runs

A run scoped to one package no longer walks git over its whole dependency closure, only over the projects that own a task, and it finds that closure by search instead of building it for the whole graph. On 1,000 projects, a warm vx run build --filter pkg-500 went from 181 ms to 113 ms. A plain repository’s git facts are read off the disk instead of from a git rev-parse spawn, and a cold load imports 128 configs at a time.

A warm frozen run also keeps its lock check from one run to the next.

vx run build --filter pkg-500

Warm vx run build --filter pkg-500, 1,000 projects

before181 ms

after113 ms

PRs #2035, #2241, #2306, #2323, #2329.

Secrets masked in run history

The invocation line vx stores and vx last prints kept a secret passed after -- whole, while the task’s own output masked it. It is now masked with the same rule before it is recorded. --tag values, stored on the history row and sent to telemetry, are masked too.

vx run publish -- --token=$NPM_TOKEN
vx last

PRs #2307, #2337.

vx init maps more repos

vx init now maps a script that runs a server as a persistent task, so a dependent no longer waits on it forever. A build’s output directory is guessed from its own command when no framework rule names one. The next: line it prints is runnable, naming git init first when needed. It names Yarn Plug’n’Play when that is why a config cannot load, and vx.config.cjs and vx.config.cts are read as configs.

vx init

PRs #2070, #2098, #2100, #2169, #2290, #2308.

Sandboxed tasks run once

A strace that warns it cannot check the seccomp filter order still works, but vx read the warning as a tracer failure and ran every sandboxed task twice. vx now uses such a strace only when it is quiet, and otherwise runs tasks untraced. A task with a port bridge also waits for its host listener before it starts, so a server’s port no longer refuses its first connection under load.

vx run test --all

PRs #2121, #2130. Deep dive: The sandbox.

Reftable repositories

Git 2.45 can store refs as a reftable (--ref-format=reftable). vx read HEAD from the ref files, which a reftable repository does not keep, and vx-migrate missed branch moves. Both now handle it; keys, cache hits and --affected match a normal repository.

git init --ref-format=reftable

PR #2318.

Breaking changes

Native Windows is unsupported; run vx under WSL. Tasks no longer get SYSTEMROOT, APPDATA and the other Windows env vars (#2227).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

Fewer surprises when you switch

Thu, 01 Oct 2026 12:00:00 GMT

vx 0.0.243 to 0.0.325 all shipped on 2026-10-01. The theme is adoption: moving from Turbo or Nx to vx has fewer surprises, from the first vx init to the CI job that must not write the shared cache.

In this release

Root scripts in vx init
A default base for affected runs
Turbo’s //#task
Turbo and Nx spellings name the vx way
Remote cache switches for pull requests
turboCache() reads all of Turbo’s cache config
nx() follows more of nx.json
More Turbo builds stay cached
A faster vx from npm
Edited Bun patches invalidate the cache

Root scripts in vx init

vx run lint used to find no project in many repos, because the root’s lint, test and format scripts were never mapped. vx init now turns a root script that checks the whole repo into a root task. A script that runs the members (pnpm -r, --filter, --cwd, --prefix, vp run, a runner, or vx itself) stays unmapped, and init names it. A run scoped to a project that lacks a task others declare now says so and names --all.

acme (the workspace root): its scripts that check the whole repo are its tasks; left out as running the members (`pnpm -r`, `--filter`, a runner): build

PRs #1994, #1996, #2004, #1971

A default base for affected runs

A bare --affected compared with origin/HEAD, so a git-flow repo diffed against the wrong branch. affectedBase in vx.workspace.ts now names the ref, and --affected=<base> still wins. nx() and turbo() set it from Nx’s defaultBase and NX_BASE, and from Turbo’s TURBO_SCM_BASE.

import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({ affectedBase: 'origin/develop' })

PR #1960. Docs: Workspace config.

Turbo’s //#task

Turbo spells a root task //#lint. vx read // as a project name and refused it in vx run, vx show, vx why and in dependsOn. All four now take it as the root project’s task, from any directory.

vx run //#lint

PRs #1953, #1956, #1957

Turbo and Nx spellings name the vx way

Turbo’s and Nx’s run flags and verbs used to stop at “unknown flag” or “unknown command”. Now -F is --filter, three Nx options are aliases, and the rest (--env-mode, --global-deps, nx graph, nx show projects and more) say what does it in vx. A flag cut short (--dry) or --json on a verb that takes --format json gets a hint too.

$ vx run build --env-mode=strict
vx run: --env-mode (turbo): vx passes only the variables a task declares (strict): list the rest in `exec.env.passThrough` (see `vx run --help`)
$ vx graph
`nx graph` is `vx run <task> --graph[=<file>.dot]` here: the task graph as Graphviz DOT
$ vx info --json
vx info: unknown flag: --json (did you mean --format json?) (see `vx info --help`)

PRs #1948, #1949, #1950, #1951, #1955, #1964, #1936

Remote cache switches for pull requests

A CI keeps an untrusted pull request from writing the shared cache with Turbo’s TURBO_CACHE and TURBO_REMOTE_CACHE_READ_ONLY, or Nx’s NX_SKIP_REMOTE_CACHE. vx ignored them, so such a job wrote what main would restore. turboCache() and nxCache() now honour each one. A switch can only narrow the run’s --cache policy, never widen it.

TURBO_REMOTE_CACHE_READ_ONLY=1 vx run build --all

PR #1941. Docs: Remote cache.

turboCache() reads all of Turbo’s cache config

turboCache() declined on Vercel and in a turbo linked repo. It now reads VERCEL_ARTIFACTS_TOKEN and _OWNER, and .turbo/config.json. It honours Turbo’s timeouts, signs only where turbo.json turns signing on, and sends teamId only in Vercel’s team_ form. vx init declares it in a linked repo, and says when nx.json uses Nx Cloud, which vx cannot share.

import { defineWorkspace } from '@vzn/vx/config'
import { turbo, turboCache } from '@vzn/vx-migrate'

export default defineWorkspace({ plugins: [turboCache(), turbo()] })

PRs #1942, #1939, #1940, #1946, #1962

nx() follows more of nx.json

nx() now caps the local cache at maxCacheSize (or NX_MAX_CACHE_SIZE), and lets NX_PARALLEL win over nx.json’s parallel, as Nx 23 does. nxCache() keeps reads on when a read-only token’s upload is refused. bunx @vzn/vx-migrate --from nx exports the graph itself when none is on disk.

NX_PARALLEL=2 vx run build --all

PRs #1945, #1944, #1947, #1977

More Turbo builds stay cached

turbo() left a task uncached when its outputs glob might reach a source file. It now proves more globs safe: **/dist/** with no tracked dist directory, a pattern like dist-*/** that matches no tracked top-level entry, and top-level artifacts like *.xml. vercel/ai’s 69 builds and tldraw’s 35 now cache. nx() shares the same rules.

vx run build --all

PRs #1974, #1986, #1969, #1980

A faster vx from npm

Every vx an npm user runs starts in a small Node launcher. It is now CommonJS, not ESM: vx --version went from 65.5 ms to 57.0 ms. On Node 22.15 and newer the launcher replaces itself with the binary instead of spawning it: from 54.2 ms to 45.3 ms. The binary itself answers --version before loading the dispatcher, from 20.1 ms to 16.4 ms.

npx vx --version

vx --version from npm

before65.5 ms

after57 ms

On Node, spawning vx

before54.2 ms

after45.3 ms

The binary

before20.1 ms

after16.4 ms

PRs #1979, #1981, #1961

Edited Bun patches invalidate the cache

bun.lock records a patch by path, so editing the patch leaves the lockfile byte-identical while bun install applies the new one. Without the bun() plugin, vx replayed the old outputs. Core now folds each patch bun.lock names into the key, and --affected widens on its edit.

# after editing patches/left-pad@1.3.0.patch and running bun install
vx run build --all

PR #1904. Docs: Lockfiles.

Breaking changes

vx init and vx-migrate write import type { ProjectConfig } from '@vzn/vx/config' (#2013).
@vzn/vx-migrate adopts Turbo and Nx only: lage(), wireit(), workspaceScripts() and --from lage|wireit|scripts are gone (#2009).
moon support is removed: moon(), mapMoonWorkspace and --from moon (#2008).
vx info --format json and vx mcp’s getWorkspaceInfo gain sandbox.untraced (#2000).
vx init maps a root’s repo-wide scripts to root tasks (#1994).
vx init drops the readyWhen note on a persistent task nothing depends on (#1987).
turbo() caches outputs it proved safe, and the plugin API’s tracked set changed (#1986, #1974).
The npm launcher is CommonJS (#1979).
A bare --affected reads affectedBase first (#1960).
Turbo task tags map to nothing (#1934).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

Starts 2× faster

Wed, 30 Sep 2026 12:00:00 GMT

vx 0.0.200 to 0.0.242 shipped on 2026-09-29 and 09-30. Most of the batch makes turbo() and nx() from @vzn/vx-migrate run more real repos unchanged. Core also starts faster, saves misses faster, and tells you how to fix a task that rewrites its own input.

In this release

Turbo root tasks without a root config
Turbo with sidecars
Turbo env wildcards and framework prefixes
Nx projects outside the package list
Faster startup
Faster cache misses
vx-reapi fails fast when the server is down
A hint for tasks that rewrite their inputs
Sandbox: gitConfig and writes outside the project
vx-mcp takes short run ids

Turbo root tasks without a root config

A //#format task in turbo.json used to need a vx.config.ts at the root, or vx run format --all said no project declares it. Core gained a discover stage, where a plugin names directories that become projects, and turbo() names the root when turbo.json declares a //# task. A single-package Turbo setup, with no workspaces at all, now maps its plain tasks to the root too. The two-line workspace file is all you need:

import type { WorkspaceConfig } from '@vzn/vx/config'
import { turbo } from '@vzn/vx-migrate'

export default { plugins: [turbo()] } satisfies WorkspaceConfig

PRs #1859, #1867. Deep dive: From Turborepo.

Turbo with sidecars

Turbo’s with key (web#dev with api#dev) was a todo, so starting web#dev started no API. Each persistent sidecar is now an edge: vx starts it and runs the task beside it. A task with no script of its own, like the dev in Turbo’s with-tailwind example, becomes a group that starts its sidecars.

vx run web#dev

PRs #1864, #1866. See Turbo and Nx config support.

Turbo env wildcards and framework prefixes

Under turbo(), a * name in env or passThroughEnv (NEXT_PUBLIC_*) now expands over the run’s environment, as Turbo does, instead of leaving the task without those variables. Turbo 2’s framework inference applies too, so a Next.js build gets its NEXT_PUBLIC_* values and no longer inlines empty ones. A !NAME entry removes that name from the list.

NEXT_PUBLIC_API_URL=https://api.example.com vx run build --all

PRs #1896, #1897, #1881.

Nx projects outside the package list

An integrated Nx repo keeps its project.json libraries out of the package manager’s workspace list. nx() attached only the ones that list named: 1 of analogjs’s 21 build tasks. It now names each graph node’s directory through the discover stage, so every project runs, and a root project needs no hand-written config. A warm nx() run also reuses core’s git status for its graph key instead of spawning its own.

vx run build --all

PRs #1862, #1901.

Faster startup

vx --version spent most of its time importing the run path. Every verb now loads on use, run included, so --version went from about 60 ms to 25 ms. A warm no-op run is unchanged.

vx --version

vx --version

before60 ms

after25 ms

PR #1883.

Faster cache misses

Each miss paid async round trips to check where its outputs live and to clean them before the task ran. Those now run synchronously for small sets. A full-miss run of 100 tasks went from 594 ms to 541 ms, and from 979 ms to 898 ms at --concurrency 1.

vx run build --all

Full miss, 100 tasks

before594 ms

after541 ms

Same, --concurrency 1

before979 ms

after898 ms

PRs #1885, #1898.

vx-reapi fails fast when the server is down

Every cache call spent 2.1 s backing off when the REAPI server refused the connection, so a five-task run took 24 s. Once one call has spent its retries, the next ones give up at the first refusal until the server answers again. The same run now takes 2.6 s and falls back to the local cache.

vx run build --all

PR #1887.

A hint for tasks that rewrite their inputs

A task that rewrites one of its own inputs, like TanStack Router’s committed routeTree.gen.ts, is never saved: its key no longer describes the files. The status line named the file but not the fix. It now says to declare the file in cache.outputs:

[vx] app#build: `packages/app/src/routeTree.gen.ts` changed after its key was taken — the result stands, but is not saved under a key that no longer describes it; if the task writes it, declare it in cache.outputs

PR #1877.

Sandbox: gitConfig and writes outside the project

allow.gitConfig was ignored, so .git/config stayed read-only to every sandboxed task. It now reaches the sandbox, for that task only. A dir/ write grant outside the project is created when missing, so a tool can fill a cold cache in your home. When a task fails, vx names the writes the sandbox refused outside the project and the directory to grant.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    compile: {
      exec: {
        command: 'bun build --compile --target=bun-linux-x64 src/bin.ts',
        sandbox: {
          allow: {
            network: ['registry.npmjs.org'],
            write: ['~/.bun/install/cache/', '.*.tmp/**'],
          },
        },
      },
    },
  },
})

PRs #1851, #1875. See What you can grant.

vx-mcp takes short run ids

vx why --run and vx last accept the short id that vx last --list prints. The MCP tool whyDidThisRerun answered “not found” for it. It now resolves ids the same way the CLI does.

ok     2026-10-08T19:56:51.484Z  01a11d17-099c  1 task · 0 hits  148ms  $ vx run build --all

PR #1888. Deep dive: Agents and MCP.

Breaking changes

Plugins: PLUGIN_HOOKS gains discover, after config (#1859).
vx-mcp: whyDidThisRerun’s runId now takes a prefix (#1888).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

Start from Turbo or Nx in one line

Mon, 28 Sep 2026 12:00:00 GMT

vx 0.0.76 through 0.0.199 shipped on 2026-09-27 and 2026-09-28. The theme is adoption: a Turbo or Nx user gets a working setup from vx init, their habits get an answer instead of an error, and the root package can hold tasks. The run footer, vx last and secret masking also got better. Two changes are breaking; they are listed at the end.

In this release

vx init adopts a Turbo or Nx repo
Turbo and Nx habits get an answer
A workspace root can be a project
Narrow a filter by a git range
Exclude paths from outputs
A one-line result row
vx last finds the failure
Mask any secret by name
Scaffold a plugin
JSON Schemas for JSON output

vx init adopts a Turbo or Nx repo

In a repo with turbo.json or nx.json, vx init used to copy scripts into one config per package and drop every edge the repo declared. It now writes only vx.workspace.ts with turbo() or nx(), which read the repo as it is. When it sees a remote cache (TURBO_TOKEN in CI, or a remoteCache in turbo.json), it adds turboCache() or nxCache() too, so the first vx run on CI hits the cache Turbo already filled. The next: line installs what is missing with your package manager.

// vx.workspace.ts, as vx init writes it beside turbo.json
import type { WorkspaceConfig } from '@vzn/vx/config'
import { turbo, turboCache } from '@vzn/vx-migrate'

export default { plugins: [turbo(), turboCache()] } satisfies WorkspaceConfig

flowchart LR
  T["turbo.json or Nx graph"] --> I["vx init"] --> P["one plugin line in vx.workspace.ts"] --> R["vx run build --all"]

PRs #1706, #1801. Docs: Migrate from Turborepo.

Turbo and Nx habits get an answer

Hands trained on Turbo or Nx type turbo build, nx run web:build, --dry-run, -p or --parallel. vx refused each as unknown. Now every Turbo and Nx run flag has one outcome: it works as is, it is an alias, or the error names the vx spelling. A task typed as a verb, and Nx’s project:target, name the vx run to type instead.

$ vx build
vx: `build` is a task here, not a command: vx run build --all
$ vx run app:build
vx run: `app:build` is Nx's project:target: vx run app#build

PRs #1715, #1720, #1768.

A workspace root can be a project

A root task, like codegen or a root tsc -b every package waits on, had no home. A vx.config.ts at the root is now a project: its globs stop at every member, and other tasks can depend on it. --filter // selects it, as in Turbo. turbo() maps Turbo’s //#task keys onto it, and bunx @vzn/vx-migrate writes the root config for them. Five of eleven real Turbo repos had root tasks that were dropped before.

// vx.config.ts at the workspace root
import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    codegen: { exec: { command: 'bun scripts/codegen.ts' } },
  },
})

vx run codegen --filter //

PRs #1646, #1724, #1685, #1827.

Narrow a filter by a git range

A selector followed by a git range, like @scope/*[HEAD] or {./apps/*}[main], was read as one name glob and matched nothing. vx now reads it as Turbo and pnpm do: the selected projects that changed since that ref.

vx run build --filter '{./packages/*}[main]'

PR #1703. Docs: Run and filter.

Exclude paths from outputs

cache.outputs now takes ! entries. A path matched by one is not cleaned, saved, restored or taken from a remote, and vx watch still sees it. A scratch dir inside dist no longer forces a task to run uncached. Turbo and Nx negated outputs map to it.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    build: {
      exec: { command: 'bun run build' },
      cache: {
        inputs: { files: ['src/**'] },
        outputs: { files: ['dist/**', '!dist/tmp/**'] },
      },
    },
  },
})

PRs #1649, #1679. Docs: Caching.

A one-line result row

The footer spread tasks, cache hits and time over three meters. It now ends with one result line: task count, how many were cached, time saved and wall time. It says all cached when every task hit, and puts failures first.

  info      4 workers · local cache
  time      27ms
  result    2 tasks · all cached · 22ms saved · 27ms

PR #1760.

vx last finds the failure

After a green re-run, finding the failure took --list and a copied UUID. vx last --failed replays the latest failed run, and with --list lists only failures. --list prints short run ids, and vx last and vx why take any unique prefix. A failed replay ends with the command that re-runs what failed.

$ vx last --failed
  $ vx run test --all
  3 tasks · 2 hits (2 up-to-date, 0 restored) · 1 failed

  failed (exit 1)   app#test        5ms  a210b23e08eded55  no-cache  0.3× cpu
  up-to-date        lib#build       0ms  18679153744c589a
  up-to-date        app#build       2ms  15f0218ef9e7a02c

  re-run what failed: vx run app#test

PRs #1499, #1385, #1436, #1493. Deep dive: Why did this re-run?

Mask any secret by name

vx masks values of env vars whose names hold TOKEN, SECRET, KEY, PASSWORD, PASSWD or CREDENTIAL, wherever it prints, stores or exports a task’s output or command. That missed names like GH_PAT: a task that echoed it stored the token in its cached log. The new exec.env.secret list masks any name you give it.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    publish: {
      exec: {
        command: 'bun scripts/publish.ts',
        env: { passThrough: ['GH_PAT'], secret: ['GH_PAT'] },
      },
    },
  },
})

PRs #1406, #1532. Docs: Environment variables.

Scaffold a plugin

vx init --plugin <seam> writes plugins/<seam>.ts, a runnable plugin, and a test that drives it through a real run. It covers all nine seams: executor, cache, telemetry, schedule, admit, commands, project, graph and key. The templates are the same examples the repo’s gate runs.

$ vx init --plugin telemetry
wrote plugins/telemetry.ts and plugins/telemetry.test.ts
Declare it in vx.workspace.ts: import { jsonlTelemetry } from './plugins/telemetry.ts', then plugins: [jsonlTelemetry(…)]
Test it: bun test plugins/telemetry.test.ts (needs @vzn/vx installed)

PRs #1415, #1347. Docs: Write one.

JSON Schemas for JSON output

CI scripts and agents parse vx show, vx info, vx why, vx last, vx cache prune --format json, vx run --dry=json and --summarize. Their shapes are now JSON Schemas shipped in node_modules/@vzn/vx/schemas/, and tests hold each output to its schema. vx cache prune gained --format json in the same batch.

vx run build --all --dry=json > plan.json   # schemas/plan.json

PRs #1608, #1675, #1681, #1644.

Breaking changes

vx stats is removed; run vx info, which prints the same report. PR #1392.
defineProject and defineWorkspace reject undeclared keys at type-check time; vx already refused them at load. PRs #1792, #1793.

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

Affected runs that include dependents

Sun, 27 Sep 2026 12:00:00 GMT

vx 0.0.22 through 0.0.75 shipped between 2026-09-15 and 2026-09-27. The theme is adoption and correctness: nx() maps an Nx graph as it is, CI selection does what its name says, and several stale cache hits are gone. A few changes are breaking; they are listed at the end.

In this release

Start from an Nx graph with nx()
Affected runs include dependents
Cache retention
Remote caches stream artifacts
Try vx in the browser
Brackets are literal in task globs
Configs are JSON data
Stale-hit fixes
Faster config reloads in vx watch

Start from an Nx graph with nx()

nx() from @vzn/vx-migrate turns every target in Nx’s resolved project graph into a vx task. You write no config. Executor targets run through nx-exec, one process per executor on Nx’s own runExecutor, and run-commands targets run as the shell commands they are. Configurations become <target>:<configuration> tasks. nx-exec starts in 214 ms against 346 ms for nx run with the daemon warm.

import { defineWorkspace } from '@vzn/vx/config'
import { nx } from '@vzn/vx-migrate'

export default defineWorkspace({ plugins: [nx()] })

Start one executor

nx run, daemon warm346 ms

nx-exec214 ms

PRs #685, #688, #691. Docs: Migrate from Nx. Deep dive: From Nx.

Affected runs include dependents

--affected used to select only the changed projects. On a branch that edited lib, a CI gate ran lib’s tests and skipped app, which depends on it. It now selects the changed projects and everything that depends on them. --filter '[<base>]' keeps the changed-only form, and the new --filter '...^<pattern>' selects a package’s dependents without the package itself.

vx run test --affected=origin/main

flowchart LR
  U["ui changed"] --> UT["ui#test"]
  U --> W["web#test"]
  U --> D["docs#test"]
  style U stroke:#c6f84e,stroke-width:2px

PR #446, commit c148bd6. Docs: Run and filter.

Cache retention

cacheRetention in vx.workspace.ts evicts local cache entries at the end of a run, by the same policy vx cache prune takes as flags. olderThan drops entries unused for that long, then maxSize drops the least recently used past the size. It does work only when something is due.

import { defineWorkspace } from '@vzn/vx/config'

export default defineWorkspace({
  cacheRetention: { olderThan: '30d', maxSize: '10G' },
})

PRs #755, #772. Docs: Workspace config.

Remote caches stream artifacts

A remote cache layer now streams an artifact between disk and the wire instead of holding it in memory. On a 150 MiB round trip, peak memory grew by 45 MiB instead of 495 MiB. Every first-party layer moved with it. If you wrote your own layer, see Breaking changes below.

// a remote cache layer's get and put, as they read today
get(hash: string): Promise<{ body: Blob | Response; durationMs: number | undefined } | null>
put(hash: string, body: Blob, meta: { durationMs: number }): Promise<void>

PRs #756, #761.

Try vx in the browser

The docs site has a “Try it” page that runs vx’s real planner in your browser, bundled from core’s own source. Edit a file, an environment variable or a vx.config.mjs, press Run, and read each task’s key, hit or miss, and why a key moved. Core’s tests hold the page’s plan to what vx run --dry=json prints.

vx run build --all --dry=json

PRs #789, #791, #793, #797. Page: Try it.

Brackets are literal in task globs

A bracket in cache.inputs.files, cache.outputs.files or workspaceFiles now means a bracket. Read as a character class, an input over a Next.js route like app/[id]/ keyed nothing, so an edit replayed an old output. An output over one deleted app/i/page.js and saved nothing. \[id\] still works. CACHE_VERSION moved to v28.

cache: { inputs: { files: ['app/[id]/**'] } }

PR #765.

Configs are JSON data

A project config must be JSON data on every path, because the cache key folds its JSON. A function, symbol, bigint, NaN, Map, Date, cycle or undefined inside an array is refused before the schema, with the path that holds it. Before, vx watch accepted a function that vx run refused, and a Map or Date loaded on both and was keyed as {} or a string. An undefined property is still fine, and vx.workspace.ts is not held to this rule.

vx run build --all

PR #792.

Stale-hit fixes

Two bugs could replay wrong output under a green run. Bun’s xxHash3 reads only 32 bits of a seed, so the key fold carried 32 bits of state and two input sets could share a key. The fold now feeds the seed forward (CACHE_VERSION v29). And npm and Yarn link every workspace package at the root, so a sandboxed task could read its own project through node_modules without the read being reported. That read now fails the task (CACHE_VERSION v30). Each bump makes every entry miss once.

vx run build --all

PRs #775, #806, #812. Deep dive: The sandbox.

Faster config reloads in vx watch

A watch cycle that re-reads configs now starts one config worker for the round, not one per config. With 50 configs a round went from 148 ms to 10.5 ms.

vx watch test --all

Watch round, 50 configs

before148 ms

after10.5 ms

PR #785.

Breaking changes

A bracket in a task glob is a literal character, not a class (#765).
A project config value JSON cannot carry fails to load (#792).
A negated absolute path (!/x) in cache.inputs.files fails to load (#774).
A remote cache layer’s get resolves { body: Blob | Response } and put takes a Blob; a layer that returns bytes is refused (#761).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.

Learn more

The foundation

Sun, 13 Sep 2026 12:00:00 GMT

vx 0.0.1 shipped on 2026-05-13 and 0.0.21 on 2026-09-13. Those 21 releases built the foundation every later one stands on: a task graph from TypeScript configs, a cache keyed on content, and seams for plugins. This post covers what a new user meets, as it shipped then and as it still works today.

In this release

Tasks in TypeScript, one graph
A content-addressed cache
Filters and affected runs
Watch mode
Dev servers in the graph
The sandbox
vx why and vx last
vx lock and frozen runs
Plugins on seams
Adopting from Turborepo and Nx

Tasks in TypeScript, one graph

Each package declares its tasks in a vx.config.ts. A task is one shell command, and dependsOn orders it: '^build' means build in every package this one depends on. vx discovers the projects, evaluates every config, and builds one graph for the whole workspace. A config is a program, so shared settings are an import, not a special field.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    build: {
      dependsOn: ['^build'],
      exec: { command: 'tsc -b' },
      cache: { inputs: { files: ['src/**'] }, outputs: { files: ['dist/**'] } },
    },
  },
})

Commit 4e7e62e. Docs: Tasks and dependencies. Deep dive: Config in TypeScript.

flowchart LR
  C["vx.config.ts"] --> G["task graph"] --> K["cache keys"] --> H{"hit?"}
  H -->|yes| R["restore outputs"]
  H -->|no| X["run, then save"]

A content-addressed cache

Caching is opt-in, and a cached task lists its input files. vx never guesses them. The key folds those files, the task’s resolved config, the package’s package.json, the lockfile and the keys of the tasks it depends on. Tracked, clean files are keyed by the blob ids already in git’s index, so a warm run reads almost nothing. Entries live in a local SQLite index with compressed archives, and a hit restores the outputs and replays the logs.

$ vx run build --all

─ vx 0.0.0 ───────────────────────────────────────────────────
  projects  ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            2 in run · 2 total
  tasks     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            2 success · 2 total
  cache     ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰
            2 up-to-date

  info      4 workers · local cache
  time      32ms
  result    2 tasks · all cached · 45ms saved · 32ms

PRs #7, #86, commit 613d527. Docs: Caching. Deep dives: Explicit over magical, Keys from git, Cascade through inputs.

Filters and affected runs

--filter takes pnpm-style patterns: a name, a glob, a path, a package with its dependencies (app...) or dependents (...lib). --affected selects what changed since a git base, origin/HEAD by default. A change to a workspace-level file that every key folds, such as a lockfile no plugin claims, widens it to every project. A later release made --affected include the changed projects’ dependents too.

vx run test --affected

PRs #58, #210. Docs: CLI.

Watch mode

vx watch runs a task, then runs it again on every change. Each cycle is a normal vx run, so the cache key decides what re-runs, and an edit to an unrelated file costs a fully cached cycle. A task that writes into its own project does not trigger itself: a cycle starts only when file contents differ, not on every event.

vx watch test --all

PR #67. Deep dive: Watch mode.

Dev servers in the graph

exec.persistent marks a server or watcher that does not exit. Its dependents start once it prints a line matching readyWhen, not after a sleep. When the run ends, vx stops the server, and Ctrl-C leaves nothing running.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    dev: {
      exec: { command: 'vite', persistent: { readyWhen: 'Local:' }, timeout: 30_000 },
    },
    e2e: {
      dependsOn: ['dev'],
      exec: { command: 'playwright test' },
    },
  },
})

PRs #62, #189. Docs: Dev tasks. Deep dives: Dev servers in the graph, Ctrl-C.

The sandbox

exec.sandbox runs a task where only what you granted exists. You declare capabilities (read, write, network) and vx maps them to bubblewrap on Linux and the system sandbox on macOS. An undeclared read or write of the task’s own files fails the task and names the path, and a failed task is never cached. That turns an input list from a promise into a checked boundary.

import { defineProject } from '@vzn/vx/config'

export default defineProject({
  tasks: {
    build: {
      exec: {
        command: 'vite build',
        sandbox: { allow: { read: ['.'], write: ['dist/**'] } },
      },
      cache: { inputs: { files: ['src/**', 'index.html'] }, outputs: { files: ['dist/**'] } },
    },
  },
})

PRs #15, #102, #245, commit d7f6e74. Docs: Sandboxing tasks. Deep dive: The sandbox.

vx why and vx last

vx why compares a task’s last two runs and names what moved its key: a file, an env var, a config field, an upstream task. vx last replays a recorded run’s summary from local history. Both read only what the runs already stored.

$ vx why lib#build
lib#build — run 01a11d16-a5b0-74af-a52d-bb0bbf33a1ed
  this run   2026-10-08T19:56:25.939Z · success · executed · key 49a37e4bfb0bd487
  previous   2026-10-08T19:56:18.576Z · cache-hit · up-to-date · key e291b2e50af34f01
  verdict    cache key changed: file packages/lib/src/index.js

  what changed (1 component, 4 unchanged):
    changed file  packages/lib/src/index.js  09b76aaa26ac6afc3f6b09805e8ede78e0637954 → 838198e50b78e865ce6cde1f69d359ffeacc3063

  what to do:
    file  an edit re-runs by design; a file the task does not read belongs out of cache.inputs.files

Commits 7edfaeb, 4013941, PR #333. Docs: Why did it re-run?. Deep dive: Why did this re-run?.

vx lock and frozen runs

vx lock writes every project’s resolved config to vx-lock.json. vx run --frozen builds the graph from that file instead of evaluating configs, and vx lock --check fails when the two drift. Run both in CI and the graph a run sees is the one you reviewed.

$ vx lock
vx lock: locked 2 project configs → vx-lock.json
$ vx lock --check
vx lock --check: up to date (2 projects)

Commit 133a55a. Docs: A frozen graph. Deep dive: vx lock.

Plugins on seams

Core runs and caches on this machine and applies no plugin by default. Everything else is a plugin declared in vx.workspace.ts, named by its package. By 0.0.21 these shipped: @vzn/vx-reapi (remote cache and remote execution on any Bazel REAPI server), @vzn/vx-lockfile (each package keyed on its own dependencies), @vzn/vx-otel (OpenTelemetry), a GitHub Actions job summary (today @vzn/vx-ci), @vzn/vx-mcp (a vx mcp server for coding agents) and @vzn/vx-schedule-history.

import { defineWorkspace } from '@vzn/vx/config'
import { bun } from '@vzn/vx-lockfile'
import { reapi } from '@vzn/vx-reapi'

export default defineWorkspace({
  plugins: [bun(), reapi({ endpoint: 'grpcs://cache.internal:443' })],
})

PR #259, commits 02d6b67, a485690, b5e534d. Docs: Plugins. Deep dives: A pipeline with seams, Remote execution, Lockfile-aware keys, Agents and MCP.

Adopting from Turborepo and Nx

@vzn/vx-migrate covers adoption. Its turbo() plugin runs a Turbo repo under vx with nothing written, reading turbo.json and the package scripts each run. bunx @vzn/vx-migrate writes native vx.config.ts files from turbo.json or an Nx graph, and turboCache() and nxCache() keep an existing remote cache. In any other repo, vx init writes starter configs from the package.json scripts.

bunx @vzn/vx-migrate

PR #302, commit 1487872. Docs: Migrate. Deep dives: From Turborepo, From Nx.

Breaking changes

The package became @vzn/vx, and a project config lists tasks directly, with no run: { tasks } wrapper (#43).

See Upgrading.

How to update

npm install -D @vzn/vx@latest

A standalone binary updates itself with vx upgrade.