LSP Server Reference

LSP Server

Lectic includes a Language Server Protocol (LSP) server that makes editing .lec files more pleasant. It provides completions, diagnostics, folding, and other features that help you write correct configurations and navigate conversations.

Start the server with:

lectic lsp

The server uses stdio transport and works with any LSP-capable editor. See Editor Integration for setup instructions.

Features

Completions

The LSP suggests completions as you type:

  • Directives: Type : to see built-in directives (:cmd, :env, :fetch, :verbatim, :once, :discard, :attach, :ask, :aside, :reset) and any macros you’ve defined.
  • Interlocutor names: Inside :ask[ or :aside[, the LSP suggests names from your configuration.
  • Macro argument values: Inside :macro_name[...], if the macro defines completions, the LSP suggests argument values from inline data, file: sources, or exec: sources. exec: defaults to manual trigger policy.
  • YAML header fields: In the frontmatter, get suggestions for interlocutor properties (provider, model, thinking_effort, etc.), tool types, kit names, model names, and use: reference values (hook_defs, env_defs, sandbox_defs).
  • Tool types: Type - inside a tools: array to see available tool kinds (exec, sqlite, mcp_command, native, etc.).

Completions are case-insensitive and respect any prefix you’ve typed.

Diagnostics

The server catches errors before you run the file:

  • YAML syntax errors: Malformed frontmatter is flagged immediately.
  • Missing required fields: An interlocutor without a name or prompt triggers an error.
  • Unknown properties: A typo like promt instead of prompt shows a warning.
  • Duplicate names: If you define two interlocutors or macros with the same name, the LSP warns you. (The later definition wins at runtime.)

Folding

Tool calls and inline attachments can be long. The LSP provides folding ranges so your editor can collapse them:

:::Assistant

<tool-call with="search">        ← Fold starts here
...                              ← Hidden when folded
</tool-call>                     ← Fold ends here

Based on the search results...
:::

Both Neovim and VS Code plugins enable folding by default.

Hover Information

Hover over elements to see documentation:

  • Directives: Hover on built-in directives to see what they do.
  • Macros: Hover on a macro directive to preview its expansion.
  • Tool calls: Hover on a <tool-call> block to see a summary.

Go to Definition

Jump to where things are defined:

  • Place your cursor on a macro name and invoke “Go to Definition” to jump to the macro’s definition in your config.
  • Works for interlocutors, kits, and macros.
  • If multiple definitions exist (e.g., a local override of a system config), the LSP returns all locations, prioritized by proximity.

Document Outline

The LSP provides document symbols showing the conversation structure: messages, interlocutor responses, and configuration sections. Use your editor’s outline view to navigate long conversations.

Editor Setup

Neovim

Auto-start the LSP for .lec files:

vim.api.nvim_create_autocmd("FileType", {
  pattern = { "lectic", "markdown.lectic", "lectic.markdown" },
  callback = function(args)
    vim.lsp.start({
      name = "lectic",
      cmd = { "lectic", "lsp" },
      root_dir = vim.fs.root(args.buf, { ".git", "lectic.yaml" })
                 or vim.fn.getcwd(),
      single_file_support = true,
    })
  end,
})

For LSP-based folding:

vim.opt.foldmethod = 'expr'
vim.opt.foldexpr = 'v:lua.vim.lsp.foldexpr()'

With nvim-cmp, completions appear automatically on : and -. For bracket completions (interlocutor names), you may need to invoke completion manually with <C-Space> or <C-x><C-o>.

VS Code

Install the extension from extra/lectic.vscode or download the VSIX from releases. The extension starts the LSP automatically for .lec files.

Other Editors

Any editor that supports LSP over stdio can use the Lectic server. The command is lectic lsp with no arguments. See your editor’s documentation for how to configure external language servers.

Technical Details

Completion Sources

Completions are merged from multiple configuration sources, with later sources taking precedence:

  1. System config: $LECTIC_CONFIG/lectic.yaml
  2. Workspace config: lectic.yaml in the document’s directory
  3. The document’s YAML header

This matches the precedence used at runtime, so what you see in completions reflects what will actually be available.

Triggers

  • : triggers directive and macro completions
  • [ after directives triggers bracket-aware completions:
    • :ask[ / :aside[ for interlocutor names
    • :macro_name[ for macro argument completions (if configured)
  • - in a tools: array triggers tool type completions
  • use: in YAML maps suggests definition names for the matching kind (hook, env, or sandbox)

Limitations

  • Completion previews are static. The server doesn’t expand exec: or read file: references when showing hover/preview text.
  • Macro argument completions from exec: may run commands during editing. By default those are manual trigger only.
  • No completions are offered inside ::: fences (those are response blocks, not meant for editing).