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). It also reports every enabled target that agentsmesh generate --targets … left out after a canonical change (staleTargets): its files were not regenerated from the new sources, so check fails until that target is generated again. This catches generated-output drift without running the generators. If a managed location resolves outside the project through a symlink, check stops with an error naming where it resolves to instead of reporting drift.

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

Fixing drift

check prints the fix that matches what it found:

Canonical or generated-output drift: run agentsmesh generate. It regenerates from .agentsmesh/ and records fresh checksums in the lock. It also replaces hand edits to generated files, so put lasting changes in .agentsmesh/.
Locked features changed (collaboration.strategy: lock): plain generate refuses them, so revert the change, or run agentsmesh generate --force to accept it.
The lock has git conflict markers: run agentsmesh merge to rebuild it, then agentsmesh generate. JSON output reports this as lockConflict: true.

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. agentsmesh merge keeps the outputs map when either branch’s lock had one, so a merge does not turn verification off. After a merge, check can report a generated file that only the other branch changed as modified, because the merged lock may keep your branch’s older checksum for it; run agentsmesh generate to record the real checksums. Only a merge of two locks without an outputs map gives a lock in this old format.

Unreadable lessons graph

In project scope, check also fails (exit 1) when .agentsmesh/lessons/lessons.json exists but cannot be read, or is still in an unfinished git merge, even if the lock is in sync. The error starts with Lessons graph unreadable: and names the cause and the next step:

Merge conflict — the file has git conflict markers. Run agentsmesh lessons resolve, then git add the file. check also fails when git still holds lessons.json unmerged and the file is missing lessons from the other branch (for example, the merge driver could not run). Run agentsmesh lessons resolve before git add, or the other branch’s lessons are dropped.
Corrupt — the JSON cannot be parsed. Keep a copy, then repair it or restore the last committed graph from git.
Schema — the file is valid JSON but does not match the lessons schema. The error lists the first problems. Keep a copy, then fix those fields by hand or restore the last committed graph from git.
Newer version — the graph was written by a newer agentsmesh. Upgrade agentsmesh.

A project without a lessons graph is not affected. See agentsmesh lessons.

CI integration

- 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 — or the project’s lessons graph cannot be read.

The MCP check tool mirrors this in its result payload, exposing canonicalDrift, outputDrift, outputsModified, outputsRemoved, outputsStale, staleTargets, outputsChecked, lockConflict (true when the lock has git conflict markers; run agentsmesh merge), and lessonsGraphError. That field holds the same text as the CLI JSON error when .agentsmesh/lessons/lessons.json cannot be read, so the MCP tool and agentsmesh check fail on the same things; it is null otherwise.

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.