GDScript Linter - Static Code Quality Analyzer

Static code analyzer for GDScript that identifies code quality issues, technical debt, and best practice violations. Features clickable navigation to issues, configurable thresholds, and CI/CD support via CLI.

Runs in seconds with no external dependencies. Can help reduce token usage on large projects.

Features

Code Quality Checks

Check	Severity	Description
File Length	Warning/Critical	Files exceeding soft/hard line limits
Function Length	Warning/Critical	Functions that are too long
Cyclomatic Complexity	Warning/Critical	Functions with too many decision paths
Parameter Count	Warning	Functions with too many parameters
Nesting Depth	Warning	Deeply nested code blocks
TODO/FIXME Comments	Info/Warning	Tracks technical debt markers
Print Statements	Warning	Debug prints left in code
Empty Functions	Info	Functions with no implementation
Magic Numbers	Info	Hardcoded numbers that should be constants
Commented-Out Code	Info	Dead code left in comments
Missing Type Hints	Info	Variables and functions without type annotations
God Classes	Warning	Classes with too many public functions or signals
Naming Conventions	Info/Warning	Non-standard naming (snake_case, PascalCase, etc.)
Unused Variables	Warning	Local variables declared but never used
Unused Parameters	Info	Function parameters declared but never used
ASCII Enforcement	Warning	Non-ASCII characters in `#@ascii_only` files
Strict Limits	Critical	Values exceeding `gdlint:strict` overrides
Sealed Classes	Critical	Extending a `#@Sealed` class

Editor Integration

Bottom panel dock with full analysis results
Clickable file:line links to navigate directly to issues
Filter by severity (Critical/Warning/Info)
Filter by issue type (linked to severity selection)
Filter by filename
Configurable thresholds via settings panel
Real-time debt score calculation
Export to JSON or interactive HTML report

Reports

Optionally export to .md file (useful for non-claude LLMs and task management systems)
Optionally export to .json file
Optionally export to self-contained dark-themed HTML file
- Interactive filtering by severity, type, and filename
- Linked filters: type dropdown updates based on selected severity
- Summary stats with issue counts and debt score

Claude Code Integration

Launch Claude Code directly from scan results to get AI-assisted fixes:

Enable in Settings > Claude Code Integration
Issue context (file, line, type, message) is passed automatically
Add custom instructions to customize the AI prompt
Requires claude-code CLI installed

Interaction Options:

Action	Behavior
Click	Launch Claude Code in plan mode (safe - reviews before making changes)
Shift+Click	Launch Claude Code in immediate mode (fixes without planning)
Right-click	Context menu with "Plan Fix" and "Fix Immediately" options

Hover over any Claude icon to see a tooltip with these options.

CLI Support

Run analysis from command line for CI/CD integration:

# Analyze current project
godot --headless --script res://addons/gdscript-linter/analyzer/analyze-cli.gd

# Analyze external project
godot --headless --path /path/to/gdscript-linter --script res://addons/gdscript-linter/analyzer/analyze-cli.gd -- --path "C:/my/project"

# Output formats
godot --headless --script res://addons/gdscript-linter/analyzer/analyze-cli.gd -- --clickable  # Godot Output panel format
godot --headless --script res://addons/gdscript-linter/analyzer/analyze-cli.gd -- --json       # JSON format
godot --headless --script res://addons/gdscript-linter/analyzer/analyze-cli.gd -- --html -o report.html  # HTML report

# Audit mode - bypass all ignore directives
godot --headless --script res://addons/gdscript-linter/analyzer/analyze-cli.gd -- --no-ignore

Exit Codes:

0 - No issues found
1 - Warnings only
2 - Critical issues found

Installation

From Asset Library

Open Godot Editor
Go to AssetLib tab
Search for "GDScript Linter"
Download and install
Enable plugin: Project > Project Settings > Plugins > GDScript Linter > Enable

Manual Installation

Download or clone this repository
Copy the addons/gdscript-linter folder to your project's addons/ directory
Enable plugin: Project > Project Settings > Plugins > GDScript Linter > Enable

Usage

Editor Dock

After enabling the plugin, find "Code Quality" in the bottom panel
Click "Scan" to analyze your codebase
Click any issue to navigate to the source location
Use filters to focus on specific severity levels or issue types
Click the settings icon to adjust thresholds

Ignore Comments

Suppress warnings for intentional code patterns using inline comments:

Directive	Scope
`gdlint:ignore-file`	Entire file
`gdlint:ignore-below`	Line to EOF
`gdlint:ignore-function`	Entire function
`gdlint:ignore-block-start/end`	Code block
`gdlint:ignore-next-line`	Next line
`gdlint:ignore-line`	Same line

All directives support optional check IDs: # gdlint:ignore-line:magic-number,print-statement

Pinned Exceptions

Track technical debt regression by pinning numeric values:

# gdlint:ignore-function:long-function=35
func my_complex_function():
    # Function is 35 lines - pinned at this value

Scenario	Result
Actual matches pinned (35 = 35)	Silently ignored
Actual exceeds pinned (35 → 40)	⚠️ Warning: "exceeded pinned limit"
Actual improved (35 → 32, still > 30)	ℹ️ Info: "consider tightening"
Actual now within limit (35 → 25)	ℹ️ Info: "pinned ignore is now unnecessary"

See IGNORE_RULES.md for full syntax reference and examples.

