Lsp Assist
Language Server Protocol integration for OpenClaw agents. Enables precise code navigation: go-to-definition, find-references, hover type info, diagnostics, and symbol search. Supports TypeScript (via typescript-language-server) and Python (via pyright). Two modes: one-shot (query then quit) and daemon (persistent server for multi-query sessions). Use when editing code and need to find where a function/type is defined, see all usages, check types, diagnose errors, or search workspace symbols. Use when the user says "go to definition", "find references", "what does this type mean", "check for errors", or when navigating large codebases where grep is insufficient.
LSP Assist
Precise code navigation via Language Server Protocol.
Modes
| Mode | How | When to use |
|---|---|---|
| Daemon (recommended) | daemon --port 9876 then HTTP queries | Multiple queries in a session (start once, query many) |
| One-shot | goto/refs/hover/diag/symbols directly | Single quick query, or scripting |
Requirements
- Runtime: Python 3.10+ (standard library only)
- OS: Linux, macOS
- Language servers (install separately):
- TypeScript:
npm i -g typescript-language-server typescript - Python:
pip install pyright
- TypeScript:
- Project config:
- TypeScript:
tsconfig.jsonin project root - Python:
pyproject.tomlorpyrightconfig.json
- TypeScript:
Security
Binding
Daemon binds to 127.0.0.1 only — no external/remote access:
server = HTTPServer(("127.0.0.1", port), DaemonHandler)
File Access Control
All file reads go through _open_file(), which enforces project-root containment:
def _open_file(self, filepath: str):
path = Path(filepath).resolve() # resolve symlinks, .., etc.
if str(path) in self._opened_files:
return # skip duplicate opens
common = os.path.commonpath([str(path), self.root_path])
if common != self.root_path: # must be direct ancestor of root
raise ValueError(f"File outside project root: {path}")
# Only then: read file content and send didOpen to language server
Path.resolve()canonicalizes the path (resolves symlinks,..,~)os.path.commonpathrejects sibling dirs (e.g./root/openclaw-backup/when root is/root/openclaw)- Tested against: symlink escape,
..traversal, trailing-slash differences, sibling-prefix collision
Auth Token (optional)
When --token <secret> is passed, every HTTP request must include Authorization: Bearer <secret>:
def _check_auth(self) -> bool:
expected = getattr(self.server, "auth_token", None)
if expected is None:
return True # no token required
header = self.headers.get("Authorization", "")
if header == f"Bearer {expected}":
return True
self._respond({"error": "unauthorized"}, 401)
return False
- Checked in both
do_GETanddo_POSTbefore any handler logic - Without
--token, daemon is open on localhost (intended for local single-user use)
Shutdown Handling
elif self.path == "/shutdown":
self._respond({"status": "shutting down"})
threading.Thread(target=lambda: (time.sleep(0.5), os._exit(0)), daemon=True).start()
Responds first, then exits after 0.5s delay to ensure the HTTP response is flushed.
Process Isolation
- One-shot mode: fresh server per query, auto-terminates (15s timeout)
- Daemon mode: persistent server, but
is_alive()check returns 503 if the language server crashes - Language server communication is local stdio only
Quick Reference
Daemon Mode (recommended for multi-query)
# Start daemon (blocks, run in background or separate terminal)
python3 scripts/lsp_client.py daemon --lang typescript --root /path/to/project --port 9876
# Start with auth token (requests need Bearer token)
python3 scripts/lsp_client.py daemon --lang typescript --root /path/to/project --port 9876 --token mysecret
# Query via HTTP (all output JSON)
curl -s http://127.0.0.1:9876/goto -d '{"file":"src/main.ts","line":10,"col":5}'
curl -s http://127.0.0.1:9876/refs -d '{"file":"src/main.ts","line":10,"col":5}'
curl -s http://127.0.0.1:9876/hover -d '{"file":"src/main.ts","line":10,"col":5}'
curl -s http://127.0.0.1:9876/diag -d '{"file":"src/main.ts"}'
curl -s http://127.0.0.1:9876/symbols -d '{"query":"UserService"}'
curl -s http://127.0.0.1:9876/shutdown
curl -s http://127.0.0.1:9876/ping # health check
# With auth token
curl -s -H "Authorization: Bearer mysecret" http://127.0.0.1:9876/ping
One-shot Mode
| Action | Command |
|---|---|
| Go to definition | python3 scripts/lsp_client.py --lang ts --root <dir> goto --file <f> --line <n> --col <n> |
| Find references | python3 scripts/lsp_client.py --lang ts --root <dir> refs --file <f> --line <n> --col <n> |
| Hover type info | python3 scripts/lsp_client.py --lang ts --root <dir> hover --file <f> --line <n> --col <n> |
| Diagnostics | python3 scripts/lsp_client.py --lang ts --root <dir> diag --file <f> |
| Symbol search | python3 scripts/lsp_client.py --lang ts --root <dir> symbols [--query <text>] |
Language shorthand: --lang typescript or --lang ts or --lang python.
Output Format
All commands output JSON for structured consumption:
// goto / refs
[{"file": "/path/to/file.ts", "line": 42, "col": 10}]
// hover
"function foo(bar: string): number"
// diag
[{"severity": "ERROR", "line": 10, "message": "Cannot find name 'x'"}]
// symbols
[{"name": "UserService", "kind": 5, "file": "/path/to/file.ts", "line": 12, "container": "models"}]
When to Use vs Grep
| Scenario | Use |
|---|---|
| "Where is this function defined?" | LSP goto |
| "Who calls this function?" | LSP refs |
| "What type is this variable?" | LSP hover |
| "Any compile errors?" | LSP diag |
| "Find all classes matching X" | LSP symbols |
| "Search for text pattern 'TODO'" | grep |
| "Find all .json files" | glob |
| "Search across non-code files" | grep |
Supported Languages
| Language | Server | Install |
|---|---|---|
| TypeScript/JavaScript | typescript-language-server | npm i -g typescript-language-server typescript |
| Python | pyright | pip install pyright |
Adding a language: edit SERVERS dict in lsp_client.py — add the server command and file extensions.
Related skills
- Downloads
- Security audit
- Review
- Last updated
- 6mo ago
- Current version
- v1.1.2
- License
- MIT-0
