@dex-ai/lsp

Real-time code feedback for Dex — LSP servers, linters, formatters, structural analysis & edit guardrails.

Overview

@dex-ai/lsp provides the AI coding agent with IDE-level code intelligence:

• 37+ Language Servers — TypeScript, Python, Go, Rust, Ruby, C/C++, Java, PHP, Zig, Bash, and more
• 4 Tools — diagnostics, navigation, ast-grep search, ast-grep replace
• Edit Guards — secrets scanner, read-before-edit enforcement, duplicate export detection
• Post-Write Pipeline — automatic diagnostics, lint feedback, deferred formatting
• Formatter Integration — Biome, Prettier, Ruff, gofmt, rustfmt

Installation

npm install @dex-ai/lsp

Add to your Dex configuration:

{
  "extensions": ["@dex-ai/lsp"]
}

Configuration

Create .dex/lsp.json in your project root:

{
  "disabledServers": [],
  "customServers": [],
  "format": {
    "enabled": true,
    "deferred": true,
    "onSave": false
  },
  "guards": {
    "readBeforeEdit": "warn",
    "secrets": true,
    "duplicateExports": true
  },
  "lint": {
    "biome": true,
    "ruff": true
  },
  "warmFiles": []
}

Configuration Reference

| Field | Type | Default | Description | |-------|------|---------|-------------| | disabledServers | string[] | [] | Server IDs to disable | | customServers | ServerDef[] | [] | Additional server definitions | | format.enabled | boolean | true | Enable formatting | | format.deferred | boolean | true | Queue formatting until turn-end | | format.onSave | boolean | false | Format immediately on write | | guards.readBeforeEdit | "off" \| "warn" \| "block" | "warn" | Read-before-edit enforcement | | guards.secrets | boolean | true | Secrets scanning | | guards.duplicateExports | boolean | true | Duplicate export detection | | lint.biome | boolean | true | Enable Biome lint | | lint.ruff | boolean | true | Enable Ruff (Python) lint | | warmFiles | string[] | [] | Files to pre-analyze on session start |

Custom Server Definition

{
  "customServers": [
    {
      "id": "my-server",
      "name": "My Server",
      "command": "my-lsp-server",
      "args": ["--stdio"],
      "extensions": [".myext"],
      "rootMarkers": ["my.config.json"],
      "initOptions": {}
    }
  ]
}

Tools

lsp_diagnostics

Get compiler/linter diagnostics for files or directories.

lsp_diagnostics({ path: "src/", severity: "error" })
lsp_diagnostics({ path: "src/foo.ts" })

Parameters:

• path (required) — File or directory path
• severity — Filter: "error" | "warning" | "information" | "hint"
• includeSource — Include source context lines (default: true)

lsp_navigation

IDE-level code navigation with 12 operations.

lsp_navigation({ operation: "definition", file: "src/foo.ts", line: 10, character: 5 })
lsp_navigation({ operation: "references", file: "src/foo.ts", line: 10, character: 5 })
lsp_navigation({ operation: "documentSymbols", file: "src/foo.ts" })

Operations: | Operation | Description | |-----------|-------------| | definition | Go to definition | | typeDefinition | Go to type definition | | implementation | Find implementations | | references | Find all references | | hover | Get type/doc info | | signatureHelp | Get function signature | | documentSymbols | List all symbols in file | | workspaceSymbols | Search workspace symbols | | rename | Compute rename edits | | codeActions | Get available code actions | | callHierarchyIn | Incoming calls | | callHierarchyOut | Outgoing calls |

ast_grep_search

AST-aware structural code search using ast-grep patterns.

ast_grep_search({ pattern: "console.log($$$)", lang: "typescript" })
ast_grep_search({ pattern: "import $NAME from '$MOD'", lang: "typescript", path: "src/" })

Parameters:

• pattern (required) — ast-grep pattern with metavariables ($X, $$$)
• lang (required) — Language: typescript, python, go, rust, etc.
• path — Scope search to path (default: workspace root)
• limit — Max results (default: 50)

ast_grep_replace

AST-aware find-and-replace with preview.

