A Language Server for Crystal.

Build Status GitHub tag (latest SemVer) GitHub

Crystalline is an implementation of the Language Server Protocol written in and for the Crystal Language. It aims to provide limited language features (like go-to, autocompletion, syntax and semantic checking) and ease development with any compatible code editor.

Status: in development.


Recommended method is to download and use pre-built binaries when possible. Building from source does take a long time.


| Crystal | Crystalline | | -------- | ----------- | | 1.11 | 0.12 | | 1.10 | 0.11 | | 1.9 | 0.10 | | 1.8 | 0.9 | | 1.7 | 0.8 | | 1.6 | 0.7 | | 1.4 | 0.6 | | 1.3 | 0.5 | | 1.2 | 0.4 | | 1.1 | 0.4 | | 1.0 | 0.3 | | 0.36 | 0.2 | | 0.35.1 | 0.1 |

Pre-built binaries

Latest Release

Linux (x86_64)
wget -O crystalline.gz &&\
gzip -d crystalline.gz &&\
chmod u+x crystalline
yay -S crystalline

Install using homebrew:

brew install crystalline

Specific release

See the releases page.

Specific commit

Binaries are uploaded as artifacts during the CI build.

Build from source

Warning: this can take a long time! (several minutes - up to 20 minutes, depending on your hardware)

Scoped install

In the .shard.yml file:

    github: elbywan/crystalline
    branch: master


# Produces a binary at ./bin/crystalline
shards build crystalline --release --no-debug --progress -Dpreview_mt

Global install

git clone
cd crystalline
shards install
mkdir bin
crystal build ./src/  -o ./bin/crystalline --release --no-debug --progress -Dpreview_mt

Known Build Issues

Potential errors when building from source.

llvm-config path

llvm is required in order to build crystalline, if you get the following error message it means that the crystal compiler is unable to locate the llvm-config binary:

--: : command not found
Showing last frame. Use --error-trace for full trace.

In /usr/local/Cellar/crystal/0.35.1/src/llvm/

 13 | VERSION = {{`#{LibLLVM::LLVM_CONFIG} --version`.chomp.stringify}}
Error: error executing command: "" --version, got exit status 127

This can be solved by adding the location of the llvm-config binary to the LLVM_CONFIG environment variable. (or the containing directory to the PATH env. variable)

For instance on a typical macOS setup, prefixing the command with the following declaration would solve the issue:

# Prepend the command with this:
env LLVM_CONFIG=/usr/local/opt/llvm/bin/llvm-config
# For Example:
env LLVM_CONFIG=/usr/local/opt/llvm/bin/llvm-config crystal build ./src/  -o ./bin/crystalline --release --no-debug -Dpreview_mt

Replace env by export on Debian and derived (Ubuntu, Mint, ...)

ld: library not found for -llibxml2.tbd

LLVM 10.0.1 has some issues when reporting required system libraries on macOS.

More info: here

# Wrong: -llibxml2.tbd
$ llvm-config --system-libs
-lm -lz -lcurses -llibxml2.tbd
# `liblibxml2.tbd.dylib` is unlikely to be found during compilation,
# hence the "library not found" error…

A hacky solution until llvm produces a solution would be to add a symbolic link to the correct shared library file:

ln -s /usr/lib/libxml2.2.dylib /usr/local/lib/liblibxml2.tbd.dylib

Or just use a different LLVM major version until this issue is fixed upstream.


Crystalline is meant to be used alongside an editor extension.


vscode screen


Using Conquer of Completion we can configure Crystalline as our LSP backend and get all the features of Crystalline we would get with VSCode.

Add the following snippet to your coc-settings.json file:

"languageserver": {
    "crystal": {
      "command": "crystalline",
      "args": [
      "filetypes": [
      "rootPatterns": ["shard.yml"]


At the moment, lsp-mode only knows about scry as the Crystal language server. So, to get it working with crystalline we need to configure lsp-mode to look for crystalline.

You can use the following config snippet to achieve this:

(with-eval-after-load 'lsp-mode
  (add-to-list 'lsp-language-id-configuration
               '(crystal-mode . "crystal"))
  (make-lsp-client :new-connection (lsp-stdio-connection '("crystalline"))
                   :activation-fn (lsp-activate-on "crystal")
                   :priority '1
                   :server-id 'crystalline)))

This will give higher priority to crystalline, and Emacs should automatically connect to the backend whenever you're in crystal-mode.

Entry point

Important: Crystalline will try to determine which file is best suited as an entry point when providing language features.

The default behaviour is to check the shard.yml file for a target entry with the same name as the shard.

name: my_shard

    main: src/

With the configuration above, every file required by src/ will use src/ as the entry point.

If this shard.yml entry is not present, or if the file is not part of the main dependency tree then crystalline will use the file itself as the entry point.

To override this behaviour, you can add a configuration key in the shard.yml file.


This can be extremely important to understand when you are writing a code library that does not call any of its own methods - it will skip code analysis. In this case, and if you are writing specs, you should point to a file that require the specs (or anything calling the library) and then crystalline will use it as the entry point.

# Contents of a file at the root of the project.
# Will require the specs that call the library methods and enable the code analysis.
require "./spec/**"


Disclaimer: Crystalline is not as extensive in terms of features as other Language Servers but still provides very convenient tools.

Code Diagnostics

Syntax and semantic checks on save.

Limited Autocompletion

List (depending on the target) method definitions, macros or module/class/struct names or symbols available in the current context.


A whole document or a text selection.

Go to definition

By clicking on a symbol with the Cmd or Ctrl key pressed (editor/platform dependent).

Hover information

Hovering should display (when possible) either a variable type, a function definition signature or the expanded macro.

Document symbols

Fetch all the symbols in a given file, used in VSCode to populate the Outline view and the Breadcrumbs.



Dev build

Sentry is used to re-build crystalline in debug mode on code change.

# To build sentry (once):
shards build --release sentry
# Then, to launch it and watch the filesystem:
./bin/sentry -i


Logging is the most practical way to debug the LSP.

# Use the LSP logger to display logs in the editor. { "log" }

Debug logs are deactivated by default, uncomment this line in src/crystalline/lsp/ to enable them:

# Uncomment:
# ::Log.setup(:debug, LSP::Log.backend.not_nil!)


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Please always crystal tool format your code!




Why the name crystalline?

Aside of the obvious reasons (crystal-lang), cristaline is a famous bottled water brand in France that published silly TV commercials. It is pronounced the same as crystalline.

guy roux