VX - Universal Development Tool Manager#

One-sentence summary: vx = prefix any dev tool command with vx → it auto-installs the tool and runs it.

vx is a universal development tool manager that automatically installs and manages development tools (Node.js, Python/uv, Go, Rust, etc.) with zero configuration.

Core Concept#

Instead of requiring users to manually install tools, prefix any command with vx:

bash

vx node --version      # Auto-installs Node.js if needed
vx uv pip install x    # Auto-installs uv if needed
vx go build .          # Auto-installs Go if needed
vx cargo build         # Auto-installs Rust if needed
vx just test           # Auto-installs just if needed

vx is fully transparent - same commands, same arguments, just add vx prefix.

Essential Commands#

Tool Execution (most common)#

bash

vx <tool> [args...]           # Run any tool (auto-installs if missing)
vx node app.js                # Run Node.js
vx python script.py           # Run Python (via uv)
vx npm install                # Run npm
vx npx create-react-app app   # Run npx
vx cargo test                 # Run cargo
vx just build                 # Run just (task runner)
vx git status                 # Run git
vx gh pr status               # Run GitHub CLI

Git and GitHub for Codex#

When Codex or another AI agent works in a vx-managed repository, use vx-managed Git and GitHub CLI commands. Do not run bare git or bare gh.

bash

vx git status --short --branch
vx git fetch origin main
vx git checkout -B fix/example origin/main
vx git diff --stat
vx git add path/to/file
vx git commit -m "fix: example"

vx gh issue view 123
vx gh pr view 456 --json title,state,headRefName
vx gh pr checks 456
vx gh run view 789 --json status,conclusion,jobs

Token-Efficient Agent Workflows#

vx is not just an installation wrapper. For agents, it is the stable way to use fast search, structured GitHub queries, JSON filters, and scoped diffs without spending tokens on irrelevant output.

Prefer narrow, structured commands before broad dumps:

bash

# Search and file discovery
vx rg -n --glob '!target/**' --glob '!node_modules/**' "OutputRenderer"
vx rg --files -g '*.rs' -g '!target/**'
vx fd provider.star crates/vx-providers

# Git context with small output first
vx git status --short --branch
vx git diff --stat
vx git diff --name-only origin/main...HEAD
vx git grep -n "CommandOutput" origin/main -- crates/vx-cli

# GitHub context with selected fields
vx gh issue view 123 --json title,state,labels,body
vx gh pr view 456 --json title,state,headRefName,baseRefName,files
vx gh pr checks 456 --json name,state,conclusion,link
vx gh run view 789 --json status,conclusion,jobs
vx gh run view 789 --json jobs --jq '.jobs[] | {name,conclusion,startedAt,completedAt}'
vx gh run view 789 --log | vx rg -n -m 80 "error|failed|panic|Traceback|warning"

# Structured filtering
vx jq -r '.files[].path' pr.json
vx yq '.jobs | keys' .github/workflows/ci.yml

Token-saving defaults for agents:

• Start with vx rg, vx fd, vx git diff --stat, and vx git diff --name-only; open full files or full diffs only after locating the relevant surface.
• Use vx gh --json ... with selected fields, and add --jq when a small projection is enough.
• Use vx structured output flags when the vx command supports them: --json, --fields, --toon, --compact, or --output-format toon|compact.
• For forwarded runtimes like vx node, vx cargo, or vx npm, use that tool's own quiet, JSON, or filtering flags when available.
• Pipe large logs through vx-managed filters such as vx rg, vx jq, or vx yq before reading them.
• Use vx --compact <tool> ... only when you still need broad subprocess output after structured fields and grep-style filters are not enough. It preserves vx transparency unless explicitly requested.
• Do not expect default vx git or vx gh forwarding to shrink output; explicit --json, --jq, filtering, or --compact is what saves tokens.

Compression decision tree for CI/log triage:

1. Status only: vx gh run view <run> --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'.
2. Suspected failure: vx gh run view <run> --log | vx rg -n -m 80 "error|failed|panic|Traceback|FAILED|warning".
3. Broad but bounded context: vx --compact gh run view <run> --log.
4. Last resort: full raw logs, preferably saved to a file and searched locally before being pasted into an agent prompt.

