---
url: /integrations/claude-code-plugin.md
description: >-
  Install claudelint as a Claude Code plugin to access validation skills
  directly inside Claude Code sessions via slash commands.
---

# Claude Code Plugin

This guide covers how to install and use claudelint as a Claude Code plugin.

## Installation

### Prerequisites

The plugin's skills run claudelint CLI commands under the hood. Install the npm package first:

**Global** makes `claudelint` available in every project. **Project-local** pins a version for your team via `package.json`. See [Global vs Project Install](#global-vs-project-install) for help choosing.

### Quick Trial

To try the plugin for a single session without registering the marketplace, point Claude Code at the release archive:

```bash
claude --plugin-url https://github.com/pdugan20/claudelint/releases/latest/download/claudelint-plugin.zip
```

This loads the plugin's skills for the current session only — nothing is persisted and your installed marketplaces are untouched. The skills still run the `claudelint` CLI, so the npm package above is required.

For a persistent install, use the marketplace below.

### From the Marketplace

1. Add the marketplace (one-time setup):

   ```text
   /plugin marketplace add pdugan20/plugins
   ```

2. Install the plugin:

   ```text
   /plugin install claudelint@patrick-plugins
   ```

Choose your installation scope when prompted:

* **User scope** (default, recommended) — available in all your projects
* **Project scope** — shared with collaborators via `.claude/settings.json`
* **Local scope** — only you, only this repo

### Team Setup

To pre-configure the plugin for all collaborators, commit this to `.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": {
    "patrick-plugins": {
      "source": {
        "source": "github",
        "repo": "pdugan20/plugins"
      }
    }
  },
  "enabledPlugins": {
    "claudelint@patrick-plugins": true
  }
}
```

When a collaborator opens Claude Code in this project, they will be prompted to install the plugin.

### Local Development / Testing

For plugin contributors, load the plugin directly:

```bash
claude --plugin-dir ./node_modules/claude-code-lint
```

## Skills

Once installed, the plugin adds 9 skills that Claude can use automatically. Ask naturally or invoke directly with `/<name>`.

### Validation

### Quality and Optimization

The **optimize-cc-md** skill runs a guided 3-phase workflow (validate, assess, improve) to reduce CLAUDE.md file size by extracting content into `@import` files, removing generic instructions, and reorganizing by concern. Use it when `claudelint check-all` flags `claude-md-size` violations or when your CLAUDE.md has grown large.

See the [CLI Reference](/guide/cli-reference) for all available flags when using slash commands directly.

## Automatic Validation

Set up a SessionStart hook so Claude is automatically aware of validation issues at the start of every session:

```bash
claudelint init --hooks
```

This creates `.claude/hooks/hooks.json` with a hook that runs `claudelint check-all` when a Claude Code session begins. See [Claude Code Hooks](/integrations/hooks) for manual setup and alternative hook types.

## Configuration

The plugin respects your project's configuration files:

* `.claudelintrc.json` — Rule configuration
* `.claudelintignore` — Files to ignore

See the [Configuration Guide](/guide/configuration) for details.

## Global vs Project Install

| Scenario | npm Install | Plugin Scope |
|----------|------------|--------------|
| Individual developer, all projects | `npm install -g` | User scope |
| Team project, pinned version | `npm install --save-dev` | Project scope |
| Trying it out | `npm install --save-dev` | Local scope |

* **Global npm + User scope** is the simplest setup. Install once and claudelint works everywhere.
* **Local npm + Project scope** gives teams a pinned version. Add `claude-code-lint` to `devDependencies` and commit `.claude/settings.json` so everyone gets the same setup.

## Keeping Up to Date

The plugin and npm package are updated independently.

### Plugin Updates

Third-party marketplace plugins don't auto-update by default. Enable it via `/plugin` → **Marketplaces** → select your installed marketplace → **Enable auto-update**. When enabled, Claude Code checks for updates at startup and prompts you to run `/reload-plugins` when new versions are available.

To update manually:

```text
/plugin marketplace list
/plugin marketplace update <name>
```

Replace `<name>` with the installed marketplace name shown by the list command. Then
open `/plugin`, select claudelint under **Installed**, and choose **Update now**.
Use the installed name rather than assuming it matches a repository or manifest name.

### npm Package Updates

The plugin's SessionStart hook checks for a missing or outdated CLI using npm. If npm is
unavailable, it compares the CLI with the installed plugin's expected version. It does
not infer plugin update availability from npm: the installed marketplace may pin a
different plugin version, and Claude Code handles those updates.

::: details Environment variables for auto-update control
Set `DISABLE_AUTOUPDATER=true` to disable all automatic updates (Claude Code and plugins). To keep plugin auto-updates while disabling Claude Code updates, also set `FORCE_AUTOUPDATE_PLUGINS=true`.
:::

## Troubleshooting

### Skills don't appear

**Problem:** Slash commands from the plugin aren't available in Claude Code.

**Solution:**

1. Check plugin is installed: `/plugin list`
2. Reinstall if needed: `/plugin uninstall claudelint` then reinstall
3. Restart Claude Code session

### Validation fails

**Problem:** Running a validation skill returns unexpected errors.

**Solution:**

1. Run with `--explain` flag for detailed guidance
2. Check `.claudelintrc.json` for rule configuration
3. See error messages for specific line numbers and fixes
4. Review [Rules Reference](/rules/overview) for rule details

### Permission denied

**Problem:** Permission errors when the plugin tries to run claudelint.

**Solution:**

1. Check `claudelint` is installed: `which claudelint`
2. Install globally if needed: `npm install -g claude-code-lint`
3. Check PATH includes npm global bin directory

### False positives

**Problem:** Warnings or errors that don't apply to your project.

**Solution:**

1. Use inline disable comments: `<!-- claudelint-disable rule-name -->`
2. Configure rules in `.claudelintrc.json`
3. Add file overrides for specific patterns
4. [Report an issue](https://github.com/pdugan20/claudelint/issues) if the rule is incorrect

### Skills work in one project but not another

**Problem:** Plugin skills run in some projects but fail in others.

The npm package is likely installed locally (in `node_modules`) rather than globally.

**Solution:**

1. Install globally: `npm install -g claude-code-lint`
2. Or add `claude-code-lint` to `devDependencies` in each project

### Version mismatch warning

**Problem:** Claude mentions a version mismatch between the plugin and npm package at session start.

The plugin and npm package are out of sync. Claude will offer to fix it for you, or you can update manually:

**Solution:**

```bash
npm install -g claude-code-lint@latest
```

### Auto-update not working

**Problem:** The plugin doesn't auto-update when new versions are released.

Third-party marketplaces have auto-update disabled by default. Also check that `DISABLE_AUTOUPDATER` is not set in your environment.

**Solution:** Enable auto-update via `/plugin` → **Marketplaces** → select your installed marketplace → **Enable auto-update**. For a manual update, run `/plugin marketplace list`, use the installed name in `/plugin marketplace update <name>`, then select claudelint under **Installed** and choose **Update now**.

## Uninstalling

To remove the plugin:

```bash
/plugin uninstall claudelint
```

## See Also

* [Configuration Guide](/guide/configuration) - Customize validation rules
* [Claude Code Hooks](/integrations/hooks) - Automatic validation hooks
* [Rules Reference](/rules/overview) - What gets validated
* [CLI Reference](/guide/cli-reference) - All commands and flags