agentsmesh check

Verify that the canonical files still match the lock file (.agentsmesh/.lock). Designed for CI pipelines — exits with code 1 if generated files have drifted.

Usage

agentsmesh check

agentsmesh check --global

Flags

Flag	Description
--global	Check ~/.agentsmesh/.lock instead of the current project lock.
--no-outputs	Skip generated-output verification and only check canonical-source drift. Useful in CI setups that deliberately gitignore generated outputs, where every output would otherwise report as removed after checkout.

What drift means

agentsmesh check verifies two independent kinds of drift, and exits with code 1 if either is detected.

Canonical-source drift

The .agentsmesh/ sources no longer match the checksums recorded in .agentsmesh/.lock. This is reported as modified, added, or removed canonical files (plus changed extends sources and locked-feature violations). It happens when:

• Someone edited .agentsmesh/ but forgot to run agentsmesh generate
• A pull request merged changes to canonical config without regenerating
• An extends source changed and the project hasn’t refreshed

Generated-output drift

A generated file (.claude/, .cursor/, AGENTS.md, etc.) was hand-edited, deleted, or added unexpectedly under a configured target’s managed output locations. When agentsmesh generate runs, it records an outputs map in the lock — a checksum of every generated file it wrote or verified. agentsmesh check re-hashes those files on disk and reports any that were changed (outputsModified) or deleted (outputsRemoved), then scans managed locations for files absent from the lock (outputsStale). This catches generated-output drift without running the generators.

JSON output exposes the two drift classes directly as canonicalDrift and outputDrift; the per-path arrays remain available for actionable diagnostics.

Old-format locks

Locks written before generated-output tracking existed have no outputs map. For those, output verification is skipped and check prints:

Generated-output verification skipped; run 'agentsmesh generate' to refresh the lock and enable it.

Running agentsmesh generate once upgrades the lock and enables output verification on subsequent checks. A run of agentsmesh merge intentionally omits the outputs map (a merge changes canonical inputs), so verification is reported as skipped until you regenerate.

CI integration

.github/workflows/ci.yml

- name: Verify AI config is in sync
  run: agentsmesh check

This step fails the build if generated files are out of date with canonical sources.

For user-level config checks, run agentsmesh check --global on a machine that owns the home-level AgentsMesh config.

Full CI example

name: CI

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: agentsmesh lint
      - run: agentsmesh check

Exit codes

Code	Meaning
0	Canonical sources and recorded generated outputs both match the lock.
1	Drift detected — canonical sources or generated outputs are out of sync.

The MCP check tool mirrors this in its result payload, exposing canonicalDrift, outputDrift, outputsModified, outputsRemoved, outputsStale, and outputsChecked.

Difference between check and generate --check

• agentsmesh check — fast: reads the lock and re-hashes files only. Covers both canonical-source drift and drift in the generated outputs recorded in the lock. Does not run the generators.
• agentsmesh generate --check — slower: runs the full generation pipeline and compares output to what’s on disk. Additionally catches output differences caused by generator or version changes over otherwise-unchanged sources.

For CI pipelines where speed matters, use agentsmesh check. Use generate --check when you want to verify the full generation path.