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