# Claude Code Integration — Hooks

This page shows how to configure a [Claude Code hook](https://code.claude.com/docs/en/hooks) that validates a widget after each file edit (`PostToolUse`).

**The hook is optional.** The main path is to call the `widgets-validate` Tool, which the generation workflow already does (`modyo://docs/widgets/reference-generation-workflow`). The hook only automates that call. The `widgets-*` tools and the `widgets-init-project` Prompt do not depend on it.

Where Claude Code reads hooks from:

| File | Scope |
|------|-------|
| `~/.claude/settings.json` | Every project on your machine |
| `.claude/settings.json` | The project; read from the folder where Claude Code is started |

---

## Option 1 (recommended) — run `widgets-validate` from the hook

A hook of type `mcp_tool` calls a tool of a connected MCP server. Put this in the widget project's `.claude/settings.json` and start Claude Code at the widget root, so the hook only runs while you work on that widget:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "modyo",
            "tool": "widgets-validate",
            "input": {
              "projectPath": "/path/to/my-widget"
            }
          }
        ]
      }
    ]
  }
}
```

**Adapt:**
- `"server"`: the name of the Modyo MCP server as you configured it in Claude Code.
- `"projectPath"`: the absolute path to the widget root, the folder that contains its `package.json` and `widget.manifest.json`. `widgets-validate` validates a whole widget, not a single file, so the path is fixed instead of taken from the edited file.

**Behavior:**
- The hook runs `widgets-validate` with the same rules and the same `stack-alignment` check as a direct call. Reading the report: `modyo://docs/widgets/reference-validator-rules`.
- If the MCP server is not connected when the hook runs, Claude Code reports a non-blocking hook error and continues.

---

## Option 2 — run the validator with `npx`

Useful when the Modyo MCP server is not connected in Claude Code, or when one hook should cover every widget under a folder. It runs the validator's CLI, which applies the same validator rules but **not** the `stack-alignment` check that `widgets-validate` adds.

### Use the same validator version as the MCP

Every `widgets-validate` report has a `version` field: the version of the validator the MCP runs. Use that version in the command, `npx @modyo/widget-validator@<version>`. Without a version, `npx` runs the latest published release, which may apply different rules.

### Snippet

Put this in `~/.claude/settings.json`. Adapt `ROOT` to the folder that holds your widgets (one widget per subfolder, with the trailing `/`), and `<version>` to the `version` of a `widgets-validate` report. The folder is compared and cut as plain text, not as a pattern, so names with spaces, parentheses or other special characters work; only a single quote (`'`) in the name needs escaping:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "ROOT='/path/to/my-widgets/'; FILE=$(jq -r '.tool_input.file_path // empty'); case \"$FILE\" in \"$ROOT\"*) REST=${FILE#\"$ROOT\"}; WIDGET=\"$ROOT${REST%%/*}\"; OUT=$(npx @modyo/widget-validator@<version> \"$WIDGET\" 2>&1) || { echo \"$OUT\" | tail -40 >&2; exit 2; } ;; esac"
          }
        ]
      }
    ]
  }
}
```

**How it works:**
1. Claude Code passes the event as JSON on stdin; `jq` reads the edited file's path from `tool_input.file_path`.
2. The `case` only continues for files under `ROOT`. Any other edit is ignored.
3. `${FILE#"$ROOT"}` removes the `ROOT` prefix and `${REST%%/*}` keeps the first folder after it, so `WIDGET` is the widget root (`/path/to/my-widgets/<widget>`).
4. The validator's CLI exits with 1 when the report has errors and 0 otherwise.
5. On errors, the hook writes the last 40 lines of the report to stderr and exits with 2: Claude Code then shows that output to Claude. With exit 0 (no errors, warnings allowed) nothing is shown.

**Requirements:**
- `jq` on the `PATH`.
- `node` and `npx` on the `PATH`. Node 22 or later (the validator's `engines`).
- Network access to npm on the first run; later runs use the npm cache.

To start faster, install that version globally once (`npm install -g @modyo/widget-validator@<version>`) then call `modyo-widget-validator` instead of `npx @modyo/widget-validator@<version>`.

---

## Other MCP clients

This page covers Claude Code. Other clients have different hook mechanisms, or none. See `modyo://docs/widgets/_meta-integration-README`.