Observed on a successful 5,589-line GitHub Actions run: selected gh --json --jq projection was about 500 tokens, raw gh --log output was about 226k tokens, and vx --compact gh --log was about 15.9k tokens. That makes semantic selection the default, compact mode the fallback for broad context, and raw logs the exception.

Agent Operating Principles#

vx skills should help agents make small, correct, maintainable changes with bounded context. Treat vx as a token-aware execution layer, not just a command prefix.

Use this loop for coding tasks:

1. Inspect the narrowest relevant file, symbol, diff, log, or test output first.
2. Prefer existing project patterns over new helpers or abstractions.
3. Make the smallest maintainable change that solves the actual request.
4. Validate with the cheapest useful scoped command for the risk involved.
5. Summarize only what changed, what was checked, and any remaining risk.

Context discipline:

• Scope before printing. Search paths first, then open focused file sections.
• Avoid dumping full files, broad diffs, generated output, or full CI logs unless the task truly requires them.
• For unknown or potentially huge output, cap and filter with vx-managed tools.
• Do not cap instruction files, skill files, or agent policy files; read the relevant one fully unless it is unexpectedly huge.
• If capped output is insufficient, narrow the query before increasing the cap.

Examples:

bash

vx rg -n -m 20 "render_token_savings|OutputRenderer" crates/vx-cli crates/vx-metrics
vx git diff --stat origin/main...HEAD
vx git diff --name-only origin/main...HEAD
vx gh run view 789 --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'
vx gh run view 789 --log | vx rg -n -m 50 "error|failed|panic|Traceback|FAILED"
vx --compact gh run view 789 --log
vx metrics tokens --last 20 --json

Validation discipline:

• Use focused checks first, such as vx cargo test -p vx-cli --test cli_parsing_tests <case>.
• Run broader checks only when the touched surface or release risk justifies it.
• Prefer evidence from the actual failing command, CI job, or runtime behavior over speculative fixes.
• Do not add wrappers, maps, helper files, or validation layers unless they clearly reduce real complexity.

Tool Management#

bash

vx install node@22            # Install specific version
vx install uv go rust         # Install multiple tools at once
vx list                       # List all available tools
vx list --installed           # List installed tools only
vx versions node              # Show available versions
vx switch node@20             # Switch active version
vx uninstall go@1.21          # Remove a version

Project Management#

bash

vx init                       # Initialize vx.toml for project
vx sync                       # Install all tools from vx.toml
vx setup                      # Full project setup (sync + hooks)
vx dev                        # Enter dev environment with all tools
vx run test                   # Run project scripts from vx.toml
vx check                      # Verify tool constraints
vx lock                       # Generate vx.lock for reproducibility

Environment & Config#

bash

vx env list                   # List environments
vx config show                # Show configuration
vx cache info                 # Show cache usage
vx search <query>             # Search available tools
vx info                       # System info and capabilities

Managed Plain Commands#

Use vx <runtime> for ordinary execution. When a user needs a plain command outside vx dev (for example an editor invoking a CLI), use a managed command shim instead of maintaining a handwritten wrapper.

First check vx --version and the command list in vx --help. Only if shim is listed, check vx shim --help and vx shim add --help: the required interface is add/list/remove/sync/path. Release v0.9.34 predates this interface; a merged PR alone does not mean the installed binary supports it.

Read the managed command shim guide before creating or repairing entries. It covers Codex package targets, safe --as/ --dir selection, Windows shells, PATH precedence, upgrade sync, and ownership checks. Do not default to --force or change global PATH. vx shim codex, bare vx shim, and vx shim rebuild are not this interface.

Project Configuration (vx.toml)#

Projects use vx.toml in the root directory:

toml

[tools]
node = "22"         # Major version
go = "1.22"         # Minor version
uv = "latest"       # Always latest
rust = "1.80"       # Specific version
just = "*"          # Any version

[scripts]
dev = "vx npm run dev"
test = "vx cargo test"
lint = "vx npm run lint && vx cargo clippy"
build = "vx just build"

