clangd-query

# clangd-query Fast C++ code intelligence CLI tool that provides instant access to semantic code navigation features through a persistent daemon architecture. `clangd-query` leverages the clangd language server to provide IDE-quality code intelligence on the command line. Perfect for exploring large C++ codebases, integrating with scripts, or building development tools. ## Features - **Fast Startup**: Daemon architecture maintains warm clangd instance - **Semantic Search**: Find symbols by name with fuzzy matching - **Source Viewing**: View complete implementations of any symbol - **Jump to Definition**: Navigate to symbol definitions - **Find References**: Locate all usages of a symbol - **Class Hierarchy**: View complete inheritance trees with base and derived classes - **Function Signatures**: Display detailed function/method signatures with documentation - **Public Interface**: Show only public API of classes for quick reference - **Smart Output**: Human and AI-agent friendly formatting ## Installation ### From npm (coming soon) ```bash npm install -g clangd-query ``` ### From source 1. Clone this repository 2. Make sure you have Node.js v18+ installed 3. Install dependencies: ```bash npm install ``` 4. Build the TypeScript code: ```bash npm run build ``` 5. Link the command globally: ```bash npm link ``` ## Prerequisites - `clangd` must be installed on your system (or you can specify a custom path) - Your C++ project must have a `compile_commands.json` file (generated by CMake with `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`) ## Usage ### Basic Commands ```bash # Search for symbols clangd-query search Scene clangd-query search "LoadResources" --limit 10 # View complete source code clangd-query view SceneManager clangd-query view "View::SetSize" # Find all references clangd-query usages Scene::StartScene clangd-query usages include/widget.h:100:8 # Show class hierarchy clangd-query hierarchy Scene clangd-query hierarchy View # Show function signatures clangd-query signature SetTitleForState clangd-query signature View::SetSize # Show public interface of a class clangd-query interface ResourceManager clangd-query interface View # Check daemon status clangd-query status # Stop the daemon clangd-query shutdown ``` ### Options - `--limit <n>` - Limit search results (default: 20) - `--timeout <seconds>` - Set request timeout (default: 30) - `--help` - Show help for command ### How It Works 1. **First Run**: Automatically starts a background daemon for your project 2. **Daemon Process**: Maintains persistent clangd instance with warm index 3. **Fast Queries**: Subsequent queries are near-instantaneous 4. **Auto-Cleanup**: Daemon shuts down after 30 minutes of inactivity ### Architecture ``` ┌─────────────┐ JSON-RPC ┌──────────────┐ │clangd-query ├──────────────────────►│clangd-daemon │ │ (client) │◄──────────────────────┤ (server) │ └─────────────┘ Unix Socket └──────┬───────┘ │ ▼ ┌──────────┐ │ clangd │ │ LSP │ └──────────┘ ``` ### Project Detection The tool automatically detects your C++ project by looking for `CMakeLists.txt` in parent directories. Run commands from anywhere within your project tree. ### Environment Variables - `CLANGD_DAEMON_TIMEOUT` - Idle timeout in seconds (default: 1800) - `CLANGD_PATH` - Path to clangd executable (defaults to system `clangd`) ## Examples ### Finding and Viewing Code ```bash # Find all scene-related classes $ clangd-query search Scene Found 12 symbols matching "Scene": - `class Scene` at clients/flare/src/base/scene.h:45:7 - `class SceneManager` at clients/flare/src/base/scenemanager.cc:18:6 - `class ModalScene` at clients/src/phoenix2/scenes/modalscene.h:12:8 ... # View the SceneManager implementation $ clangd-query view SceneManager Found class 'SceneManager' at clients/flare/src/base/scenemanager.cc:18:6 ```cpp class SceneManager { public: SceneManager() : active_scene_(nullptr) { // ... full implementation ... } // ... complete class shown ... }; ``` ### Navigating Code ```bash # Find all usages of a class $ clangd-query usages Scene Found 23 references to 'Scene': - clients/src/phoenix2/game.cpp:15:8 - clients/src/phoenix2/scenes/menuscene.cc:34:12 ... ``` ### Viewing Class Hierarchies ```bash # Show inheritance hierarchy for a class $ clangd-query hierarchy Scene Inherits from: ├── MouseInputHandling - clients/flare/include/flare/base/ui/mouse.h:37 ├── KeyboardStateDelegate - clients/flare/include/flare/base/ui/keyboard.h:209 ├── TouchInputHandling - clients/flare/include/flare/base/ui/touch.h:59 ├── ControllerInputHandling - clients/flare/include/flare/base/ui/controller.h:48 └── KeyboardInputHandling - clients/flare/include/flare/base/ui/keyboard.h:166 Scene - clients/flare/include/flare/base/scene.h:237 ├── InterfaceScene - clients/src/phoenix2/scenes/interfacescene.h:60 │ ├── MenuScene - clients/src/phoenix2/scenes/menuscene.h:180 │ ├── SettingsScene - clients/src/phoenix2/scenes/settingsscene.h:102 │ └── LoginScene - clients/src/phoenix2/scenes/loginscene.h:100 ├── GameScene - clients/src/phoenix2/scenes/gamescene.h:264 ├── AccountScene - clients/src/phoenix2/scenes/accountscene.h:109 └── RootScene - clients/src/phoenix2/scenes/rootscene.h:140 ``` ### Function Signatures with Documentation ```bash # Show all signatures for a function/method $ clangd-query signature LoadResources LoadResources - clients/flare/include/flare/base/scene.h:273:16 public: virtual void LoadResources(ResourceManager* manager) Return Type: void Parameters: - manager: ResourceManager* - The resource manager instance Description: Load all resources that this scene will use. This method is called on the resource manager's dispatch queue before the scene starts. Override this to load your scene-specific resources. Modifiers: virtual ──────────────────────────────────────────────────────────────────────────────── LoadResources - clients/src/phoenix2/scenes/gamescene.h:287:8 protected: virtual void LoadResources(ResourceManager* manager) override Return Type: void Parameters: - manager: ResourceManager* - The resource manager for loading resources Modifiers: virtual, override ``` ## Troubleshooting ### Daemon Issues If the daemon crashes or becomes unresponsive: ```bash # Check status clangd-query status # Force shutdown and restart clangd-query shutdown clangd-query search test # Will auto-restart daemon ``` ## Debugging and logging Use the --debug flag when issuing a command to get the debug output directly before the output of the command itself. Useful for quick checks on result. To view the last logs from the daemon, use the `logs` command with the optional `--limit X` parameter. ```bash clangd-query logs ``` ### First Run Slowness The first query in a project may take longer as clangd indexes your codebase. Subsequent queries will be fast. You can check indexing status with: ```bash clangd-query status ``` ### Lock Files The daemon uses lock files at `<project-root>/.clangd-query.lock`. These are automatically cleaned up but can be manually removed if needed. ### Compilation Database The tool will build a `compile_commands.json` from the `CMakeLists.txt`, which must be in the project root. This is used by clangd to index the codebase. ## Technical Details - **Compilation Database**: Cached in `.cache/clangd-query/build/compile_commands.json` - **Index Location**: `.cache/clangd-query/build/.cache/clangd/index/` - **Socket Location**: System temp directory - **Log Files**: System temp directory ## Requirements - Node.js 18 or higher - clangd 12 or higher (15+ recommended for full feature support) - CMake-based C++ project (for automatic compile_commands.json generation) ## License MIT License - see [LICENSE](LICENSE) file for details. ## Contributing Contributions are welcome! Please feel free to submit issues and pull requests. ## Acknowledgments Built on top of the excellent [clangd](https://clangd.llvm.org/) language server.