| name | lsp-client |
| description | Use when verifying Tcl LSP server behavior: semantic tokens, diagnostics, formatting, hover, completion, definition, references, code actions, optimizations, document symbols, diagram extraction, event/command registry lookups, or benchmarking server performance and collecting timing logs. Tests the server directly over JSON-RPC without VS Code.
|
| allowed-tools | Bash, Read |
Tcl LSP Client
Runs a standalone LSP client that starts the Tcl language server, exercises
an LSP feature against a Tcl file, and prints human-readable results.
Use this to verify server behavior after making changes.
Usage
Run from the project root (the git worktree directory):
python3 .claude/skills/lsp-client/lsp_client.py <subcommand> <args...>
The script auto-detects the tcl-lsp/ server directory. Override with
--server-dir /path/to/tcl-lsp if needed.
Subcommands
| Subcommand | Arguments | What it does |
|---|
semantic-tokens | <file.tcl> | Decode and display all semantic tokens with types |
diagnostics | <file.tcl> | Show warnings, errors, hints from the analyzer and optimizer |
format | <file.tcl> | Show formatting edits the server would apply |
hover | <file.tcl> <line> <col> | Show hover info at a 0-based position |
completion | <file.tcl> <line> <col> | Show completions at a 0-based position |
definition | <file.tcl> <line> <col> | Show go-to-definition locations |
references | <file.tcl> <line> <col> | Show all reference locations |
code-actions | <file.tcl> <l> <c> <el> <ec> | Show code actions in a 0-based range |
optimize | <file.tcl> | Show optimization suggestions and rewritten source |
symbols | <file.tcl> | Show document symbol hierarchy (procs, events, namespaces, variables) |
diagram | <file.tcl> | Extract control flow diagram data from compiler IR |
event-info | <EVENT_NAME> | Show iRules event registry metadata (no file needed) |
command-info | <COMMAND_NAME> | Show iRules command registry metadata (no file needed) |
context | <file.tcl> | Build context pack: diagnostics + symbols + event metadata |
all | <file.tcl> | Run semantic-tokens + diagnostics + symbols + format + optimize together |
bench | <file.tcl> [--iterations N] | Benchmark time-to-semantic-tokens with server timing breakdown |
logs | <file.tcl> [--timing-only] | Collect and display server logs and timing information |
All line/col arguments are 0-based, matching the LSP protocol.
Interpreting Output
Semantic Tokens
Each token shows line:col type "text":
0:0 keyword "set"
0:4 string "name"
1:0 keyword "puts"
1:5 variable "$name"
Token types: keyword, function, variable, string, comment, number,
operator, parameter, namespace, regexp.
Diagnostics
WARNING W100 2:4-2:18 Unbraced expr in 'if' condition
HINT W302 5:0-5:12 catch without result variable
INFO O101 3:10-3:18 Fold constant expression
Optimizer suggestions (O100, O101, O102) appear as INFO-level diagnostics
with QuickFix code actions in VS Code.
Optimizations
=== Optimizations (2 items) ===
O101 2:10-2:18 Fold constant expression → "{3}"
O102 3:8-3:27 Fold constant expr command substitution → "3"
=== Optimized Source ===
set a 1
set b 3
...
Shows each optimization and the fully rewritten source.
Symbols
=== Symbol Definitions (4 symbols) ===
Event HTTP_REQUEST (line 1)
Event HTTP_RESPONSE (line 15)
Function my_proc (a b) (line 25)
Variable result (line 26)
Hierarchical display of events, procs, namespaces, and variables.
Diagram Data
Shows events in canonical firing order with multiplicity and priority,
procedures with parameters, and the full structured JSON for diagram
generation.
Event Info
=== Event Info ===
Event: HTTP_REQUEST
Known: yes
Deprecated: no
Valid commands: 87
Sample commands: HTTP::host, HTTP::path, HTTP::method, ...
Command Info
=== Command Info ===
Command: HTTP::uri
Summary: Returns or sets the HTTP URI
Synopsis: HTTP::uri [<uri>]
Valid in: HTTP_REQUEST, HTTP_RESPONSE, ...
Context Pack
Combined output for AI skill consumption:
=== Context Pack ===
Dialect: f5-irules
File: redirect.tcl
Lines: 42
=== Diagnostics (2) ===
WARNING W100 line 15: unbraced expression in expr
WARNING W304 line 22: missing -- option terminator
=== Symbol Definitions (3) ===
Event HTTP_REQUEST (line 1)
Event HTTP_RESPONSE (line 15)
Function my_proc (a b) (line 25)
=== Event Metadata (2 events, in source order) ===
HTTP_REQUEST: known=yes, deprecated=no, validCommands=87
sample: HTTP::host, HTTP::path, HTTP::method, HTTP::uri
HTTP_RESPONSE: known=yes, deprecated=no, validCommands=45
sample: HTTP::header, HTTP::status
Hover
Shows the markdown content the editor would display on hover.
Completions
Shows label, kind (Keyword, Function, Variable), and detail.
Bench
Measures wall-clock time from request to semantic token response, plus
server-side timing breakdown from [timing] log entries:
=== Benchmark ===
File: 09_long_code.tcl
Lines: 540, Size: 15208 bytes
Iterations: 3
Iteration 1:
Wall clock (request → response): 445.1ms
Tokens: 1557
Server timings:
_build_full_chunk_caches: 1ms
semantic_tokens_full: 200ms
semanticTokens/full: 200ms
workspace_state.update: 459ms
After mid-file edit:
Wall clock: 180.5ms
Server timings:
workspace_state.update: 150ms
Use --iterations N to run multiple open/close cycles for reliable medians.
The edit benchmark simulates a mid-file change to measure incremental
update performance.
Logs
Shows server stderr and window/logMessage notifications. Use --timing-only
to filter to just [timing] entries for performance analysis.
When to Use
- After changing semantic token logic, verify tokens are correct
- After changing diagnostic checks, verify warnings appear
- After changing the formatter, verify edit output
- After changing the optimizer, verify suggestions and rewrites
- Quick smoke test with
all on any example file
- Verify position-dependent features (hover, completion, definition)
at specific cursor locations
- Use
context to build rich LSP context for AI skill consumption
- Use
diagram to extract structured flow data for Mermaid generation
- Use
event-info / command-info to look up iRules registry metadata
- After performance changes, use
bench to measure time-to-semantic-tokens
- Use
logs --timing-only to see the server-side timing breakdown
Example Invocations
python3 .claude/skills/lsp-client/lsp_client.py semantic-tokens tcl-lsp/samples/for_screenshots/03-completions.tcl
python3 .claude/skills/lsp-client/lsp_client.py diagnostics tcl-lsp/editors/vscode/testFixture/diagnostics.tcl
python3 .claude/skills/lsp-client/lsp_client.py hover tcl-lsp/editors/vscode/testFixture/procs.tcl 1 6
python3 .claude/skills/lsp-client/lsp_client.py optimize tcl-lsp/samples/for_screenshots/22-optimiser-before.tcl
python3 .claude/skills/lsp-client/lsp_client.py symbols tcl-lsp/samples/for_screenshots/ai-scene.irul
python3 .claude/skills/lsp-client/lsp_client.py diagram tcl-lsp/samples/for_screenshots/ai-scene.irul
python3 .claude/skills/lsp-client/lsp_client.py event-info HTTP_REQUEST
python3 .claude/skills/lsp-client/lsp_client.py command-info HTTP::uri
python3 .claude/skills/lsp-client/lsp_client.py context tcl-lsp/samples/for_screenshots/ai-scene.irul
python3 .claude/skills/lsp-client/lsp_client.py all tcl-lsp/samples/for_screenshots/03-completions.tcl
python3 .claude/skills/lsp-client/lsp_client.py bench tcl-lsp/samples/tcl/09_long_code.tcl --iterations 3
python3 .claude/skills/lsp-client/lsp_client.py logs tcl-lsp/samples/tcl/09_long_code.tcl --timing-only
$ARGUMENTS
