Crystal Language Plugin for JetBrains IDEs: v0.2.7 Public Beta

[magynhard]

Crystal Language Plugin for JetBrains IDEs: v0.2.7 Public Beta

After many months of development, I am finally ready to share version 0.2.7 of the Crystal Language plugin for JetBrains IDEs with the wider Crystal community.

The plugin is available from the JetBrains Marketplace:

Crystal Language on JetBrains Marketplace

Source code, documentation, and issue tracking are available on GitHub:

github.com/magynhard/intellij-crystal

Why Did I Build This?

My motivation may sound slightly backwards.

I wanted to learn Crystal and start building something with it, but I also wanted proper support for my favorite IDE, RubyMine. Before seriously developing in Crystal, I therefore decided that I first needed a JetBrains plugin for it. ;-)

What began as a prerequisite gradually turned into a substantial project of its own.

The plugin does not rely on an LSP. It has its own JFlex lexer, GrammarKit parser, PSI tree, stub indexes, type inference, navigation, inspections, completion, and JetBrains-specific editor integrations.

Long term, I believe that an LSP implementation will probably be the future for Crystal tooling. There is also renewed work on an LSP being discussed here in the forum, which I am following with interest. This plugin takes a different approach for now: it integrates directly with the IntelliJ Platform and implements its language intelligence through JetBrains APIs.

A Largely AI-Built Project

I do not actively develop in Java or Kotlin, so this has been an almost entirely AI-assisted, or “vibe-coded,” project.

I used my OpenCode subscription extensively and worked with a wide range of models throughout development. Large parts of the earlier implementation were written with Mimo V2.5, with occasional help from DeepSeek, GLM 5.2, and different Kimi models.

That journey was not exactly linear.

At one point, the project reached a dead end: the parser had become extremely slow, and increasingly complex fixes made it difficult to move forward. GPT-5.6 Sol managed to resolve the major parser-performance problems, but several existing features stopped working in the process. Even after multiple iterations, I could not get some important parts back into a reliable state.

Then the stealth model Ox Alpha became available for free testing during the last few days. To my surprise, progress changed dramatically. It helped me finish and stabilize a number of features that had resisted previous attempts, particularly around parsing, require-aware code intelligence, type resolution, completion, and navigation.

This experience taught me a great deal about working with AI on a non-trivial software project: requirements management, architectural constraints, regression testing, reviewing generated code, diagnosing plausible but incorrect implementations, and understanding how much discipline is still required even when most of the code is generated.

The project may have been largely written by AI, but it certainly was not built by accepting the first answer from a model.

What Is Included?

Version 0.2.7 is an early beta, but it already provides a broad set of IDE features.

Editing and Syntax Support

• Extensive Crystal syntax highlighting
• Semantic highlighting for variables, parameters, methods, and types
• Crystal macros, annotations, heredocs, regex literals, percent literals, interpolation, and command literals
• Matching and highlighting for Crystal keyword blocks such as if, elsif, else, and end
• Code folding, brace matching, automatic indentation, and automatic end insertion
• TODO and FIXME highlighting
• 21 Crystal live templates
• Formatting through crystal tool format

Navigation and Documentation

• Go to Definition for classes, modules, structs, enums, methods, variables, constructors, and DOT calls
• Go to Class and Go to Symbol
• Find Usages
• Rename refactoring with optional compiler verification
• Structure View
• Parameter information for ordinary calls, bare calls, DOT calls, constructors, and overloads
• Quick Documentation generated from Crystal documentation comments
• Clickable type references inside documentation popups
• Hover information for variables, parameters, definitions, and inferred return types

Code Completion

• Context-aware free-text and DOT completion
• Completion for local variables, parameters, methods, constants, classes, and stdlib types
• Receiver-aware completion for literals, expressions, method results, ranges, collections, constructors, and type objects
• Overload-aware method suggestions with parameter signatures
• Type completion inside annotations, generics, and union types
• Namespace and class-constant completion after ::
• require statement and path completion
• Require-aware visibility based on the current file, its transitive dependencies, and the configured Crystal prelude

A major goal has been to avoid suggesting methods merely because a declaration with the same name exists somewhere in the project. The plugin attempts to resolve the actual receiver and respect Crystal’s require graph before offering completion or navigation targets.

Inspections and Type Inference

The plugin includes inspections for:

• Incorrect argument counts
• Argument type mismatches
• Named arguments, splats, double splats, defaults, and overloads
• Instance-variable type mismatches
• Unused assignments
• Invalid empty collection literals
• Missing types in lib fun declarations
• Invalid single-quoted strings
• Invalid dynamic require expressions
• Several Crystal-specific syntax and formatting problems

Its type inference covers local and instance variables, method parameters and return values, literals, arrays, hashes, tuples, named tuples, unions, control-flow expressions, constructors, and many common method-call chains.

This is not a replacement for the Crystal compiler’s complete type system, but it provides useful editor feedback without compiling after every keystroke.

Run, Test, and Debug Support

• Run configurations for crystal run, crystal build, and crystal spec
• Configurable arguments, environment variables, and working directories
• Integrated Crystal spec runner
• Test gutter icons and execution of individual specs
• Test result tree inside the IDE
• Debugging through lldb-dap
• Breakpoints, stepping, and variable inspection
• Crystal-specific LLDB formatters

Embedded Crystal Templates

The plugin also supports .ecr and .html.ecr files:

• Crystal parsing and syntax highlighting inside <% %> tags
• HTML highlighting outside Crystal tags
• Completion, navigation, documentation, parameter information, and inspections inside injected Crystal code
• Combined ECR and HTML Structure Views
• Navigation for instance variables used in templates

Current Status and Limitations

I am calling this an early beta deliberately.

I am very happy with this first public version, but I am also sure that bugs remain. Some features may still feel less comfortable than their equivalents in mature JetBrains language plugins, some Crystal syntax combinations may not yet be parsed correctly, and important features are certainly still missing.

The plugin currently requires:

• A JetBrains IDE based on IntelliJ Platform 2026.2 or newer
• A Crystal compiler for project creation, formatting, compiler-assisted checks, running, testing, and standard-library code intelligence; the plugin auto-detects common installations or accepts a project-specific executable path
• lldb-dap (optional) for debugging

It supports IntelliJ IDEA, RubyMine, WebStorm, and other compatible JetBrains IDEs. Native Windows support remains experimental and less extensively tested than Linux and macOS support.

Feedback Is Very Welcome

This is the first version I am intentionally sending out to the Crystal community rather than treating it mainly as my own development experiment.

If you use a JetBrains IDE and are interested in Crystal, I would be very grateful if you gave it a try.

Bug reports, missing syntax examples, feature requests, and feedback about awkward workflows are all welcome. When reporting a problem, please include a minimal code example together with the current and expected behavior. That makes it much easier to reproduce the issue and turn it into a regression test.

• Install from the JetBrains Marketplace
• Source code and issue tracker

Thank you to everyone working on Crystal and its tooling. I hope this plugin is already useful to some of you, even if it is still only the beginning.

If you like it and want to support me by a donation, you can do this here.