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 source

1. Clone this repository
2. Make sure you have Go 1.21+ installed
3. Build the binary:

   ./build.sh

4. The binary will be available at bin/clangd-query

Prerequisites

• clangd must be installed on your system (or you can specify a custom path)
• Your C++ project must have CMakeLists.txt at the root. The tool automatically detects your C++ project by looking for CMakeLists.txt in parent directories. Run commands from anywhere within your project tree.

Usage

Basic Commands

# 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    │
                                       └──────────┘

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

# 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

# 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

# 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

# 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:

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

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:

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: .cache/clangd-query/daemon.log

Requirements

• Go 1.21 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 file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Acknowledgments

Built on top of the excellent clangd language server.