ZLS Integration Skill

ZLS Integration Skill

Zig Language Server (ZLS) provides IDE features for Zig development. This skill covers installation, configuration, build-on-save diagnostics, and troubleshooting.

Quick Reference

Feature	ZLS Support	Notes
Autocomplete	✓ Full	Includes comptime-aware completion
Goto Definition	✓ Full	Cross-file navigation
Find References	✓ Full	All usages in workspace
Hover Documentation	✓ Full	Inline docs from source
Diagnostics	⚡ Parser-level	Semantic via build-on-save
Rename Symbol	✓ Full	Safe refactoring
Code Actions	✓ Partial	Fix imports, remove unused
Formatting	✓ Full	Uses zig fmt

Installation

Via Package Manager (Recommended)

# macOS (Homebrew)
brew install zls

# Nix/Flox
flox install zls

# Arch Linux
pacman -S zls

# From source (any platform)
git clone https://github.com/zigtools/zls
cd zls
zig build -Doptimize=ReleaseSafe

Version Compatibility

Zig Version	ZLS Version	Notes
0.15.x	0.15.x	Current stable
0.14.x	0.14.x	Previous stable
0.13.x	0.13.x	Legacy
master	master	Build from source

Always match ZLS version to Zig version.

Configuration

zls.json Location

~/.config/zls.json           # Linux/macOS
%APPDATA%\zls.json           # Windows
<project>/.zls.json          # Project-specific

Essential Configuration

{
  "zig_exe_path": "/path/to/zig",
  "enable_autofix": true,
  "enable_import_access": true,
  "highlight_global_var_declarations": true,
  "warn_style": true,
  "enable_build_on_save": true,
  "build_on_save_step": "check"
}

Build-On-Save Diagnostics

ZLS can run your build script on save to catch semantic errors (type mismatches, wrong argument counts) that parser-level analysis misses.

Step 1: Add Check Step to build.zig

// build.zig
pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    b.installArtifact(exe);

    // ZLS check step - runs on save
    const check = b.addExecutable(.{
        .name = "myapp",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });
    
    const check_step = b.step("check", "Check compilation (for ZLS)");
    check_step.dependOn(&check.step);
}

Step 2: Configure ZLS

{
  "enable_build_on_save": true,
  "build_on_save_step": "check"
}

Step 3: Editor Setup

VS Code (zls extension):

// settings.json
{
  "zig.zls.path": "/path/to/zls",
  "zig.zls.enableBuildOnSave": true
}

Neovim (nvim-lspconfig):

require('lspconfig').zls.setup({
  settings = {
    zls = {
      enable_build_on_save = true,
      build_on_save_step = "check"
    }
  }
})

Emacs (lsp-mode):

(setq lsp-zig-zls-executable "/path/to/zls")
(setq lsp-zig-enable-build-on-save t)

Troubleshooting

No Diagnostics Appearing

1. Verify ZLS is running: pgrep -l zls
2. Check ZLS log: ~/.cache/zls/zls.log
3. Ensure Zig version matches: zig version vs zls --version
4. Test build manually: zig build check

Slow Completions

{
  "skip_std_references": true,
  "prefer_ast_check_as_child_process": true
}

Import Resolution Failures

{
  "enable_import_access": true,
  "additional_module_paths": ["deps/", "vendor/"]
}

Build-On-Save Not Working

1. Verify check step exists in build.zig
2. Run zig build check manually
3. Check ZLS config: enable_build_on_save: true
4. Restart language server

GF(3) Integration

ZLS diagnostics map to triadic workflow:

Diagnostic Type	Trit	Action
Error (red)	-1	Must fix before build
Warning (yellow)	0	Review, may ignore
Hint (blue)	+1	Optimization opportunity

Conservation: errors + warnings + hints → 0 as code improves.

Editor Integration Matrix

Editor	Plugin	Config Path
VS Code	zls (extension)	.vscode/settings.json
Neovim	nvim-lspconfig	init.lua or lsp.lua
Helix	Built-in	languages.toml
Emacs	lsp-mode + lsp-zig	init.el
Sublime	LSP-zig	*.sublime-settings
Vim	vim-lsp or coc.nvim	.vimrc or coc-settings.json

Related Skills

• zig-programming - Core Zig language and stdlib
• zig-async-io - Async/concurrent patterns (0.16.0+)
• tree-sitter - AST-based code analysis

Resources

• ZLS GitHub
• ZLS Configuration Guide
• Build-On-Save Guide
• Zig BBQ Cookbook

Scientific Skill Interleaving

This skill connects to the K-Dense-AI/claude-scientific-skills ecosystem:

Graph Theory

• networkx [○] via bicomodule
  • Universal graph hub

Bibliography References

• general: 734 citations in bib.duckdb

Cat# Integration

This skill maps to Cat# = Comod(P) as a bicomodule in the equipment structure:

Trit: 0 (ERGODIC)
Home: Prof
Poly Op: ⊗
Kan Role: Adj
Color: #26D826

GF(3) Naturality

The skill participates in triads satisfying:

(-1) + (0) + (+1) ≡ 0 (mod 3)

This ensures compositional coherence in the Cat# equipment structure.