LSP Assist

Precise code navigation via Language Server Protocol.

Modes

Mode	How	When to use
Daemon (recommended)	INLINECODE0 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

• - Project config:

- TypeScript: tsconfig.json in project root - Python: pyproject.toml or INLINECODE6

Security

Binding

Daemon binds to 127.0.0.1 only — no external/remote access: CODEBLOCK0

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, .., ~)
• INLINECODE12 rejects 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_GET and do_POST before 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)

CODEBLOCK4

One-shot Mode

Action	Command
Go to definition	INLINECODE22
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:

CODEBLOCK5

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	INLINECODE30
Python

pyright | pip install pyright |

Adding a language: edit SERVERS dict in lsp_client.py — add the server command and file extensions.