AI agents

An agent asks vx what to run, runs it, and learns why it failed, all as typed JSON. People get the same answers as text.

bunx skills add vznjs/vx
vx last --failed --format json

---

Set up your agent

1. Install the vx skill

   One SKILL.md teaches any coding agent to run tasks, read failures and query the workspace as JSON:

   bunx skills add vznjs/vx

2. Give it the docs

   llms.txt indexes every page as markdown; llms-full.txt is all of them in one file. Add .md to any page’s path for its markdown. vx docs <query> prints the matching reference sections for your vx’s version.

3. Let it run tasks

   The same commands as yours:

   vx run build --all
   vx run test --affected=origin/main

   Outside a terminal vx prints plain lines. A run with no task name fails and lists the tasks, instead of opening the picker.

---

Every question has a command

Question	Command
What can I run here?	vx show --format json
What would run, and why?	vx run test --dry=json
Run these tasks and tell me how it went.	vx run test, then vx last --format json
Why did the run fail, at which file and line?	vx last --failed --format json
What did a task print?	vx last --log app#test
Why did this task run again?	vx why app#test --format json
What does a task declare?	vx show app#test --format json
What is this workspace?	vx info --format json
What ran, how fast, what flaked?	vx last --stats --format json
Is the lock current? What would vx init do?	vx lock --check --format json, vx init --dry --format json
Free cache space.	vx cache clean --max-size 1G --dry-run

---

Read answers as JSON

Each --format json prints one JSON document to stdout; notices go to stderr, so stdout always parses. Every shape is a JSON Schema in the package’s schemas/, with a closed key set.

--dry=json under --affected gives each task the reason it was kept. A failed row of vx last --format json carries the task’s output and the files it names (locations). vx why --format json gives each changed part of the key, so an agent fixes the cause instead of re-running:

{"kind":"file","name":"packages/app/src/a.ts","change":"changed","before":"d00491fd7e5bb6fa28c517a0bb32b8b506539d4d","after":"0cfbf08886fca9a91cb753ec8734c84fcbe52c9f"}

---

Branch on exit codes and error codes

Exit	Means
0	Every task passed or was a cache hit, or nothing was affected.
1	A task failed or was skipped, or vx refused the command (see below).
130 / 143 / 129	Interrupted by SIGINT / SIGTERM / SIGHUP; vx stopped every task first.

A refused command asked for JSON prints one line with a stable code, and exits 1. Branch on the code, not the message:

$ vx run biuld --all --dry=json
{"ok":false,"error":{"code":"VX_E_UNKNOWN_TASK","message":"vx run: no projects declare task(s): biuld. Did you mean build?","docs":"https://vznjs.github.io/vx/cli/#vx_e_unknown_task"}}

Code	What to do
VX_E_UNKNOWN_TASK	Read the task names from vx show --format json.
VX_E_USAGE	Fix the flag or argument; vx help <verb> lists them.
VX_E_CONFIG	Fix the config file named in the message.
VX_E_NO_HISTORY	Run the task first; vx why and vx last need a run.
VX_E_INTERNAL	A defect in vx: report it with the stack from stderr.

docs links the code’s section of the CLI reference; vx docs VX_E_UNKNOWN_TASK prints it.

Tip

A mistyped flag gets the right one back: --concurency hints --concurrency, and --json hints --format json.

---

Next

Machine-readable outputEvery JSON shape vx prints.

Error codesEvery code, and what to do.