[hooks]
pre_commit = ["vx run lint"]
post_setup = ["vx npm install"]

AI Skills Maintenance#

vx ai setup installs vx's built-in skills globally by default so every agent session can reuse the same guidance:

bash

vx ai setup                 # Install/update global agent skills
vx ai setup --project       # Install project-local skills and record hash in vx.toml
vx ai setup --project --force
vx ai check                 # Compare vx.toml [ai].skills_hash with embedded skills

For project-local skills, vx ai setup --project records the current embedded skills hash in vx.toml. If vx ai check reports stale skills, refresh them with vx ai setup --project --force before continuing project work.

Legacy Python 2.7/3.7 Projects#

vx can run modern and legacy Python lines side by side:

bash

vx python@3.12 --version
vx python@3.7 --version
vx python@2.7 --version

Python 3.7+ uses vx-managed CPython builds where available. Python 2.7 uses the vx legacy compatibility path backed by PyPy2.7 portable archives, so mention the PyPy caveat when a project depends on CPython-only native extensions.

For virtual environments, keep one environment per Python line. When uv receives a simple --python version through vx, vx resolves it to the vx-managed interpreter path before forwarding to uv. Python 2.7 is a special legacy case: uv requires Python 3.6+, so vx uv venv ... --python 2.7 uses PyPA's Python 2.7 virtualenv.pyz under the hood while preserving the same command shape:

bash

vx uv venv .venv312 --python 3.12
vx uv venv .venv37 --python 3.7
vx uv venv .venv27 --python 2.7

Use just to make the workflow repeatable:

makefile

venv37:
    vx uv venv .venv37 --python 3.7
    vx uv pip install --python .venv37 -r requirements-py37.txt

venv27:
    vx uv venv .venv27 --python 2.7
    .venv27/bin/python -m pip install -r requirements-py27.txt

test37: venv37
    .venv37/bin/python -m pytest

test27: venv27
    .venv27/bin/python -m pytest

test-legacy: test37 test27

On Windows, use .venv37\Scripts\python.exe and .venv27\Scripts\python.exe in justfile recipes.

Multi-Version Test Matrices#

For projects that support multiple runtime lines, keep the matrix in justfile instead of ad hoc commands. Use explicit runtime versions for Node/npm and explicit virtual environments for Python:

makefile

test-node18:
    vx node@18 npm test

test-node20:
    vx node@20 npm test

test-node22:
    vx node@22 npm test

test-py37: venv37
    .venv37/bin/python -m pytest tests/py37

test-py312: venv312
    .venv312/bin/python -m pytest tests/py312

test-matrix: test-node18 test-node20 test-node22 test-py37 test-py312

Agents should prefer vx just test-matrix or vx run test-matrix when a project defines it, and should add a matrix recipe when compatibility support is part of the task.

Using --with for Multi-Runtime#

When a command needs additional runtimes available:

bash

vx --with bun node app.js     # Node.js + Bun in PATH
vx --with deno npm test        # npm + Deno available

Package Aliases#

vx supports package aliases — short commands that automatically route to ecosystem packages:

bash

# These are equivalent:
vx vite              # Same as: vx npm:vite
vx vite@5.0          # Same as: vx npm:vite@5.0
vx rez               # Same as: vx uv:rez
vx pre-commit        # Same as: vx uv:pre-commit
vx meson             # Same as: vx uv:meson
vx release-please    # Same as: vx npm:release-please

Benefits:

• Simpler commands without remembering ecosystem prefixes
• Automatic runtime dependency management (node/python installed as needed)
• Respects project vx.toml version configuration

Available Aliases:

Short CommandEquivalentEcosystemvx vite``vx npm:vitenpmvx release-please``vx npm:release-pleasenpmvx rez``vx uv:rezuvvx pre-commit``vx uv:pre-commituvvx meson``vx uv:mesonuv

Companion Tool Environment Injection#

When vx.toml includes tools like MSVC, vx automatically injects discovery environment variables into all subprocess environments. This allows any tool needing a C/C++ compiler to discover the vx-managed installation.

toml

