vmn

A version number that can rebuild your repo.

Language-agnostic semantic versioning where a version is a restorable state, not just a label.
Designed for AI-assisted development. Versions live in git tags — no database, no server, no lock-in.

_{Works with any language in a git repository — vmn versions the repo, not the build system.}

pip install vmn

vmn stamp -r patch my_app        # => 0.0.1   (auto-initializes, no setup)

# ...six months and 400 commits later, prod is broken on 0.0.1

vmn goto -v 0.0.1 my_app         # your repo AND every dependency repo,
                                 # exactly as they were when 0.0.1 shipped

Other versioning tools produce a string. vmn produces a state you can return to — across every repository your product spans, not just the one you run it in.

The same property is what makes vmn a natural fit for AI-assisted development: give each agent an isolated workspace, capture what it produced, and roll back what didn't work.

All state is stored as plain YAML in git annotated tag messages. Remove vmn and the tags remain fully readable.

vmn has been in continuous development since 2019 and versions its own releases. It is in daily production use by teams shipping multi-repository products, where recovering from a bad release means restoring every repo to a known state, not just one.

Install · The idea · AI agents · Why vmn · Commands · Config · Experiments · Web UI · Islands · CI · Help · Migrate

📦 Install

pip install vmn          # or: pipx install vmn / uvx vmn
pip install "vmn[ui]"    # + the web dashboard

Requirements: Python 3.8+, Git 2.10+ (2.17+ recommended). Linux, macOS, Windows/WSL. Nothing platform-specific to configure.

vmn is a Python CLI, but the project it versions can be in any language — it operates on git tags, not on your build system.

mkdir remote && cd remote && git init --bare && cd ..
git clone ./remote ./local && cd local
echo a >> ./a.txt && git add ./a.txt && git commit -m "first commit" && git push origin master

vmn stamp -r patch my_app   # => 0.0.1

echo b >> ./a.txt && git add ./a.txt && git commit -m "feat: add b" && git push origin master
vmn stamp -r patch my_app   # => 0.0.2

git tag -n1 my_app_0.0.2    # the version metadata is right there in the tag

vmn --completion-install      # auto-detects your shell, idempotent
vmn --completion              # or just print the script, change nothing
vmn --completion-uninstall    # remove it again

💡 The idea

Most tools treat a version as a name for a moment. vmn treats it as a handle on a state — and once you have that, the same primitive answers four different problems.

Each of the first three rows extends the one above it; the fourth materializes any of them as a separate tree. These are not four separate features: vmn exp is built on the snapshot primitive, and snapshots share the version grammar of stamps. That is why vmn goto -v 1.2.0-dev.a1b2c3d.e4f5g6h works — a snapshot is a version.

1.6.0                        # release
1.6.0-rc.23                  # prerelease
1.6.7.4                      # hotfix — an optional 4th segment
1.6.0-rc.23+build01.Info     # build metadata
1.6.0-dev.a1b2c3d.e4f5g6h    # dev snapshot (commit hash + diff hash)

🤖 Built for AI-assisted development

Coding agents are fast, parallel, and occasionally destructive. Each of those properties creates a state problem — and state is what vmn manages.

The tool documents itself to the agent. vmn skill --install writes vmn usage instructions into your agent's instruction file — .claude/skills/vmn/SKILL.md, .cursorrules, or AGENTS.md. The agent learns your versioning workflow from the tool that implements it rather than inferring it from the repo. The cursor and agents targets write a marker-delimited block, so re-running updates vmn's section and leaves the rest of your instructions untouched.

vmn skill --install                  # Claude Agent Skill
vmn skill --install --target cursor  # .cursorrules
vmn skill --install --target agents  # AGENTS.md

Every agent gets its own island. One command creates a git worktree for your repo and every dependency repo, pinned to a known-good state, alongside your work rather than in place of it. Agents working in separate islands cannot touch each other's files.

vmn worktrees create my_app --island-name agent-auth
vmn worktrees create my_app --island-name agent-perf

Each island includes an island.json manifest — paths, branches, dependency hashes — so an agent can orient itself without being told the layout. Use --no-stamp for a read-only island when the agent shouldn't create versions at all.

Recoverable by default. Agents leave behind uncommitted edits, half-finished refactors, and untracked scratch files — state that git stash and WIP commits handle poorly. vmn snapshot create captures all of it, across every dependency repo, as a named version you can return to. Restore operations snapshot whatever is currently dirty before overwriting it, so uncommitted work is never silently destroyed.

