Installation

Install han binary (required for hooks to work):

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

Then install this plugin:

han plugin install shellcheck

Overview

Validation and quality enforcement for Bash and shell scripts using ShellCheck.

What This Jutsu Provides

Validation Hooks

ShellCheck Validation: Runs ShellCheck on all .sh files to catch common bugs, pitfalls, and style issues
Validates scripts on session stop and when agents complete work
Only runs when shell files have changed (with --cache flag)

Skills

This jutsu provides the following skills:

shell-scripting-fundamentals: Core patterns for variables, conditionals, loops, and functions
shell-error-handling: Traps, exit codes, cleanup routines, and debugging techniques
shell-portability: Writing scripts that work across Linux, macOS, and different shells

Installation

Install via the Han marketplace:

bash

han plugin install jutsu-shellcheck

Or install manually:

bash

claude plugin marketplace add thebushidocollective/han
claude plugin install jutsu-shellcheck@han

Usage

Once installed, this jutsu automatically validates your shell scripts:

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

Manual Validation

Run ShellCheck manually on your scripts:

bash

shellcheck -x script.sh
shellcheck -x **/*.sh

Configuring ShellCheck

Create a .shellcheckrc file in your project root:

# Disable specific checks
disable=SC2034,SC2086

# Set default shell
shell=bash

# Enable external sources
external-sources=true

Requirements

ShellCheck installed and available in PATH
Bash 4.0+ (for the validation hooks)

Installing ShellCheck

macOS:

bash

brew install shellcheck

Ubuntu/Debian:

bash

apt-get install shellcheck

Fedora:

bash

dnf install ShellCheck

From source:

bash

cabal update
cabal install ShellCheck

Common ShellCheck Codes

Code	Description
SC2086	Double quote to prevent globbing and word splitting
SC2046	Quote this to prevent word splitting
SC2034	Variable appears unused
SC2155	Declare and assign separately to avoid masking return values
SC2164	Use `cd ... \|\| exit` in case cd fails
SC2006	Use `$(...)` instead of legacy backticks

Overriding Hooks

Create a han-config.yml in directories where you want to customize behavior:

yaml

jutsu-shellcheck:
  shellcheck:
    enabled: false  # Disable shellcheck for this directory

Or override the command:

yaml

jutsu-shellcheck:
  shellcheck:
    command: "shellcheck -e SC2034 *.sh"  # Ignore unused variable warnings

Skills

📖

shell-error-handling

Use when implementing error handling, cleanup routines, or debugging in shell scripts. Covers traps, exit codes, and robust error patterns.

📖

shell-portability

Use when writing shell scripts that need to run across different systems, shells, or environments. Covers POSIX compatibility and platform differences.

📖

shell-scripting-fundamentals

Use when writing or modifying Bash/shell scripts. Covers script structure, variables, quoting, conditionals, and loops with modern best practices.

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.