guardrail

A static analysis tool that catches the patterns LLMs consistently produce: oversized functions, excessive complexity, too many parameters, bloated classes. Run it as a post-generation hook or CI gate to keep AI-written code honest.

Install

npm install --save-dev @alexcvzz/guardrail

Or run directly:

npx @alexcvzz/guardrail check src/**/*.ts

Usage

guardrail check src/**/*.ts

Glob patterns are expanded by guardrail — no shell dependency.

CLI flags

| Flag | Description | |---|---| | --json | Machine-readable JSON output | | --quiet | Only show files with violations | | --timing | Print timing/performance breakdown to stderr |

Supported languages

JavaScript, TypeScript, JSX, TSX, Python, Java, Kotlin

Configuration

Create a .guardrail.yaml (or .guardrail.yml, .guardrail.json, .guardrail.js, .guardrail.ts) at the project root via cosmiconfig:

extends: recommended

rules:
  function-max-lines:
    max: 40
  function-max-complexity:
    max: 5
  function-max-params:
    max: 4

overrides:
  python:
    rules:
      function-max-lines:
        max: 60
  java:
    rules:
      function-max-complexity:
        disabled: true

Extends

The extends field inherits rules and ignore patterns from a named preset:

extends: recommended

Available presets:

| Preset | Description | |---|---| | recommended | Enables all built-in rules with default thresholds and a broad set of ignore patterns for common directories |

On first run, guardrail creates a global config at ~/.guardrail/config.yaml with extends: recommended. You can override any preset value in your local .guardrail.yaml — local rules replace preset rules by key, and local ignore patterns are appended.

To remove a pattern inherited from a preset, prefix it with !:

extends: recommended
ignore:
  - !build        # un-ignore build/ from recommended
  - generated     # add a new pattern

Rule options

| Option | Type | Description | |---|---|---| | max | number | Upper threshold for the rule | | severity | 'error' | 'warning' | Errors cause a non-zero exit code; warnings are reported but don't fail the run | | enabled | boolean | Enable or disable a rule | | disabled | boolean | Alias for enabled: false |

Language overrides

The overrides key accepts a language name and a rules block that is merged over the base rules. Supported language names: javascript, jsx, typescript, tsx, python, java, kotlin.

Built-in rules

| Rule ID | Description | Default | |---|---|---| | function-max-lines | Function body must not exceed N lines | 60 | | function-max-complexity | Cyclomatic complexity must not exceed N | 10 | | function-max-params | Function parameter count must not exceed N | 4 | | function-max-nesting | Function nesting depth must not exceed N | 4 | | function-max-returns | Number of return statements must not exceed N | 4 | | function-max-locals | Number of local variables must not exceed N | 15 | | class-max-lines | Class body must not exceed N lines | 500 | | class-max-methods | Class method count must not exceed N | 20 | | class-max-fields | Class field/property count must not exceed N | 20 | | max-file-lines | File line count must not exceed N (warning) | 300 | | max-import-lines | Import section must not exceed N lines (warning) | 20 | | no-duplicate-imports | Disallow multiple imports from the same source | — | | no-magic-numbers | Disallow unnamed numeric literals (warning) | — | | no-short-names | Disallow overly short names; common single-letter names allowed (warning) | minLength: 2 | | class-member-ordering | Enforce class member ordering | — |

Cyclomatic complexity starts at 1 and increments for each branch point: if, else if, loops, switch cases, catch blocks, ternary expressions.

Exit codes

| Code | Meaning | |---|---| | 0 | No errors (warnings may be present) | | 1 | At least one error-level violation | | 2 | guardrail claude check: error-level violation detected |

Claude Code integration

Set up Guardrail to run automatically after every file edit/write in Claude Code:

guardrail claude init              # global setup (default)
guardrail claude init --scope local  # project-local setup

This command will:

1. Add a PostToolUse hook to .claude/settings.json that runs guardrail check after every Edit or Write
2. Append a guardrail prompt line to CLAUDE.md so Claude understands why edits are blocked
3. Write ~/.guardrail/RULES.md with instructions on how to add custom rules

You'll see a summary of changes and be asked to confirm before anything is written.

When a violation is detected, Claude Code sees the error and is blocked from proceeding.

Manual setup

If you prefer to set things up manually:

1. Build and link the binary:

npm run build && npm link

2. Add the hook to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "guardrail claude check",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Custom rules

Guardrail supports custom rules in TypeScript or JavaScript. See CUSTOM_RULES.md for the full guide.

Scaffold a new rule:

# Local rule (project-specific)
guardrail rule add no-console

# Global rule (applies to all projects)
guardrail rule add no-console --scope global

List all available rules (builtin + custom):

guardrail rule list

This creates a .ts file in .guardrail/rules/ (local) or ~/.guardrail/rules/ (global) with the boilerplate filled in.

License

MIT