---
name: lsp-cli
description: >-
  MANDATORY for Chromium C/C++ semantic analysis and compiler diagnostics.
  Activate before exact symbol, definition, caller, implementation,
  inheritance, or call-stack analysis, and after every C/C++ edit. Diagnostics
  for every modified C/C++ file must report zero errors before a build; report
  and stop when the CLI, session, or diagnostics are unavailable.
---

# lsp-cli (C++ MCP CLI)

lsp-cli.py is a lightweight CLI front-end to the C++ MCP server. It connects
using the session cached in `.lsp-cli.json`. Use it for precise, index-backed
C++ symbol lookup in the large Chromium tree.

## Hard stops

Before semantic analysis or diagnostics, locate `lsp-cli.py` at the project
root or in this skill directory. If it is missing, report that exact condition
and STOP.

The cached `.lsp-cli.json` session and its endpoint must be usable. If the
file is missing, its endpoint is unavailable, or a CLI command exits non-zero,
report the command and complete failure output, then STOP. Do not guess an
endpoint, try an alternate endpoint, or create or replace a session cache
without a new user instruction.

**ALWAYS** On any other errors related to `lsp-cli.py` -- report to user and
stop, do not act on your own.

## Required diagnostic gate

After every C/C++ source or header edit, run diagnostics for every modified
file before starting a build:

```sh
./lsp-cli.py diagnostics path/to/modified/file1.cc path/to/modified/file2.h
```

Report all errors and warnings. Zero errors is required to proceed to a build.
If diagnostics report any error, cannot cover every modified file, or fail to
run, report the result and STOP. Do not build, retry, or substitute another
compiler-diagnostic command until the user gives a new instruction.

## How to get more information

```sh
./lsp-cli.py --help # to get available arguments and examples
```

`--build-directory` should be inherited from running server (no need to specify explicitly in normal usage)

## Typical usage examples

All commands run from the project root (`/media/vptyp/images1/webos-ose/chromium/src`).
The server resolves the default build directory from the project-root
`compile_commands.json`, so `--build-directory` is only needed when you want a
different build dir than the default.

### 1. Orient: project layout and index state

```sh
./lsp-cli.py project                       # build dirs, compilation flags + compilation database the server resolved
./lsp-cli.py index                          # snapshot of clangd indexing progress
./lsp-cli.py index --wait-timeout 300       # block (up to 300s) until clangd reports done
```

Note: while clangd is *loading* an existing on-disk index (not building),
`index` may report `progress_percentage: 0.0` even though queries already
work. Trust a successful `search`/`analyze` over the percentage during load.

### 2. Find symbols

Search uses clangd fuzzy matching against the *qualified* name, so scoped
queries work:

```sh
./lsp-cli.py search "InfoBar::Show"             # scoped query -> infobars::InfoBar::Show
./lsp-cli.py search "Show" --kind Method        # bare name, restrict to methods
./lsp-cli.py search "Buffer" --kind Class Struct # find types only
./lsp-cli.py search "" --files chrome/browser/extensions/api/tabs/tabs_api.cc  # list a file's symbols
./lsp-cli.py search "std::" --include-external   # include system/library symbols
./lsp-cli.py search "InfoBar" --max-results 20   # cap result count
```

Kinds are PascalCase, one or more: `Class Struct Function Method Field
Constructor Interface Module Namespace Enum` (see `search --help`).

### 3. Deep analysis of one symbol

`analyze` returns definition, hover, usage examples, and (when applicable)
inheritance + call hierarchy. It auto-selects the analyses that fit the symbol
kind — no flags for inheritance/call hierarchy.

```sh
./lsp-cli.py analyze "InfoBar::Show"                          # full context
./lsp-cli.py analyze "InfoBar::Show" --max-examples 5         # cap usage examples
./lsp-cli.py analyze "foo" --location-hint path/to/file.cc:42:15  # disambiguate an overload
```

`--location-hint` is `FILE:LINE:COL` and resolves a specific overload when the
name alone is ambiguous.

### 4. Diagnostic gate (run after every C/C++ edit)

Accepts one or more files; run it for every modified source/header before a
build and require zero errors:

```sh
./lsp-cli.py diagnostics chrome/browser/extensions/api/tabs/tabs_api.cc
./lsp-cli.py diagnostics a.cc b.h include/c.h        # multi-file in one call
./lsp-cli.py diagnostics file.cc --wait-timeout 60   # give clangd longer to parse
```

If a file is still being reparsed, the first call after idle can be slow while
clangd pages its index back in from swap; subsequent calls are fast. Never hide
with grep timed_out or you may receive false results

### 5. Output formats (apply to every command)

```sh
./lsp-cli.py --format json search "Show" > show.json   # tool result as JSON, for scripting
./lsp-cli.py --format raw  diagnostics file.cc          # full JSON-RPC response, for debugging
```

### Flag placement (important)

- Global flags go **before** the subcommand: `--format`, `--server-path`,
  `--http-url`, `--config`, `--debug`, and the hidden `--attach-timeout`
  (default 30s; raise it if the CLI times out attaching to a busy server).
- Subcommand flags go **after** the subcommand: `--wait-timeout`,
  `--build-directory`, `--kind`, `--files`, `--max-examples`, `--location-hint`.

```sh
./lsp-cli.py --format json --attach-timeout 60 search "Show" --wait-timeout 120
#            ^^^^^^^^^^^^^ global ^^^^^^^^^^^^^           ^^^^^^^^^^^^^^^^^^^^ subcommand
```

### Possible CLI locations

- Project root
- skill directory

## Why use lsp-cli.py

The clangd index resolves qualified names and overloads reliably for the active
build configuration, yielding exact definitions and call sites.