LSP Server¶

t-linter includes a built-in Language Server Protocol (LSP) server for editor integration.

Starting the Server¶

t-linter lsp

The LSP server communicates over stdin/stdout using the standard LSP protocol.

Features¶

The LSP server provides:

• Semantic Tokens — syntax highlighting for embedded languages in template strings
• Diagnostics — real-time validation of embedded language syntax (debounced at 250ms)
• Document Formatting — full document formatting of template literals
• Range Formatting — format a single template literal by selecting its range
• Code Actions — save-time and manual rewrite actions for VSCode and other editors

Feature Support by Language¶

For HTML, T-HTML, JSON, YAML, and TOML templates:

• Diagnostics are published from the dedicated Rust backends for strict validation
• Formatting requests and code actions rewrite the whole template literal using the backend formatter

Code Action Kinds¶

The server advertises textDocument/codeAction support with two t-linter-specific kinds:

• source.fixAll.t-linter — document-level formatting for all format-capable template literals in the file
• refactor.rewrite.t-linter — selection-based rewrite for exactly one template literal

source.fixAll.t-linter returns a direct WorkspaceEdit instead of a follow-up command so save-time execution stays deterministic.

refactor.rewrite.t-linter is returned only when the requested range maps to exactly one template literal. If the selection hits no templates, or spans multiple templates, the server returns no action.

The existing textDocument/formatting and textDocument/rangeFormatting endpoints remain available for backward compatibility.

Line Length Resolution¶

For HTML and T-HTML formatting, line length is resolved in this order:

1. textDocument/formatting or textDocument/rangeFormatting custom option printWidth
2. custom option lineLength
3. pyproject.toml tool.t-linter.line-length
4. default 80

Code actions do not carry formatting options, so they use steps 3 and 4 only.

Editor Integration¶

Claude Code¶

Add t-linter as an LSP server in your project's .claude/settings.json:

{
  "lsp": {
    "t-linter": {
      "command": "t-linter",
      "args": ["lsp"],
      "languages": ["python"]
    }
  }
}

Claude Code will then use t-linter's diagnostics when editing Python files containing template strings.

You can also use the CLI commands directly:

t-linter check src/
t-linter format --check src/

Codex¶

Use t-linter's CLI commands directly within your Codex workflow:

# Validate template strings
t-linter check src/

# Check formatting without modifying files
t-linter format --check src/

To integrate into your development workflow, add t-linter checks to your project's lint configuration or CI pipeline.

VSCode¶

The VSCode extension uses this server automatically. No additional LSP configuration is needed.

Recommended Ruff coexistence settings:

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll.t-linter": "explicit"
    }
  }
}

VSCode supports only one default formatter per language, which is why t-linter exposes save-time template formatting through source.fixAll.t-linter instead of asking you to replace Ruff.

Neovim¶

vim.lsp.start({
  name = "t-linter",
  cmd = { "t-linter", "lsp" },
  filetypes = { "python" },
})

Other Editors¶

Any editor with LSP support can use t-linter. Configure the LSP client to start t-linter lsp as the server command for Python files.