VS Code & Positron

The keel-vscode extension provides full Keel language support for Visual Studio Code and Positron.

Features

Syntax Highlighting

The extension provides two layers of syntax highlighting:

• TextMate grammar — Baseline highlighting for keywords, types, strings, numbers, operators, and comments
• Tree-sitter semantic tokens — Context-aware highlighting via web-tree-sitter with incremental parsing, providing accurate token boundaries for keywords, functions, variables, types, properties, parameters, comments, strings, numbers, operators, and constructors

Language Server Support

• Intelligent Code Completion — Context-aware suggestions for functions, types, variables, and module members
• Hover Documentation — Type signatures, documentation, and examples on hover
• Diagnostics — Real-time error detection
• Go to Definition — Navigate to symbol definitions with Ctrl+Click
• Find All References — Find all usages of a symbol (Shift+F12)
• Rename Symbol — Safely rename symbols across your codebase (F2)
• Document Symbols — Navigate code structure via Outline view (Ctrl+Shift+O)
• Workspace Symbols — Search for symbols across your project (Ctrl+T)
• Code Lens — Reference counts above function definitions
• Signature Help — Parameter hints while typing function calls
• Code Folding — Fold functions, case expressions, and blocks

Code Formatting

• Format Document — Format with Shift+Alt+F
• Format on Save — Automatically format files when saving (enabled by default)

Interactive Development

REPL Integration

• Keel: Start REPL — Launch an interactive REPL in the terminal
• Keel: Send Selection to REPL — Execute selected code with Ctrl+Enter
• Persistent state across evaluations (configurable via keel.repl.persistentProcess)
• Auto-starts REPL when opening .kl files (in VS Code; Positron uses the Jupyter kernel instead)

Jupyter Notebook Support

• Create .ipynb notebooks and select the Keel kernel
• Interactive cell execution with persistent state
• Rich output rendering (HTML tables for DataFrames, JSON for Records)
• Code completion and hover documentation in notebook cells
• Interrupt long-running computations

Requires the Jupyter kernel to be installed separately.

Script Execution

• Keel: Run File — Execute the current Keel file and view output in the Keel output panel

Data Science Features

• DataFrame Viewer — Interactive HTML table rendering with sortable columns, row filtering, pagination, and column statistics (min/max/mean)
• Variable Tracking — Automatically tracks REPL variables and displays them in an expandable tree view with nested Records, Lists, and DataFrames
• Stdlib Auto-import — List, String, Math, DateTime, IO, Http, Json, DataFrame, Result, Maybe available by default in notebooks
• Type Inspection — View types and values with Shift+Tab

Installation

1. Install the Extension

From VSIX (Current Method)

1. Download the latest .vsix file from the releases page
2. In VS Code/Positron: Extensions → "..." menu → Install from VSIX
3. Select the downloaded .vsix file

From Marketplace (Coming Soon)

Search for "Keel" in the VS Code Extensions marketplace.

2. Install Keel Toolchain

The extension requires the Keel CLI for language server, formatting, and REPL features.

Recommended: Unified CLI

cargo install --git https://codeberg.org/Keel/keel-cli

This provides keel lsp, keel fmt, keel repl, and keel run in a single binary.

Optional: Jupyter Kernel

For notebook support, install the kernel separately:

cargo install --git https://codeberg.org/Keel/keel-jupyter-kernel
install-keel-kernel

Requires Python and Jupyter to be installed.

Alternative: Individual Tools

If you prefer to install tools separately:

cargo install --git https://codeberg.org/Keel/keel-lsp     # Language server (required)
cargo install --git https://codeberg.org/Keel/keel-fmt      # Formatter (optional)
cargo install --git https://codeberg.org/Keel/keel-repl     # REPL (optional)

Configuration

Configure via VS Code settings (Preferences → Settings → search "keel"):

General

REPL

Data Viewer

Variable View

Positron

Custom Paths

If keel is not in your PATH:

{
  "keel.cli.path": "/usr/local/bin/keel"
}

Or configure individual tool paths when using standalone tools:

{
  "keel.lsp.path": "/usr/local/bin/keel-lsp",
  "keel.formatter.path": "/usr/local/bin/keel-fmt",
  "keel.repl.path": "/usr/local/bin/keel-repl"
}

Usage

Basic Editing

1. Open a .kl file
2. Start typing — completion, hover, and diagnostics work automatically
3. Use Ctrl+Click to navigate to definitions
4. View document structure in the Outline panel (Ctrl+Shift+O)

Interactive Development with REPL

1. Open a .kl file
2. Run command: Keel: Start REPL
3. Select code and press Ctrl+Enter to execute
4. Results appear immediately in the REPL terminal

Jupyter Notebooks

1. Create or open a .ipynb file
2. Select "Keel" as the kernel
3. Write Keel code in cells
4. Run cells with Shift+Enter
5. DataFrames render as interactive HTML tables

Keyboard Shortcuts

Commands

Positron-Specific Features

This extension is fully compatible with Positron, Posit's next-generation data science IDE.

Runtime Integration

The extension registers as a Positron language runtime, providing native integration with Positron's data science features via the Jupyter kernel protocol.

Variable Pane Integration

Variables and their types are automatically tracked and displayed in Positron's variable pane via Jupyter kernel introspection. Falls back to heuristic tracking when the kernel is not available.

Data Explorer

DataFrames can be opened in Positron's built-in data explorer with:

• Column schemas and type information
• Column statistics (null count, min, max, mean, median, std dev)
• Sortable and filterable data views
• Pagination for large datasets

Enhanced Notebook Experience

Positron provides a richer notebook experience with:

• Side-by-side code and output
• Interactive plots
• Integrated variable inspector
• Console integration

Troubleshooting

"Failed to start Keel Language Server"

Cause: keel CLI is not found in your PATH.

Solution:

1. Install keel-cli: cargo install --git https://codeberg.org/Keel/keel-cli
2. Or configure the full path in settings: keel.cli.path

Verify: Run keel lsp --help in your terminal.

"Formatter not found" or Format on Save Not Working

Cause: keel CLI is not installed or not in PATH.

Solution:

1. Install keel-cli, or
2. Configure the path: keel.formatter.path, or
3. Disable format-on-save: keel.formatter.formatOnSave: false

Verify: keel fmt --help

Jupyter Kernel Not Available

Cause: Keel kernel is not installed.

Solution:

cargo install --git https://codeberg.org/Keel/keel-jupyter-kernel
install-keel-kernel
jupyter kernelspec list  # Verify installation

Completion/Hover Not Working

Causes:

1. LSP server failed to start
2. File is not saved (LSP only analyzes saved files)
3. Syntax errors in the file

Solutions:

1. Check the "Keel" output panel for errors
2. Save the file (Ctrl+S)
3. Fix syntax errors shown as red squiggles
4. Restart the language server: Keel: Restart Language Server

Debugging LSP Issues

Enable verbose logging:

{
  "keel.trace.server": "verbose"
}

Check the "Keel" output panel (View → Output → select "Keel").