---
draft: false
title: agentsmesh lint
description: Validate canonical files against target-specific constraints. Catches frontmatter errors, format violations, and schema issues before generation.
---

Validate canonical files against target-specific constraints. Each target has its own linting rules — for example, Cursor requires `.mdc` format compliance, Claude Code validates `settings.json` schema, and all targets check for valid frontmatter.

## Usage

```bash
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

```bash
agentsmesh lint
```

### Lint for specific targets

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

### Lint home-level config

```bash
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

- `settings.json` schema validation
- Valid `permissionMode` values (`ask`, `default`, `none`)
- Valid tool names in `allowed-tools` and `permissions.yaml`

### 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.
- 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`:

```yaml
# .github/workflows/ci.yml
- 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.