Keep the good run reproducible. When an agent iterates on something measurable — a prompt, a heuristic, a model — vmn exp run records the metrics and the exact tree that produced them. Identifying run 14 as the best one is still useful a month later, because run 14's code remains addressable.

The full text of the instructions vmn installs is in docs/agent-skill.md.

⚡ Why vmn

Bold rows are things only vmn does. _{* changesets authors offline but needs GitHub/npm to publish.}

🔧 Commands

Global flags: --debug, --version, --completion[-install|-uninstall] [SHELL]

stamp

vmn stamp -r patch my_app             # => 0.0.1
vmn stamp -r minor my_app             # => 0.1.0
vmn stamp -r patch --pr rc my_app     # => 0.1.1-rc.1
vmn stamp my_app                      # no -r needed with conventional_commits
vmn stamp --dry-run -r patch my_app   # preview, commit nothing
vmn stamp --pull -r patch my_app      # pull first, retry on conflict

Idempotent — it won't re-stamp a commit that already has a version. Auto-initializes the repo and app on first run.

git commit -m "feat: add search endpoint"
vmn stamp my_app     # => 0.2.0, minor inferred

conf:
  conventional_commits: true
  default_release_mode: optional   # or "strict"
  changelog:
    path: "CHANGELOG.md"
  github_release:
    draft: false

release

vmn release my_app                  # auto-detect from the current commit
vmn release -v 0.0.1-rc.1 my_app    # explicit version — tag only
vmn release --stamp my_app          # full stamp flow: commit + tag + push

Promotes a prerelease to final. Idempotent. -v and --stamp are mutually exclusive.

vmn stamp -r major --pr alpha my_app   # 2.0.0-alpha.1
vmn stamp --pr alpha my_app            # 2.0.0-alpha.2
vmn stamp --pr mybeta my_app           # 2.0.0-mybeta.1
vmn release my_app                     # 2.0.0

show

vmn show my_app              # current version
vmn show --verbose my_app    # full YAML metadata
vmn show --dev my_app        # dev version (commit + diff hash)
vmn show --type my_app       # release / prerelease / metadata
vmn show -u my_app           # unique ID (version + commit hash)
vmn show --root my_platform  # root-app version (an integer)

goto

vmn goto -v 1.2.3 my_app                        # repo + all deps
vmn goto my_app                                 # latest on the current branch
vmn goto -v 1.2.3 --deps-only my_app            # dependencies only
vmn goto -v 5 --root my_platform                # by root-app version
vmn goto -v 1.2.0-dev.a1b2c3d.e4f5g6h my_model  # restore a dev snapshot
vmn goto -v 1.2.3 --pull my_app                 # fetch first if not found locally

Missing dependency repos are cloned automatically, in parallel. Restoring a dev version checks out the base commit, replays local commits, then applies the working-tree patch.

snapshot

Capture your exact working state — uncommitted changes, unpushed commits, untracked files, across every dependency — as a deterministic version you can restore. No WIP commits, no stash management.

Use it when: you're hours into a refactor that half-works and want to try a different approach without losing this one. Committing pollutes history with work you may discard; git stash gives you an unnamed entry with no record of dependency state. A snapshot gives you a version string — try the other approach, and if it's worse, restore.

Also useful for: sharing a bug that only reproduces with your local debug changes; saving your state before an agent edits the same files.

vmn snapshot create my_app --note "promising results"
# => 1.2.0-dev.a1b2c3d.e4f5g6h

vmn snapshot list my_app
vmn snapshot diff my_app -v 1.2.0-dev.a1b   # second side defaults to your working tree
vmn snapshot restore my_app --latest        # dirty work is auto-saved first

.vmn/{app}/snapshots/{version}/
  metadata.yml            # version, branch, timestamp, note, dirty states
  working_tree.patch      # uncommitted changes (git diff HEAD)
  local_commits.patch     # commits not yet pushed
  untracked_files.tar.gz  # untracked files
  deps/{dep_name}/...     # the same three, per dependency repo
  artifacts/{filename}    # attached files

gen

vmn gen -t version.j2 -o version.txt my_app
vmn gen -t version.j2 -o version.txt -c custom.yml my_app

Template variables: version, base_version, name, release_mode, prerelease, previous_version, stamped_on_branch, release_notes, changesets, root_name, root_version, root_services.

add

