Skip to main content
momentic 3.0 drops Node.js 20, retires the legacy v1 AI agents, and removes a few config options that are now handled automatically. This guide covers the breaking changes and how to upgrade.
This guide is for the web CLI (momentic). Mobile (momentic-mobile) has its own v1 upgrade guide. If your repo has both, upgrade each separately.

​
1. Use Node.js 22

momentic 3.0 requires Node.js 22 or newer — Node.js 20 has reached end of life and is no longer supported. Check your version and upgrade if needed: 
node --version   # must be v22 or newer
Update the Node version in your CI images and any .nvmrc / engines field before upgrading.

​
2. Run the upgrade

From your web project root: 
npx momentic@latest upgrade
This installs the latest CLI and applies the current recommended project defaults. Pass --dry-run first to preview what would change without writing anything.

​
3. Breaking changes

Each of these requires an edit if your project uses the affected feature:
  • Legacy v1 AI agents removed. The v1 locator, assertion, visual assertion, and text extraction agents have been retired. A run that pins one of these in ai.agentConfig in momentic.config.yaml now errors — switch those entries to a current version (see AI configuration).
  • browser.bustCacheOnBoundingBoxChange removed. The element cache is now invalidated automatically when an element’s bounding box changes, so the setting is no longer needed. Remove it from momentic.config.yaml.
  • --record-video flag removed. Use --video instead (--video true to keep every recording, --video false to disable). Recording now defaults to on-fail: a video is captured for every run but kept only when the test fails.
  • AI Action steps default to the V3 agent. The older V2 agent is marked “Legacy” and can no longer be selected for new AI Action steps in the editor. Existing V2 steps continue to run unchanged.

​
4. New-project defaults

These apply to projects created with momentic init and do not change existing projects, but are worth knowing:
  • Hybrid selectors are enabled by default (browser.hybridSelectorMode: prefer).
  • New projects set browser.disableSecondaryCacheResolution: true.
  • New projects pin each AI agent to the latest exact sub-version so defaults don’t drift when a newer revision ships.
  • The bundled Playwright is updated to 1.60.0.
Set any of these explicitly in momentic.config.yaml to override the default.