terraform-lsp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Claude Code plugin providing Terraform development support through terraform-ls LSP integration and 17 automated hooks for code quality, security, and infrastructure validation.

Setup

Run /setup to install all required tools, or manually:

# macOS (Homebrew)
brew tap hashicorp/tap
brew install hashicorp/tap/terraform hashicorp/tap/terraform-ls \
             tflint trivy checkov terraform-docs infracost terragrunt

Run /validate to verify the plugin installation and tool availability.

Key Files

File	Purpose
.lsp.json	terraform-ls LSP configuration
hooks/hooks.json	17 automated development hooks
.claude/commands/setup.md	/setup command definition
.claude/commands/validate.md	/validate command definition
.claude-plugin/plugin.json	Plugin metadata

Hook System

All hooks trigger on PostToolUse after Write|Edit operations. Hooks use command -v checks to skip gracefully when optional tools aren't installed.

Hook categories:

• Core (.tf): format, validate, init check, plan hint
• Linting (.tf): tflint, todo/fixme detection
• Security (.tf): trivy, checkov, sensitive value detection
• Variables (.tfvars): format, sensitive check
• Terragrunt (terragrunt.hcl): format, validate
• Hints (main.tf, variables.tf): docs, cost, provider upgrade suggestions

When Modifying Hooks

Edit hooks/hooks.json. The hooks use Claude Code's standard event-based format:

{
    "hooks": {
        "PostToolUse": [
            {
                "matcher": "Write|Edit",
                "hooks": [{ "type": "command", "command": "..." }],
                "conditions": { "fileExtensions": [".tf"] }
            }
        ]
    }
}

Key fields:

• matcher: Tool name pattern (e.g., Write|Edit for file operations)
• conditions.fileExtensions: File types to match (e.g., [".tf", ".tfvars"])
• conditions.pathPatterns: Path globs for specific files (e.g., ["**/main.tf"])