Language Server Protocol

behave-lint includes an LSP server for real-time diagnostics in any LSP-compatible editor (VS Code, Neovim, Emacs, etc.).

Installation

Install with the lsp optional dependency:

pip install behave-lint[lsp]

Or with uv:

uv add 'behave-lint[lsp]'

Usage

The LSP server communicates over stdio:

behave-lint-lsp

Editor configuration

VS Code

Add the following to .vscode/settings.json:

{
  "gherkin-lint.server.path": "behave-lint-lsp",
  "gherkin-lint.enabled": true
}

Or use a custom extension that connects to the server.

Neovim (nvim-lspconfig)

local lspconfig = require('lspconfig')
lspconfig.behave_lint.setup({
  cmd = { 'behave-lint-lsp' },
  filetypes = { 'gherkin', 'feature' },
  root_dir = function(bufnr, callback)
    callback(vim.fn.getcwd())
  end,
})

Emacs (eglot)

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '((feature-mode) "behave-lint-lsp")))

Generic LSP client

Any LSP client that supports stdio transport can connect to behave-lint-lsp. The server advertises:

• textDocument/didOpen — lint on file open
• textDocument/didChange — re-lint on every edit (incremental sync)
• textDocument/didSave — re-lint on save
• textDocument/didClose — clear diagnostics
• textDocument/codeAction — quick fixes for fixable diagnostics
• workspace/didChangeConfiguration — update settings and re-lint all open documents

Features

• Real-time diagnostics — errors, warnings, and info from all 50 built-in rules
• Quick fixes — textDocument/codeAction returns QuickFix actions with TextEdits for all 14 auto-fixable rules. Click the lightbulb in your editor to apply safe and unsafe fixes.
• Workspace configuration — configure select, ignore, profile, group, severityOverrides, and ruleParams directly from editor settings (e.g. VS Code settings.json). Changes trigger re-linting of all open .feature documents.
• Incremental document sync — the server applies partial range-based changes efficiently without receiving the full document on every edit
• Full document sync — full-document changes (no range) are also supported for clients that prefer full sync
• Source attribution — all diagnostics are tagged with source: behave-lint
• Rule codes — each diagnostic includes the rule ID (e.g. BC001, BS001) as the diagnostic code

Editor Configuration

The LSP server reads workspace configuration sent by the editor. The following settings are supported (under the behave-lint section):

Setting	Type	Description
select	string[]	Rule IDs to enable (empty = all)
ignore	string[]	Rule IDs to disable
profile	string	Profile name: recommended, strict, minimal
group	string[]	Group names: correctness, style, pedantic
severityOverrides	object	Per-rule severity overrides
ruleParams	object	Per-rule parameters

VS Code example

{
  "behave-lint": {
    "profile": "recommended",
    "ignore": ["BD003"]
  }
}

Neovim example

vim.lsp.config('behave-lint', {
  settings = {
    ['behave-lint'] = {
      profile = 'recommended',
      ignore = { 'BD003' },
    }
  }
})

Limitations

• None currently