chromium-ai-assisted/skills/lsp-cli/SKILL.md

name, description

name	description
lsp-cli	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:

./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

./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

./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:

./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.

./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:

./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)

./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.

./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.