# vx.toml — MSVC env vars injected for ALL tools
[tools]
node = "22"
cmake = "3.28"
rust = "1.82"

[tools.msvc]
version = "14.42"
os = ["windows"]

Now tools like node-gyp, CMake, Cargo (cc crate) automatically find MSVC:

bash

# node-gyp finds MSVC via VCINSTALLDIR
vx npx node-gyp rebuild

# CMake discovers the compiler
vx cmake -B build -G "Ninja"

# Cargo cc crate finds MSVC for C dependencies
vx cargo build

Injected Environment Variables (MSVC example):

VariablePurposeVCINSTALLDIRVS install path (node-gyp, CMake)VCToolsInstallDirExact toolchain pathVX_MSVC_ROOTvx MSVC root path

MSVC Build Tools (Windows)#

Microsoft Visual C++ compiler for Windows development:

bash

# Install MSVC Build Tools
vx install msvc@latest
vx install msvc 14.40       # Specific version

# Using MSVC tools via namespace
vx msvc cl main.cpp -o main.exe
vx msvc link main.obj
vx msvc nmake

# Direct aliases
vx cl main.cpp              # Same as: vx msvc cl
vx nmake                    # Same as: vx msvc nmake

# Version-specific usage
vx msvc@14.40 cl main.cpp

Available MSVC Tools:

ToolCommandDescriptionclvx msvc clC/C++ compilerlinkvx msvc linkLinkerlibvx msvc libLibrary managernmakevx msvc nmakeMake utility

Supported Tools (164 Providers)#

CategoryToolsJavaScriptnode, npm, npx, bun, deno, pnpm, yarn, vite, nx, turboJS Toolingoxlint, biomePythonuv, uvx, python, pip, ruff, maturin, pre-commitRustcargo, rustc, rustupGogo, gofmt, gws, goreleaser, golangci-lintSystem/CLIgit, bash, curl, pwsh, jq, yq, fd, bat, ripgrep, fzf, starship, jj, sd, eza, dust, duf, xh, atuin, zoxide, tealdeer, gping, delta, hyperfine, watchexec, bottomTUI/Terminalhelix, yazi, zellij, lazygit, lazydocker, k9sBuild Toolsjust, task, cmake, ninja, make, meson, xmake, protoc, buf, conan, vcpkg, spackDevOpskubectl, helm, flux, kind, k3d, nerdctl, skaffold, podman, terraform, hadolint, dagu, actionlintSecuritygitleaks, trivy, cosign, grype, syftCloud CLIawscli, azcli, gcloud**.NETdotnet, msbuild, nugetC/C++msvc, llvm, nasm, ccache, buildcache, sccache, rceditMediaffmpeg, imagemagickJavajavaAIollama, openclaw, mcpcallOther LangszigContainerdiveConfig Mgmtchezmoi, misePackage Managersbrew, choco, wingetData/APIduckdb, grpcurlMisc**gh, prek, actrun, wix, vscode, xcodebuild, systemctl, release-please, rez, 7zip, trippy

Provider System (Starlark DSL)#

All 164 Providers are defined using provider.star (Starlark DSL) — a declarative, zero-compilation approach. Each provider lives in crates/vx-providers/<name>/provider.star.

vx uses a two-phase execution model (inspired by Buck2):

1. Analysis Phase (Starlark): provider.star runs as pure computation, returning descriptor dicts. No I/O.
2. Execution Phase (Rust): The Rust runtime interprets descriptors for actual downloads, installs, and process execution.

How to add a new tool#

starlark

# crates/vx-providers/mytool/provider.star
load("@vx//stdlib:provider.star", "runtime_def", "github_permissions")
load("@vx//stdlib:provider_templates.star", "github_rust_provider")

name        = "mytool"
description = "My awesome tool"
ecosystem   = "custom"

runtimes = [runtime_def("mytool", aliases=["mt"])]
permissions = github_permissions()

# Use a template — covers 90% of tools
_p = github_rust_provider("owner", "mytool",
    asset = "mytool-{vversion}-{triple}.{ext}")
fetch_versions   = _p["fetch_versions"]
download_url     = _p["download_url"]
install_layout   = _p["install_layout"]
store_root       = _p["store_root"]
get_execute_path = _p["get_execute_path"]
environment      = _p["environment"]

