Skip to content

Setup: init, build, watch, hook

vouch init

Set up vouch.toml, the store and vouch.sty.

$ vouch init [--paper FILE] [--hook] [--agents [PARTS]] [--stop-gate] [--yes] [--root DIR]
Flag Meaning
--paper FILE the paper's main .tex (default: detected)
--hook also install the git pre-commit hook
--agents [PARTS] set up Claude Code: skill,rules,hook,mcp (default when the flag is bare: skill,rules,hook)
--stop-gate with --agents: also block finishing until vouch check --strict passes
--yes write without asking
$ vouch init
  wrote vouch.toml (paper: paper/main.tex)
  copied vouch.sty to paper/vouch.sty
  add to the preamble of paper/main.tex:  \usepackage{vouch}
  marked generated files in .gitattributes
next: record values in your experiments, cite them as \vouch{key}, run `vouch build`

Writes vouch.toml, detects the main .tex, copies vouch.sty, adds .gitignore entries (.vouch/cache/), and prints the \usepackage line to add. See Claude Code for what --agents installs.

In a project that already has vouch.toml, vouch init is a refresh, and the fix vouch check gives for sty-outdated after an upgrade. It keeps vouch.toml, replaces an outdated vouch.sty beside each paper, adds vouch's .gitattributes lines if they are missing, and installs no hook or agent files unless --hook or --agents asks. It prints the next steps only for a new project.

$ vouch init
  vouch.toml exists; left unchanged
  updated paper/vouch.sty to this version of vouch

vouch build

Evaluate vouch_values.py, render the values file, tables and provenance CSV (if provenance_csv is set) and catalog, refresh source annotations if enabled, auto-acknowledge new/hidden/reformatted/moved changes, and print the change block.

$ vouch build [--json] [--no-notify] [--root DIR]
Flag Meaning
--json machine-readable summary
--no-notify don't run the on_change hook
$ vouch build
vouch build: evaluated vouch_values.py (6 definitions) -> .vouch/derived.json
vouch build: paper/main.tex
  wrote: paper/vouch-values.tex (284 values, 2 claims, 1 tables; 22 citations)

Before there is a paper, leave [[paper]] out of vouch.toml. build still evaluates the values modules and writes the catalog, and vouch check gates the store and reports every run that no longer matches its code, as a warning:

$ vouch build
vouch build: evaluated vouch_values.py (3 definitions) -> .vouch/derived.json
vouch build: no [[paper]] in vouch.toml, so no paper files: experiments only; .vouch/CATALOG.md lists 41 recorded or derived value(s) and claim(s) from 2 run(s)
$ vouch check
vouch check: no [[paper]] (experiments only) · 2 runs, 0 not fresh
✓ OK

A [[paper]] whose main file does not exist yet is an error for build and check.

vouch watch

Keep vouch build running for you. vouch watch builds once, then rebuilds whenever something it depends on changes, and after each rebuild prints the values that moved.

$ vouch watch [--interval SEC] [--then CMD] [--no-notify] [--quiet] [--root DIR]
Flag Meaning
--interval SEC seconds between polls (default 1)
--then CMD run CMD after each build that wrote files, e.g. "latexmk -pdf paper/main.tex"
--no-notify don't run the on_change hook
--quiet one line per build (plus errors and moved values) instead of the full build report

What triggers a rebuild:

  • a run record appears or changes in .vouch/runs/ (an experiment finished, or vouch run/vouch import recorded values)
  • vouch.toml
  • the values modules (vouch_values.py)
  • any .tex file of any paper, including files \input later

The files the build writes (values file, tables, CSV, .vouch/derived.json, the catalog) never trigger a rebuild. The watcher polls file timestamps with the standard library, so it behaves the same on every OS and on network filesystems. It never runs an experiment; it only re-renders what was recorded. When a build fails (a half-written vouch_values.py, a typo in vouch.toml), it prints the error and keeps watching.

$ vouch watch --quiet --then "latexmk -pdf -cd paper/main.tex"
[18:28:19] vouch watch: building, then watching for new values (Ctrl-C to stop)
  wrote 3 file(s)

[18:28:24] .vouch/runs/train.json changed
  4 value(s) moved since the last build:
    run train
        ● toy.centroid.acc      79.3 ± 3.1% → 77.8 ± 3.8%   ↓ Δ -1.56 pts, -2.0% relative   worse
        ● toy.centroid.n_test   50 → 120   ↑ Δ +70, +140.0%   ! large move (140%)
    derived
        ● toy.gain              29.3 → 28.9   ↓ Δ -0.4444, -1.5%   worse
    claims
        ● toy.gain_over_10      HOLDS → HOLDS   ! margin 1.93 → 1.89
  wrote 3 file(s); 4 pending change(s): `vouch review`
  ✓ latexmk -pdf -cd paper/main.tex

Values marked ● are cited in the paper. The line format is the same as vouch diff. More in Comparing runs and live rebuilds.

vouch hook

Git pre-commit hook (install), or the Claude Code hook entry points (claude, stop).

$ vouch hook install [--strict] [--force]
$ vouch hook claude          # reads a Claude Code PostToolUse payload from stdin
$ vouch hook stop            # reads a Claude Code Stop payload from stdin
Flag Meaning
--strict the hook runs check --strict
--force replace an existing pre-commit hook
$ vouch hook install
installed .git/hooks/pre-commit: runs `vouch check --quiet` before each commit

vouch hook claude and vouch hook stop are the entry points vouch init --agents wires into .claude/settings.json; see Claude Code.