Language servers

Kolega Code can start local Language Server Protocol (LSP) servers for detected project languages. LSP is enabled by default and is used for:

• diagnostics after edit, multi_edit, and write;
• the generic read-only lsp tool;
• the permission-gated lsp_edit tool;
• the resolve tool, which applies or discards a pending lsp_edit(apply: false) preview;
• /lsp and the Settings screen’s Tools status display.

The lsp tool remains read-only. Mutating LSP operations are exposed through lsp_edit, which is treated like edit, multi_edit, and write for permission prompts. resolve mutates files only when it applies a pending preview, so it is gated the same way. Kolega Code does not expose raw arbitrary LSP requests.

Enabling and disabling

LSP can be turned off (or forced back on) at three levels, resolved as flag > environment > settings:

• --lsp <on|off> — forces the switch for one session, on both the TUI and ask. It overrides the saved setting but is never persisted; the next launch without the flag re-reads settings.
• KOLEGA_CODE_LSP=<on|off> — environment override, useful for headless or benchmark runs.
• The LSP toggle in the Settings screen’s Tools tab — persisted in settings.json as lsp_enabled.

When LSP is disabled, no language servers are started, post-edit diagnostics are skipped, and the lsp, lsp_edit, and resolve tools are removed from the model’s toolset entirely. resolve is LSP-coupled: pending actions are only ever created by lsp_edit(apply: false), so none can exist while LSP is off.

Tool operations

The generic lsp tool supports:

• diagnostics for file errors, warnings, and hints;
• definition, type_definition, implementation, references, and hover;
• document_symbols and workspace_symbols;
• call_hierarchy for incoming and outgoing calls;
• code_actions to list available quick fixes and refactors without applying them;
• status, capabilities, and reload.

Position operations use path, a 1-based line, and a symbol on that line. Use symbol#2 to select the second occurrence of a symbol on the same line. code_actions includes an action_id for each action so a later lsp_edit call can apply the exact server-provided action.

The mutating lsp_edit tool supports:

• rename for symbol rename;
• rename_file for file moves with workspace/willRenameFiles and workspace/didRenameFiles notifications;
• format_document and format_range;
• apply_code_action by action_id, title/query, or index.

lsp_edit applies server-provided WorkspaceEdit payloads only. If the server does not advertise or return an edit for an operation, Kolega Code reports that the operation is unsupported instead of constructing a manual fallback edit. Pass apply: false to preview the LSP edit without writing files; the preview is recorded as a pending action that the resolve tool then applies or discards (resolve(action_id=..., decision="apply"|"discard")), subject to the same edit-permission prompt as lsp_edit itself.

External paths, permissions, and undo

Local file: URIs returned by a language server may target files outside the project. Initiating paths can likewise be project-relative, use ../ traversal, or be absolute. The existing edit permission gate still applies to the request, and the Vibe edit policy checks every touched path before mutation.

A mutation that touches any external path—including a mix of project and external files—is not snapshotted and cannot be undone through snapshot restore. With apply: false, such an external or mixed edit can be previewed but cannot create a snapshot-backed, resolvable pending action. To perform it, rerun the operation with apply: true.

Project configuration

Create <project>/.kolega/lsp.json to override LSP behavior for a repository. Project LSP config is trusted input because custom servers can execute local binaries. Kolega Code ignores this file unless the session is started with --trust-lsp or the project is listed in trusted LSP projects in user settings.

{
  "enabled": true,
  "auto_diagnostics_on_edit": true,
  "max_diagnostics": 20,
  "auto_fallback": true,
  "prompt_on_missing": true,
  "disabled_languages": [],
  "preferences": {
    "python": "pyright"
  },
  "diagnostic_servers": ["ruff-lsp"],
  "initialization_options": {
    "pyright": {
      "python": {
        "analysis": {
          "typeCheckingMode": "basic"
        }
      }
    }
  },
  "workspace_configuration": {
    "pyright": {
      "python": {
        "analysis": {
          "typeCheckingMode": "basic"
        }
      }
    }
  },
  "servers": {
    "custom-python-lsp": {
      "bin": "custom-lsp",
      "args": ["--stdio"],
      "languages": ["python"],
      "env": {
        "CUSTOM_LSP_MODE": "project"
      }
    }
  }
}

The project file cannot change the user’s global LSP kill switch: enabled is accepted in user settings, but ignored from .kolega/lsp.json.

preferences chooses the preferred server for a language. If auto_fallback is false, Kolega Code checks only the preferred server before reporting the language as missing. If it is true, installed alternatives can be used automatically.

diagnostic_servers starts additional servers for diagnostics alongside the primary server. This is useful for setups such as Pyright plus Ruff.

initialization_options is sent in the LSP initialize request. Some servers also ask for workspace/configuration; use workspace_configuration for those responses, keyed first by server name and then by requested section.

Status and troubleshooting

Run /lsp in the TUI to see detected languages, missing servers, active sessions, and recent diagnostic counts. The full Settings screen’s Tools category has a global LSP toggle; applying a change rebuilds the agent.

If a server is missing, /lsp shows the server name and install guidance from Kolega Code’s bundled registry. You can suppress a language with disabled_languages or point it at a custom server with servers and preferences.