vmn add -v 0.0.1 --bm build42 my_app
vmn add -v 0.0.1 --bm build42 --vmp ./build.yml --vmu https://ci/build/42 my_app

Attaches build metadata to an existing tag (0.0.1+build42). --vmp records a path to a YAML metadata file; --vmu an associated URL.

config

vmn config                       # list all managed apps
vmn config my_app                # interactive TUI
vmn config my_app --vim          # open in $EDITOR
vmn config --branch my_app       # override for the current branch
vmn config --root my_platform    # root-app config
vmn config --global              # repo-level .vmn/conf.yml

vmn config gen my_app                              # .vmn/my_app/conf.yml
vmn config gen --branch my_app                     # branch config, seeded from the effective conf
vmn config gen --branch --root my_platform         # branch config for a root app
vmn config gen --branch --sync-dep-branches my_app # pin each branch-tracked dep to its current branch

skill

Emits vmn's own usage instructions for AI coding agents — see Built for AI-assisted development.

vmn skill --install                     # .claude/skills/vmn/SKILL.md (default)
vmn skill --install --target cursor     # .cursorrules
vmn skill --install --target agents     # AGENTS.md
vmn skill --install --methodology       # + opinionated TDD / worktree rules
vmn skill --install --force             # overwrite an existing Claude SKILL.md
vmn skill                               # just print it

--install resolves the managed repo root even from a nested directory. The Claude target refuses to overwrite an existing skill without --force; the Cursor and AGENTS targets rewrite only vmn's marker block and preserve the rest of the file. Full text: docs/agent-skill.md.

from version_stamp.cli.entry import vmn_run

ret, ctx = vmn_run(["show", "my_app"])

⚙️ Configuration

vmn writes .vmn/<app>/conf.yml when an app is first stamped. Edit it directly or via vmn config.

conf:
  template: '[{major}][.{minor}][.{patch}][.{hotfix}][-{prerelease}][.{rcn}][-dev.{dev_commit}.{dev_diff_hash}][+{buildmetadata}]'
  hide_zero_hotfix: true
  extra_info: false
  create_snapshots: false
  conventional_commits: true
  default_release_mode: optional   # "optional" (--orm) or "strict" (-r). Top-level, not nested.
  changelog:
    path: "CHANGELOG.md"
  github_release:
    draft: false
  deps:
    ../:
      other_repo:
        vcs_type: git
  version_backends:
    npm:
      path: "package.json"
  policies:
    whitelist_release_branches: ["main"]
  snapshot_storage:
    backend: local
    bucket: my-bucket
    prefix: vmn-snapshots
    endpoint_url: https://...
  experiment:
    metrics:
      loss: { goal: min, primary: true }
      acc:  { goal: max }
    storage:            # same shape as snapshot_storage; CLI flags override
      backend: local

version_backends:
  npm:
    path: "relative/path/to/package.json"

version_backends:
  generic_selectors:
    - paths_section:
        - input_file_path: in.txt
          output_file_path: in.txt
      selectors_section:
        - regex_selector: '(version: )(\d+\.\d+\.\d+)'
          regex_sub: \1{{version}}

version_backends:
  generic_jinja:
    - input_file_path: f1.jinja2
      output_file_path: jinja_out.txt
      custom_keys_path: custom.yml