Defensive Attributes

Three attributes for enforcing stricter contracts on critical code.

`#@ascii_only` — ASCII Enforcement

Place in the first 10 lines of a file to flag non-ASCII characters (including in strings and comments) as warnings.

#@ascii_only
extends Node

var name := "hello"   # OK
var label := "héllo"  # WARNING: ascii-violation

Enable project-wide with ascii_only_project_wide = true in .gdlint.cfg. Individual files can opt out with # gdlint:ignore-file:ascii-violation.

`# gdlint:strict` — Per-Scope Tighter Limits

Override global thresholds with stricter values. Issues fire at CRITICAL severity and suppress the normal threshold check.

# File-scoped (first 10 lines):
# gdlint:strict-file:file-length=200

# Function-scoped (above func):
# gdlint:strict-function:long-function=25
func critical_function():
    pass

Supported rules: long-function, file-length, high-complexity, deep-nesting, too-many-params, god-class-functions, god-class-signals

`#@Sealed` — Prevent Class Inheritance

Mark a class as sealed to prevent other files from extending it. Requires class_name on the next line and directory-wide analysis.

#@Sealed
class_name CoreAPI
extends RefCounted
# Other files extending CoreAPI will get a CRITICAL sealed-violation

See IGNORE_RULES.md for full details on all defensive attributes.

Project Configuration

Create a .gdlint.cfg file in your project root to customize settings:

[limits]
file_lines_soft = 200
file_lines_hard = 300
function_lines = 30
function_lines_critical = 60
max_parameters = 4
max_nesting = 3
cyclomatic_warning = 10
cyclomatic_critical = 15
ascii_only_project_wide = false

[checks]
file_length = true
function_length = true
cyclomatic_complexity = true
parameters = true
nesting = true
todo_comments = true
print_statements = true
empty_functions = true
magic_numbers = true
commented_code = true
missing_types = true
god_class = true
naming_conventions = true
unused_variables = true
unused_parameters = true
ignore_underscore_prefix = true
ascii_only = true
sealed_classes = true

[scanning]
scan_addons = false
included_addons = gdscript-linter, my-other-addon
excluded_addons = some-third-party-addon

[exclude]
paths = addons/, .godot/, tests/mocks/

Scan Options precedence:

`included_addons`	`scan_addons`	Result
non-empty	any	Scan ONLY the listed addons
empty	true	Scan all addons except `excluded_addons`
empty	false	Scan no addons (default)

CI/CD Integration

GitHub Actions

name: Code Quality

on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download Godot
        run: |
          wget -q https://github.com/godotengine/godot/releases/download/4.5-stable/Godot_v4.5-stable_linux.x86_64.zip
          unzip -q Godot_v4.5-stable_linux.x86_64.zip
          chmod +x Godot_v4.5-stable_linux.x86_64

      - name: Run Code Analysis
        run: |
          ./Godot_v4.5-stable_linux.x86_64 --headless --path . --script res://addons/gdscript-linter/analyzer/analyze-cli.gd -- --clickable

Default Thresholds

Setting	Soft/Warning	Hard/Critical
File lines	200	300
Function lines	30	60
Cyclomatic complexity	10	15
Max parameters	4	-
Max nesting depth	3	-
God class functions	20	-
God class signals	10	-

Allowed Magic Numbers

These numbers are not flagged as they are commonly self-explanatory: 0, 1, -1, 2, 0.0, 1.0, 0.5, 2.0, -1.0, 10, 60, 90, 100, 180, 255, 360

Requirements

Godot 4.0+
GDScript only (no C# support)

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Roadmap

Nothing planned. Waiting for feedback...

This project was built with the assistance of Claude Code, an AI coding assistant by Anthropic.

Name		Name	Last commit message	Last commit date
Latest commit History 103 Commits
addons/gdscript-linter		addons/gdscript-linter
screenshots		screenshots
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
icon.png		icon.png
icon.svg		icon.svg
project.godot		project.godot
project.json		project.json

Navigation Menu

Repository files navigation

GDScript Linter - Static Code Quality Analyzer

Features

Code Quality Checks

Editor Integration

Reports

Claude Code Integration

CLI Support

Installation

From Asset Library

Manual Installation

Usage

Editor Dock

Ignore Comments

Pinned Exceptions

Defensive Attributes

`#@ascii_only` — ASCII Enforcement

`# gdlint:strict` — Per-Scope Tighter Limits

`#@Sealed` — Prevent Class Inheritance

Project Configuration

CI/CD Integration

GitHub Actions

Default Thresholds

Allowed Magic Numbers

Requirements

License

Contributing

Roadmap

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

GDScript Linter - Static Code Quality Analyzer

Features

Code Quality Checks

Editor Integration

Reports

Claude Code Integration

CLI Support

Installation

From Asset Library

Manual Installation

Usage

Editor Dock

Ignore Comments

Pinned Exceptions

Defensive Attributes

#@ascii_only — ASCII Enforcement

# gdlint:strict — Per-Scope Tighter Limits

#@Sealed — Prevent Class Inheritance

Project Configuration

CI/CD Integration

GitHub Actions

Default Thresholds

Allowed Magic Numbers

Requirements

License

Contributing

Roadmap

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`#@ascii_only` — ASCII Enforcement

`# gdlint:strict` — Per-Scope Tighter Limits

`#@Sealed` — Prevent Class Inheritance