Documentation/Tools/Graphql Inspector
🔧

Graphql Inspector

v1.1.0Apache 2.0

GraphQL Inspector validation for schema diffing, breaking change detection, and operation validation.

toolsskillhookgraphqlgraphql-inspectorschemavalidationbreaking-changesdiff

Installation

Install han binary (required for hooks to work):

curl -fsSL https://han.guru/install.sh | bash

Then install this plugin:

han plugin install graphql-inspector

Overview

Validation and quality enforcement for GraphQL schemas and operations using GraphQL Inspector.

What This Jutsu Provides

Validation Hooks

  • Schema Diff: Detects breaking, dangerous, and non-breaking changes between schema versions
  • Operation Validation: Validates GraphQL operations against your schema with depth and complexity limits

Skills

This jutsu provides the following skills:

  • graphql-inspector-diff: Breaking change detection and schema comparison
  • graphql-inspector-validate: Operation validation with complexity analysis
  • graphql-inspector-audit: Query complexity auditing and metrics
  • graphql-inspector-ci: CI/CD integration for GitHub Actions, GitLab CI, and more

Installation

Install via the Han marketplace:

bash
han plugin install jutsu-graphql-inspector

Or install manually:

bash
claude plugin marketplace add thebushidocollective/han
claude plugin install jutsu-graphql-inspector@han

Usage

Once installed, this jutsu automatically validates your GraphQL code:

  • When you finish a conversation with Claude Code
  • When Claude Code agents complete their work
  • Before commits (when combined with git hooks)

Manual Commands

bash
# Validate operations against schema
npx @graphql-inspector/cli validate './src/**/*.graphql' './schema.graphql'

# Check for breaking changes against main branch
npx @graphql-inspector/cli diff 'git:origin/main:schema.graphql' 'schema.graphql'

# Audit operation complexity
npx @graphql-inspector/cli audit './src/**/*.graphql'

Features

Breaking Change Detection

GraphQL Inspector categorizes changes as:

CategoryImpactExamples
BreakingWill break clientsField removed, type changed, required arg added
DangerousMay break some clientsEnum value added, default changed
Non-BreakingSafeField added, type added, deprecation

Validation Rules

Configure limits to prevent performance issues:

  • --maxDepth: Maximum query nesting depth
  • --maxAliasCount: Maximum field aliases
  • --maxDirectiveCount: Maximum directives per operation
  • --maxComplexityScore: Calculated complexity limit

Federation Support

Works with Apollo Federation schemas:

bash
npx @graphql-inspector/cli validate './ops/*.graphql' './schema.graphql' --federationV2

Configuration

Create .graphql-inspector.yaml in your project root:

yaml
schema: './schema.graphql'

diff:
  rules:
    - suppressRemovalOfDeprecatedField
  failOnBreaking: true

validate:
  documents: './src/**/*.graphql'
  maxDepth: 10
  maxAliasCount: 5

Requirements

  • Node.js 18+
  • GraphQL schema file (.graphql or .gql)
  • GraphQL operations to validate

Related Plugins

  • jutsu-graphql: Core GraphQL schema design skills
  • jutsu-relay: Relay framework integration
  • jutsu-apollo-graphql: Apollo Client/Server skills

Resources

Skills

📖

graphql-inspector-audit

Use when auditing GraphQL operations for complexity metrics, depth analysis, directive usage, or query performance concerns.

📖

graphql-inspector-ci

Use when setting up GraphQL Inspector in CI/CD pipelines, GitHub Actions, or GitLab CI for automated schema validation.

📖

graphql-inspector-diff

Use when detecting breaking changes between GraphQL schema versions, comparing schemas across branches, or validating schema migrations.

📖

graphql-inspector-validate

Use when validating GraphQL operations/documents against a schema, checking query depth, complexity, or fragment usage.

Hooks

⚠ī¸

Token Usage Notice

Hooks run automatically during Claude Code sessions and their output is sent to the model for processing. This may increase token usage and associated costs. Consider disabling hooks you don't need via han-config.yml.

🛑

Stop

Runs when the main Claude Code agent has finished responding. Can verify task completion, check quality gates, or ensure documentation requirements are met before the session ends.

npx -y @graphql-inspector/cli validate './**/*.graphql' './schema.graphql'
npx -y @graphql-inspector/cli diff 'git:origin/main:schema.graphql' 'schema.graphql'