Editor Setup¶

Graphcal provides editor extensions with rich language support through the built-in LSP server. A key feature is inlay hints that display computed values inline, turning your editor into a live calculation sheet.

LSP Features¶

The Graphcal LSP server (graphcal lsp) provides:

The inlay hints feature is what makes Graphcal feel like a live spreadsheet. As you edit your .gcl file, the LSP evaluates the computation graph and shows the resulting values next to each param and node declaration. Change an input and watch all dependent values update.

For multi-file projects, editor navigation follows module-qualified identity for same-leaf declarations. If a.gcl and b.gcl both export Phase, Item, and Pick, go-to-definition on a.Phase, a.Phase.Burn, a.Item, or a.Pick(...) jumps to a.gcl, not whichever same-leaf symbol was seen first.

Analysis is revision-aware and bounded. A new edit cancels superseded loading, compilation, and evaluation work; only the newest completed revision publishes diagnostics or inlay-hint data. If an analysis exceeds the server deadline, the LSP keeps the last completed result available rather than replacing source diagnostics with a server-timeout error.

VS Code¶

The VS Code extension provides syntax highlighting (via TextMate grammar) and full LSP support.

Installation¶

Install the published Graphcal extension from the Visual Studio Marketplace.

You can also install it from VS Code:

1. Open the Extensions view.
2. Search for Graphcal.
3. Install the extension published by Graphcal.

Configuration¶

If graphcal is not on your PATH, set graphcal.lsp.path to the full path of the binary.

Zed¶

The Zed extension provides syntax highlighting (via tree-sitter grammar) and LSP support.

Setup¶

The Zed extension is not yet published. Install it as a dev extension for now:

1. Clone the extension repository: https://github.com/graphcal-lang/zed-graphcal
2. Open the command palette in Zed
3. Select "Extensions: Install Dev Extension"
4. Navigate to the cloned zed-graphcal directory
5. The extension will be installed and activated

Helix¶

Helix can use the Graphcal tree-sitter grammar and the built-in LSP server.

Add the following to ~/.config/helix/languages.toml:

[[grammar]]
name = "graphcal"
source = { git = "https://github.com/graphcal-lang/tree-sitter-graphcal", rev = "main" }

[language-server.graphcal-lsp]
command = "graphcal"
args = ["lsp"]

[[language]]
name = "graphcal"
scope = "source.graphcal"
file-types = ["gcl"]
roots = ["graphcal.toml"]
comment-token = "//"
language-servers = ["graphcal-lsp"]
indent = { tab-width = 2, unit = "  " }
auto-format = true

Then fetch and build the grammar:

hx --grammar fetch
hx --grammar build

graphcal must be available on your PATH; otherwise, set command to the full path of the Graphcal binary.

Helix syntax highlighting queries¶

The commands above install/update the parser binary, but Helix does not automatically install or refresh highlight query files from custom grammar repositories. Graphcal highlighting is loaded separately from:

~/.config/helix/runtime/queries/graphcal/highlights.scm

Install the highlight query after fetching the grammar:

mkdir -p ~/.config/helix/runtime/queries/graphcal
cp ~/.config/helix/runtime/grammars/sources/graphcal/queries/highlights.scm \
  ~/.config/helix/runtime/queries/graphcal/highlights.scm

If you prefer not to rely on Helix's grammar source cache, download the query directly instead:

mkdir -p ~/.config/helix/runtime/queries/graphcal
curl -fsSL \
  https://raw.githubusercontent.com/graphcal-lang/tree-sitter-graphcal/main/queries/highlights.scm \
  -o ~/.config/helix/runtime/queries/graphcal/highlights.scm

Neovim¶

For Neovim with nvim-treesitter:

1. Add https://github.com/graphcal-lang/tree-sitter-graphcal as the grammar source in your tree-sitter config
2. Copy the highlight queries from the repository's queries/highlights.scm

For LSP support, configure Neovim to run graphcal lsp over stdin/stdout for .gcl files.

Example configuration with nvim-lspconfig:

vim.api.nvim_create_autocmd("FileType", {
  pattern = "graphcal",
  callback = function()
    vim.lsp.start({
      name = "graphcal",
      cmd = { "graphcal", "lsp" },
    })
  end,
})

Other editors¶

For any editor with tree-sitter and LSP support, install the grammar from graphcal-lang/tree-sitter-graphcal and configure the language server to run graphcal lsp for .gcl files.