[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "vcs"
tag-pattern = "my_app_(?P<version>.*)"

.vmn/<app>/branch_conf/<branch>/conf.yml        # slashes in the branch name
.vmn/<app>/branch_conf/<branch>/root_conf.yml   # become real directories

🧬 Experiments

Local-first experiment tracking for any versioned app. Experiments are plain files under .vmn/{app}/experiments/ — git-ignored, never committed or pushed. No server, no database, no account.

Use it when: you're tuning something over days — hyperparameters, a cache policy, a retrieval prompt, compiler flags — editing code between runs. Two weeks later, "what did we change to get 0.91?" is unanswerable, because the tree that produced it was overwritten twenty runs ago. An experiment pins each result to the exact code that produced it, so exp diff shows the metric delta and the source change side by side.

Also useful for: benchmark and load-test runs where the configuration is the variable; agent-driven iteration loops; any workflow where many attempts produce one keeper.

# Capture code state, run the command, record metrics + exit code + duration
vmn exp run my_model --note "baseline CNN" -- python train.py
# => 0.1.0-dev.a1b2c3d.e4f5g6h

# Change the model, run again — a distinct experiment, even on the same commit
vmn exp run my_model --note "with dropout" -- python train.py

# Leaderboard, best loss first
vmn exp list my_model --sort loss --top 3

# Metric delta AND a real source diff between two runs
vmn exp diff my_model

# Winner — restore that exact state (dirty work auto-saved first)
vmn exp restore my_model --latest

No training script required. An experiment is a tree snapshot plus a metrics log — ML training is one use case; config sweeps, benchmarks, and load tests work identically.

Your command reports metrics by appending key=value lines to $VMN_METRICS_FILE. Prefix a line with step=N to build a per-step series — vmn tails the file during the run, so training curves appear live in the web UI.

experiment:
  metrics:
    loss:     {goal: min, primary: true}   # lower is better; default sort key
    val_loss: {goal: min}
    acc:      {goal: max}

📖 Full experiments guide → — the metrics protocol, structured params, addressing, S3 storage, and the no-script workflow.

🖥️ Web UI

A dashboard over data you already have. It reads git tags and .vmn/ files directly; the whole SPA ships inside the wheel.

pip install "vmn[ui]"
vmn ui               # http://127.0.0.1:8265, opens your browser

• Leaderboard — sortable, goal-aware metric columns; @N indices matching the CLI.
• Run detail — params vs. metrics, live training curves, full log, copy-paste reproduce commands.
• Compare — pick two runs for a metric-delta table plus a color-coded code diff.
• Stamp tree — your version history as a DAG, colored by release mode, with root-app topology and cross-repo dependency pins. No experiment tracker has this — it falls out of vmn's git-tag model.
• Actions — run stamp / restore / goto / release / prune from the browser. Each runs as a real vmn subprocess, so it takes the repo lock correctly and streams its log live.

vmn ui --host 0.0.0.0 --port 8265 \
       --token "$VMN_UI_TOKEN" \
       --data-dir /srv/vmn-ui \
       --repo /srv/checkouts/model-a --repo /srv/checkouts/model-b

📖 Full UI guide →

🏝️ Islands (parallel worktrees)

An island is a set of git worktrees — your main repo plus every dependency — pinned to a known-good state, sitting beside your work instead of on top of it.

Use it when: you want three agents working on three features at once in a product that spans four repos. Doing that by hand means a git worktree add per repo per feature, with every dependency checked out at the exact hash the last good version recorded — twelve checkouts, each re-derived from tag metadata. One vmn worktrees create per feature does it, and agents in separate islands cannot touch each other's files.

Also useful for: reproducing a customer bug on 2.1.0 while your current work stays where it is — vmn goto would move your checkout, an island provides that state alongside it. Or a disposable --no-stamp island for a risky experiment.

vmn worktrees create my_app                                    # from current HEAD, auto-named
vmn worktrees my_app                                           # 'create' is the default action
vmn worktrees create my_app --island-name feat-auth -fv 2.1.0  # from a version
vmn worktrees create my_app --island-name feat-perf -fb develop # from a branch
vmn worktrees create my_app --island-name ci-test --no-stamp   # read-only: stamping disabled
vmn worktrees list
vmn worktrees remove feat-auth                                 # removes worktrees and branches

../vmn-islands/                # configurable with --base-path
  feat-auth/
    my_project/                # main repo — git worktree on a new branch
    auth_service/              # dep — git worktree, detached HEAD
    payment_gateway/           # dep — git worktree, detached HEAD
    island.json                # machine-readable manifest

🔄 CI

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0          # required — vmn reads tags and history
  - uses: progovoy/vmn-action@latest
    with:
      app-name: my_app
      do-stamp: true
      stamp-mode: patch
    env:
      GITHUB_TOKEN: ${{ github.token }}

fetch-depth: 0 is not optional — vmn computes the next version from git history and tags.

🔍 Troubleshooting

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

rm .vmn/vmn.lock            # default location
# or, if VMN_LOCK_FILE_PATH is set:
rm "$VMN_LOCK_FILE_PATH"

🔀 Coming from another tool?

Your existing tags keep working — vmn uses its own {app}_{version} format and won't collide with v1.2.3-style tags.

Every version, restorable.

pip install vmn

If vmn is useful to you, consider starring the repo. Found a problem? File an issue.

_{Add the badge to your project:}
[![vmn: automatic versioning](https://img.shields.io/badge/vmn-automatic%20versioning-blue)](https://github.com/progovoy/vmn)