CMG

CMG

CMG is a browser automation CLI for producing choreographed, human-readable, pointer-accurate visual evidence.

It drives a real browser from scripts, test files, or one-shot CLI commands. When you ask it to record a GIF, CMG shows the journey with a live virtual pointer, real pointer events, hover states, drag ghosts, captions, and partial recordings when something fails. The result is automation evidence that people can understand quickly and agents can parse reliably.

Why CMG

Most browser automation tools prove that something happened. CMG is designed to show how it happened.

• Pointer-accurate GIFs: clicks, hovers, typing, scrolls, drags, offsets, captions, and drag ghosts are recorded through CMG's virtual pointer path.
• Visual evidence by default when you ask for it: use --gif for a whole run, or a gif { ... } block for a focused moment.
• Readable scripts: .cmgscript is intentionally compact, whitespace-tolerant, and friendly to AI-generated browser control.
• Tests and browser control: use cmg run for structured tests, reports, retries, traces, and sharding; use browser control script when an agent needs to control the browser directly.
• Useful failures: failed steps include the action, line number, and reason in stderr, reports, and traces.
• Broad automation without hiding the story: browser control, assertions, locators, frames, network, storage, files, screenshots, accessibility, and visual checks are covered in the action index, but recorded runs still look like a guided browser journey.

CMG is not trying to be a clone of Cypress, Puppeteer, or Playwright. It gives you the automation coverage you expect, but its center of gravity is different: CMG creates inspectable visual evidence that reads like a guided browser performance.

When To Use CMG

The useful difference is not "CMG has aliases like other tools." The useful difference is that CMG turns automation into evidence that a human can watch and an agent can reason about.

Token-Efficient Agent Execution

CMG can execute a complete, already-decided browser journey from one compact script and return concise numbered step results. An agent does not need to request and ingest a full DOM or accessibility snapshot between every click, fill, wait, assertion, and screenshot, and CMG does not require another model inference to interpret each deterministic action.

click "getByRole=button|Clone"
fill "getByLabel=Repository URL" "https://github.com/example/repo.git"
click "getByRole=button|Start"
waitForText "#status" "Complete"
screenshotPage output="result.png"

That is what CMG means by token-efficient: the execution protocol is compact. The installed agent skill follows the same principle. Its SKILL.md is a short routing guide, while full command documentation and demos are packaged as on-demand files under references/ so an agent only loads the leaf page needed for the current task.

Install And Run Locally

From this repository:

dotnet build /p:UseSharedCompilation=false
dotnet run -- browser launch

Published command examples use cmg:

cmg browser launch

The official Windows release is self-contained: it includes the .NET runtime and a checksum-pinned LGPL FFmpeg executable beside CMG.exe for MP4 evidence export. Its CMG, FFmpeg, OpenH264, and build-system licenses are included under licenses/, with exact source links in THIRD-PARTY-NOTICES.txt. Repository builds do not download third-party binaries; they use a configured FFmpeg path, CMG_FFMPEG, or PATH when MP4 output is requested.

Runtime dependencies are deliberately narrow:

• Install at least one supported browser: Chrome, Edge, or Firefox. CMG controls the installed browser directly and does not require a separate WebDriver.
• The official Windows ZIP needs no separate .NET or FFmpeg installation.
• Electron or WebView2 automation requires the target desktop app and its normal runtime; CMG does not bundle third-party applications.
• PowerShell, Git, Node.js, Python, ImageMagick, and Azure tooling are not CMG runtime requirements.

While developing in this repo, replace cmg with dotnet run --.

60-Second Happy Path

cmg browser launch
cmg browser control script --file demo.cmgscript --gif demo.gif
cmg run tests --report-html report.html

That is the shape of CMG: launch a controlled browser, drive it with readable scripts, record visual proof when useful, and run structured tests when you need reports.

For the full three-path walkthrough, see the Quick Start.

Make Your First GIF

Create first-gif.cmgscript:

navigate "C:\Projects\CMG\index.html"
waitForElement "#openProfileDialog" timeout=5000
step "Open the profile dialog" {
  click "#openProfileDialog"
}
type "#profileName" "My first CMG GIF"

Run it with GIF recording:

cmg browser launch
cmg browser control script --file first-gif.cmgscript --gif demo-output\first-gif.gif

The GIF shows the visible browser viewport, the virtual pointer moving to the target, pointer events firing against the page, typed text appearing progressively, and the step caption.

Write Your First Test

Create first-test.cmgscript:

suite "profile dialog" {
  beforeEach {
    navigate "C:\Projects\CMG\index.html"
    waitForElement "#openProfileDialog" timeout=5000
  }

  test "opens and captures the dialog" tag=smoke {
    step "Open dialog" {
      click "#openProfileDialog"
    }

    expectVisible "#profileDialog"
    expectText "#lastDialogAction" "None"

    gif "dialog evidence" {
      type "#profileName" "CMG Test Profile"
      screenshot "#profileDialog" output="demo-output\profile-dialog.png"
    }
  }
}

Run the test with reports and whole-test GIFs:

cmg run first-test.cmgscript --gif demo-output\gifs --report-html demo-output\report.html --report-json demo-output\report.json

When --gif is used, CMG records the entire selected test and suppresses nested gif block files. The nested actions still run and appear in the whole-test GIF.

Script Or Test?

Both script types use the same action syntax, control flow, macros, locators, GIF behavior, and virtual pointer model. The runner adds suites, hooks, selection, retries, sharding, reports, and per-test traces. See Script vs Runner for the longer comparison.

Learn More

• Docs overview
• Quick Start
• Command reference
• Scripting guide
• Script vs Runner
• Action index
• GIF recording
• Script style guide
• Runnable demos

Documentation For Agents

CMG is intended to be called by AI agents. Command docs include arguments, options, stdout, stderr, exit codes, and examples. Scripting docs include syntax, action behavior, error handling, migration notes, and style guidance.

When adding or changing a command or scripting feature, update docs/ in the same change.