Available templates#

TemplateUse caseExamplegithub_rust_providerRust tools on GitHub (most common)ripgrep, fd, bat, just, uvgithub_go_providerGo tools on GitHub (goreleaser style)gh, taskgithub_binary_providerSingle binary download (no archive)kubectlsystem_providerSystem package manager only7zip

Template Placeholders#

PlaceholderRust templateGo templateDescription{version}✓✓Version number (e.g., "1.0.0"){vversion}✓—With v-prefix (e.g., "v1.0.0"){triple}✓—Rust target triple (e.g., "x86_64-unknown-linux-musl"){os}—✓Go GOOS (linux, darwin, windows){arch}—✓Go GOARCH (amd64, arm64){ext}✓✓Archive extension (zip/tar.gz){exe}✓✓Executable suffix (.exe/"")

Starlark Standard Library (14 modules)#

Located in crates/vx-starlark/stdlib/. The main entry point is provider.star which re-exports everything:

starlark

# Import everything from the unified facade
load("@vx//stdlib:provider.star",
     "runtime_def", "bundled_runtime_def", "dep_def",
     "github_permissions", "platform_map",
     "env_set", "env_prepend",
     "archive_layout", "binary_layout")

Key modules:

• provider.star — Unified facade (re-exports all)
• runtime.star — runtime_def, bundled_runtime_def, dep_def
• platform.star — platform_map, platform_select, rust_triple, go_os_arch
• env.star — env_set, env_prepend, env_append, env_unset
• layout.star — archive_layout, binary_layout, bin_subdir_layout, hooks
• provider_templates.star — High-level templates (4 templates)
• permissions.star — github_permissions, system_permissions
• system_install.star — winget_install, brew_install, apt_install

Important Rules for AI Agents#

1. Always use vx prefix when running tools in vx-managed projects
2. Use vx just instead of just for task runner commands
3. Use vx npm instead of npm directly
4. Use vx cargo instead of cargo directly
5. Use vx git instead of git for repository operations
6. Use vx gh instead of gh for GitHub issue, PR, checks, and workflow operations
7. Use vx rg, vx fd, vx jq, and vx yq for scoped search and structured filtering
8. Prefer token-efficient output: --json, selected fields, --jq, --toon, --compact, --output-format toon|compact, and narrow globs
9. Check vx.toml first to understand project tool requirements
10. Use vx run <script> for project-defined scripts
11. Never suggest manual tool installation - vx handles it automatically
12. Commands like vx install are for explicit pre-installation; normal usage auto-installs
13. Use correct terminology: Runtime (not Tool), Provider (not Plugin), provider.star (not provider config)
14. Provider development: New tools are added via provider.star Starlark DSL in crates/vx-providers/<name>/
15. Tests go in tests/ dirs — never inline #[cfg(test)] in source files

Version Resolution Priority#

vx resolves tool versions in this order (highest to lowest):

1. Command-line override: vx node@22 app.js
2. Project vx.toml: [tools] node = "22"
3. Parent directory vx.toml (traverses up to root)
4. User global config: ~/.config/vx/config.toml
5. Provider default: latest stable version

MCP Integration#

vx is MCP-ready — replace npx/ uvx with vx in MCP server configurations. This eliminates the "install Node.js/Python first" requirement for all MCP servers.

Configuration Pattern#

json

{
  "mcpServers": {
    "example-server": {
      "command": "vx",
      "args": ["npx", "-y", "@example/mcp-server@latest"]
    },
    "python-server": {
      "command": "vx",
      "args": ["uvx", "some-python-mcp-server@latest"]
    }
  }
}

Real-World MCP Examples#

json

{
  "mcpServers": {
    "filesystem": {
      "command": "vx",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "vx",
      "args": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "<token>" }
    },
    "sqlite": {
      "command": "vx",
      "args": ["uvx", "mcp-server-sqlite", "--db-path", "/path/to/db.sqlite"]
    }
  }
}

Testing MCP Servers with mcpcall#