ast_grep_replace({
  pattern: "console.log($MSG)",
  replacement: "logger.info($MSG)",
  lang: "typescript",
  path: "src/"
})

Parameters:

• pattern (required) — Pattern to find
• replacement (required) — Replacement template (use same metavariables)
• lang (required) — Language
• path — Scope to path
• dryRun — Preview only, don't apply (default: false)

Edit Guards

Secrets Scanner

Automatically blocks writes containing credentials:

• AWS access/secret keys
• GitHub tokens (classic, fine-grained, OAuth)
• Stripe keys
• OpenAI/Anthropic API keys
• NPM tokens
• SSH/RSA private keys
• Database URLs with passwords
• Generic API key assignments

Exempt: test files, .md, .example, lockfiles.

Read-Before-Edit

Ensures files are read before being edited, preventing blind overwrites. Configurable: "off" | "warn" | "block".

Duplicate Export

Detects when a write would create duplicate exported symbols across the project.

Post-Write Pipeline

After every file write:

1. Sync — Notify LSP server of file change
2. Diagnostics — Collect new errors/warnings
3. Lint — Run Biome/Ruff on changed files
4. Format Queue — Queue file for formatting at turn-end

At turn-end (generate-input):

1. Format — Apply deferred formatting
2. Inject — Provide diagnostic summary to the next AI turn

Architecture

┌─────────────────────────────────────────────────────┐
│                Extension Entry Point                  │
├──────────┬──────────┬──────────┬────────────────────┤
│  Tools   │  Guards  │  Events  │     Services       │
│          │          │          │                    │
│ diagnost │ secrets  │ session  │  LSPService        │
│ navigat  │ read-be  │ tool-*   │  LintPipeline      │
│ ast-srch │ dup-exp  │ gen-*    │  FormatService     │
│ ast-repl │          │          │  RuntimeCoordinator│
└──────────┴──────────┴──────────┴────────────────────┘
         │                              │
         ▼                              ▼
┌─────────────────┐          ┌─────────────────────┐
│   LSP Client    │          │   ast-grep Client   │
│  (JSON-RPC)     │          │  (@ast-grep/napi)   │
└────────┬────────┘          └─────────────────────┘
         │ stdio
         ▼
┌─────────────────┐
│  Language Server │ × 37+
│  (typescript,   │
│   pyright, etc) │
└─────────────────┘

Supported Languages

| Language | Server | ID | |----------|--------|----| | TypeScript/JavaScript | typescript-language-server | typescript | | Python | pyright | python | | Go | gopls | go | | Rust | rust-analyzer | rust | | Ruby | ruby-lsp | ruby-lsp | | C/C++ | clangd | clangd | | Java | jdtls | java | | PHP | phpactor | php | | Zig | zls | zig | | Bash | bash-language-server | bash | | Lua | lua-language-server | lua | | Elixir | elixir-ls | elixir | | Kotlin | kotlin-language-server | kotlin | | Dart | dart language-server | dart | | Swift | sourcekit-lsp | swift | | C# | OmniSharp | csharp | | Haskell | haskell-language-server | haskell | | OCaml | ocamllsp | ocaml | | Scala | metals | scala | | Terraform | terraform-ls | terraform | | YAML | yaml-language-server | yaml | | JSON | vscode-json-languageserver | json | | HTML | vscode-html-languageserver | html | | CSS | vscode-css-languageserver | css | | Vue | vue-language-server | vue | | Svelte | svelte-language-server | svelte | | Astro | @astrojs/language-server | astro | | Prisma | prisma-language-server | prisma | | GraphQL | graphql-language-service-cli | graphql | | Dockerfile | dockerfile-language-server | dockerfile | | Nix | nil | nix | | SQL | sqls | sql | | R | languageserver | r | | Julia | LanguageServer.jl | julia | | Erlang | erlang_ls | erlang | | Perl | PLS | perl | | TOML | taplo | toml |

Development

# Install dependencies
npm install

# Build
npm run build

# Typecheck (includes tests)
npx tsc --noEmit

# Run tests
npm test

# Watch mode
npm run test:watch

License

MIT