pix-diagnostics

Pi extension — an LSP client for project-selected language servers.

What it does

• Reads language-server choices from <project>/.pi/lsp.json.
• Starts a configured server only when a visible tool call needs it.
• Registers one lsp tool with three actions: diagnostics, navigate, and mark.
• Reports diagnostics through lsp action diagnostics.
• Marks known diagnostics for the session (false-positive, suppress, defer, flagged) through lsp action mark (op: set, list, clear). Marks never change files.
• Shows a one-line LSP widget with error, warning, and file-state counts. The far right shows the age of the last check (for example 3m ago). After 5 minutes it shows stale · Nm ago in the warning color.
• Supports definition, references, hover, symbols, rename preview, and call hierarchy through lsp action navigate.
• Ships the pix-diagnostics skill (read_skills(name="pix-diagnostics", full=true)) with usage patterns.
• Opt-in syntax guard (edit.rejectNewSyntaxErrors in pix.json): an edit that adds a syntax error is undone and fails with the errors and fresh anchors.

Pix does not bundle, install, or select language servers. Use the lsp skill to choose a server for the project. The project owns the server and its version.

Project configuration

{
  "servers": {
    "python": {
      "command": "pyright-langserver",
      "args": ["--stdio"],
      "extensions": [".py", ".pyi"],
      "languageId": "python",
      "rootMarkers": ["pyproject.toml", ".git"]
    }
  }
}

Required fields: command, extensions, and languageId. Optional fields: args, filenames, and rootMarkers.

Local TypeScript server

Install the server as a project development dependency:

bun add --dev typescript-language-server

TypeScript must also exist in the project dependencies. Add this server to <project>/.pi/lsp.json:

{
  "servers": {
    "typescript": {
      "command": "bun",
      "args": ["run", "typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
      "languageId": "typescript",
      "rootMarkers": ["tsconfig.base.json", "package.json", ".git"]
    }
  }
}

The wrapper uses the project-local server, not a global installation. Run /reload after you change the server configuration. Then call lsp with action: "diagnostics", source: "lsp", and explicit file paths. This configuration does not add a JSON language server.

Diagnostic states

• clean: the server confirms that the file has no findings.
• findings: the server returns one or more diagnostics.
• unavailable: no configured server can run for the file.
• unconfirmed: the client cannot confirm diagnostics within the wait budget.

An unconfirmed result does not mean that the file is clean.

Install

pi install npm:@xynogen/pix-diagnostics

Bundled in @xynogen/pix-core. Install it alone only if you do not use pix-core.

Full distro

This package is part of Pix. The installer sets up Pi and the full distro. See Install for the notes for each OS.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex

License

MIT

The LSP engine adapts code from pi-lens (MIT). See LICENSE.pi-lens.