Use the built-in mcpcall provider for scriptable MCP smoke tests. Prefer compact vx output plus mcpcall JSON output when agents need concise logs:

bash

vx install mcpcall@0.4.0
vx --compact mcpcall list --url http://127.0.0.1:8765/mcp --json
vx --compact mcpcall doctor --url http://127.0.0.1:8765/mcp --json
vx --compact mcpcall call --url http://127.0.0.1:8765/mcp dcc_status --json

Migration Pattern#

Originalvx-powered"command": "npx"``"command": "vx", "args": ["npx", ...]``"command": "uvx"``"command": "vx", "args": ["uvx", ...]``"command": "node"``"command": "vx", "args": ["node", ...]``"command": "python"``"command": "vx", "args": ["python", ...]``"command": "bun"``"command": "vx", "args": ["bun", ...]

Benefits for AI Agents#

• Zero-config: No need to check if Node.js/Python is installed before starting MCP servers
• Version consistency: MCP servers always use the version specified in vx.toml
• Cross-platform: Same MCP config works on Windows, macOS, and Linux
• CI/CD ready: MCP servers in CI pipelines just work with vx

GitHub Actions Integration#

vx provides a GitHub Action ( action.yml) for CI/CD workflows. Use it in .github/workflows/ files:

Basic Usage#

yaml

- uses: vx-org/vx@main
  with:
    version: 'latest'           # vx version (default: latest)
    github-token: ${{ secrets.GITHUB_TOKEN }}

Pre-install Tools#

yaml

- uses: vx-org/vx@main
  with:
    tools: 'node go uv'         # Space-separated tools to pre-install
    cache: 'true'               # Enable tool caching (default: true)

Project Setup (vx.toml)#

yaml

- uses: vx-org/vx@main
  with:
    setup: 'true'               # Run `vx setup --ci` for vx.toml projects

Full Example#

yaml

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]

    steps:
      - uses: actions/checkout@v6

      - uses: vx-org/vx@main
        with:
          tools: 'node@22 uv'
          setup: 'true'
          cache: 'true'

      - run: vx node --version
      - run: vx npm test

Action Inputs#

InputDefaultDescriptionversion``latestvx version to installgithub-token``${{ github.token }}GitHub token for API requeststools``''Space-separated tools to pre-installcache``trueEnable caching of ~/.vx directorycache-key-prefix``vx-toolsCustom prefix for cache keysetup``falseRun vx setup --ci for vx.toml projects

Action Outputs#

OutputDescriptionversionThe installed vx versioncache-hitWhether the cache was hit

Container Image Support#

vx also provides a container image for containerized workflows, and it can be consumed from Podman-compatible environments:

dockerfile

# Use vx as base image
FROM ghcr.io/vx-org/vx:latest

# Tools are auto-installed on first use
RUN vx node --version
RUN vx uv pip install mypackage

Multi-stage Build with vx#

dockerfile

FROM ghcr.io/vx-org/vx:latest AS builder
RUN vx node --version && vx npm ci && vx npm run build

FROM nginx:alpine
COPY --from=builder /home/vx/dist /usr/share/nginx/html

GitHub Actions Container Jobs#

yaml

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/vx-org/vx:latest
    steps:
      - uses: actions/checkout@v6
      - run: vx node --version
      - run: vx npm test

---

Delivery Surface — External Systems Are Evidence#

GitHub PRs, CI runs, and dashboards are supporting evidence, not the delivery surface. The conclusion has to land where the work is tracked.

• Record the outcome once, completely — one issue comment carrying status, branch/commit/PR, what you validated, the blocker, and the next owner.
• Verify terminal state, not intermediate state. A green CI run or an open, review-ready PR is not "shipped". Confirm merged / released / deployed, then record that.
• Keep public surfaces public-safe. PR titles, bodies, and commit messages carry technical content only — no internal issue IDs, routing history, reviewer handoffs, local absolute paths, or internal hostnames.
• Collect results in the foreground. A queued or pending state is a handoff, not a completion; never end a turn "standing by" for background work.

Concretely: the delivery surface is the team's issue or task tracker — the issue comment plus its metadata. A PR comment alone delivers nothing.