agentsmesh lint

Validate canonical files against target-specific constraints. Targets can register per-feature linters on top of the shared rule checks — Cursor validates .mdc format compliance, Gemini CLI warns that project permissions need --global, Kiro explains the scope its embedded permission rules apply in — and every target checks for valid frontmatter.

Usage

agentsmesh lint [flags]

Flags

Flag	Description
`--global`	Lint canonical home config under `~/.agentsmesh/`.
`--targets <csv>`	Limit linting to specific target IDs.

Examples

Lint for all configured targets

agentsmesh lint

Lint for specific targets

agentsmesh lint --targets cursor
agentsmesh lint --targets claude-code,gemini-cli

Lint home-level config

agentsmesh lint --global --targets claude-code

What lint checks

All targets

Valid YAML frontmatter in all .md files
No duplicate rule/command/agent names
Required fields present (root: true in _root.md, description in agents)
Valid targets values (must be known target IDs)
Valid globs patterns (syntactically valid gitignore patterns)

Claude Code

The shared rule validation above. Claude Code registers no per-feature lint hooks, so there is no settings.json schema check and no tool-name or permissionMode validation.

Cursor

.mdc frontmatter format compliance
Valid trigger values for Cursor rules

MCP servers

Valid JSON in mcp.json
Required fields per server type (command for stdio, url for HTTP)

Hooks

Valid hook event types (PreToolUse, PostToolUse, etc.)
Required fields (matcher, type)
Valid type values (command, prompt)

Lessons subsystem

When .agentsmesh/lessons/lessons.json is present, lint validates the canonical graph and the procedural rule:

lessons.json parses as valid JSON matching the graph schema.
Graph integrity: no dangling lesson→topic / lesson→trigger / supersededBy refs.
No duplicate rule text (normalized: whitespace-collapsed, lowercased).
Status invariants: superseded requires a supersededBy; active forbids it.
Trigger patterns are safe: a command_pattern the linear regex engine cannot run (UNSAFE_TRIGGER_PATTERN) or a file_glob outside the safe glob subset (UNSAFE_GLOB_PATTERN) is an error.
Orphan topics/triggers (warning only).
_root.md contains the ## Lessons (…) procedural rule heading.

These checks run only when the lessons subsystem is scaffolded (agentsmesh init --lessons). Projects without lessons are unaffected.

The same integrity checks are available standalone via agentsmesh lessons validate.

Cross-target diagnostics (warnings)

These checks run against every configured target and are emitted as warnings — they do not fail lint’s exit code, but they surface contract gaps that would silently bite at generation time.

silent-drop-guard — flags canonical content (rules, commands, agents, skills, hooks, permissions, ignore) that a target would drop without trace because its capability for that feature is none (or partial in cases where the dropped subset is detectable). Lets you see what each target will actually emit before running generate.
hook-script-references — when a hook command references a script path (e.g. ./scripts/pre-commit.sh), warns for every target that does not copy hook scripts into its generated tree (currently every target except Copilot). The script must already exist relative to the hook execution directory or the generated config will fail at runtime.
rule-scope-inversion — flags canonical rules whose activation scope (globs: / alwaysApply:) contradicts a target whose projection rules force always-on (or vice versa), so you don’t end up with a rule that silently always activates on a target that should respect manual scoping (e.g. Cursor manual rules).

These run automatically. Existing configs may surface new warnings on first lint after upgrading — particularly hook-script-references for any non-Copilot target whose hook commands reference scripts.

Exit codes

Code	Meaning
`0`	No lint errors found.
`1`	One or more lint errors.

Integrating with CI

Add lint to your CI pipeline alongside check:

- name: Lint AgentsMesh config
  run: agentsmesh lint

- name: Check AgentsMesh sync
  run: agentsmesh check

This catches both config errors and drift in the same pipeline.