CodeQuery: one index for cscope and ctags queries with a GUI

Two symbol databases with complementary blind spots

CodeQuery indexes C, C++, Java, Python, Ruby, Go and JavaScript source code, and then lets you query or search it. The design starts with a claim that cscope and ctags are good at different things.

The README lays out the difference. Both tools can do symbol lookup and identify functions, macros, classes and structs. cscope is very C-centric and only fuzzy enough to cover C++ and Java, and the README points out that it does not understand destructors or class member instantiations, and it cannot provide relationships of class inheritance and membership. What cscope can do is functions that call this function and functions called by this function, and the README calls that a very powerful feature that makes cscope stand out among comparable tools.

ctags goes the other way. It does many languages well, understands destructors, member instantiations, and the relationships of class membership and inheritance, so from it you can find the members and methods of a class, the class that owns a member, the parent of a class or its children. What ctags does not do is the call relationships.

Since the two complement each other, CodeQuery is an attempt to combine the features of both. That framing is the honest description of the project, and it is also the reason the tool exists rather than being a from-scratch indexer.

cqmakedb turns symbol databases into one SQLite file

The data flow has two steps, and the second one is what makes the tool different from running cscope directly.

The databases of cscope and ctags are processed by the cqmakedb tool, which generates the CodeQuery database file. That file is then viewed and queried with the codequery GUI tool.

The database is SQLite, and the README is explicit that this is the reason for the speed. Because it uses sqlite, CodeQuery provides faster database access compared to cscope, and the README says this faster access is what makes fast auto-completion of search terms and multiple complex queries for visualisation possible.

This is a sensible architecture. cscope's own database is its weak point for interactive use, and a query tool that has to re-scan the tree on every question is not much better than grep. A single relational file that can be joined against is a better base for the kind of question a GUI asks, such as a symbol that also has callers and an owner class.

The repository layout follows the pipeline. The makedb directory holds the database builder, the gui directory the desktop front end, querylib the library used to query the database files, cli for command line access, showgraph for the visualisation, and doc for the documentation, alongside the vendored scintilla and lexilla editor components and the cmakefind helper.

The query types, from symbol lookup to call graph

The list of supported queries is the clearest statement of what the tool can do, and it is worth reading as a whole rather than as a menu.

There are the obvious ones: symbol, function or macro definition, class or struct, full path for a file, and functions and macros inside a file. Then the call relationship queries, functions calling this function, functions called by this function, and calls of this function or macro. Then the class relationship queries: class which owns this member or method, members and methods of this class, parent of this class by inheritance, and children of this class by inheritance. Then the file level queries, files including this file, and finally grep.

Notice that grep is in the list. That is an admission that the tool is not replacing grep, it is a different way of navigating the same tree with structure attached.

The visualisation is the part that has no equivalent in the two underlying tools. CodeQuery can visualise the function call graph and class inheritance based on a search term, and the README shows a call graph in which A to B means A calls B. Those graphs can be saved to PNG or to Graphviz DOT files, which means the output is not trapped in the GUI. The DOT export in particular is the useful one, because it lets you diff a call graph between two revisions of a codebase.

Python, Ruby, Go and JavaScript need extra tools

The language coverage of the underlying tools does not match the language coverage of the final product, and the README is explicit about the gap and the fix.

For Python, pycscope is used to add support, in place of cscope. For Ruby, Go and JavaScript, starscope is used instead, again in place of cscope. In other words, the call-graph side of the analysis for those four languages comes from forks or alternatives rather than from stock cscope.

The installation section adds a practical note: pycscope and starscope are optional, and only needed for the languages they cover.

This has a real consequence for anyone planning a deployment. The tool is not self-contained for every language it advertises. If your tree is Go and Ruby only, you need starscope, and if you want the same UI you need a GUI front end for it, and the README points to a Visual Studio Code extension, codequery4vscode, and a vim plugin, vim-codequery by devjoe, both of which are separate projects.

It also means the analysis quality for those languages depends on a third party. The README does not discuss how the starscope output compares to stock cscope output, so anyone relying on the call graphs for a non-C language should spot-check the results against the source.

Search behaviour in the GUI: completion, wildcards and filters

The GUI feature list is where the difference from the command line shows up in daily use.

Search terms auto-complete quickly, which is the payoff from the SQLite backend. Matching is case-insensitive and partial, and wildcard search is supported with the asterisk and question mark characters, alongside exact match search. Results can be filtered by file path, which is how you narrow a cross-project answer down to one directory.

Reading the result is also handled. There is a file viewer with syntax highlighting for UTF-8 encoded source files, and the viewed file can be opened in an external editor or IDE rather than being read in a pane you cannot edit in.

The application is written in C++ and the project is MPL-2.0 licensed, with the GUI translatable: the README states that the software is available in other languages and that this applies only to the GUI tool, and contributions to update or provide new translations are welcomed.

Platform support is listed as Windows 10 64-bit, Mac OS X, Ubuntu and Arch Linux 64-bit, with contributions to attempt ports to other operating systems welcome. The cross-platform GUI is the part that is genuinely new, since the two tools it wraps are both command line programs with their own curses interfaces.

Installing on Linux, macOS and Windows

There is a package for each of the three major platforms, and the Windows path is a single installer that bundles the dependencies.

On Debian and Ubuntu the install is a single command:

apt-get install codequery

On macOS it goes through Homebrew:

brew install codequery

For Windows, EXE setup packages are published on the SourceForge downloads page, and the README notes that the package also contains cscope.exe, ctags.exe and the required DLLs, so everything needed is in one package. That is the difference between the Windows installation and the Linux one: on Linux you are installing only the tool, and the cscope and ctags databases still have to be produced for your tree.

To build from source on Linux, the README points to a separate file, doc/INSTALL-LINUX.md. The project uses CMake, with a CMakeLists.txt at the root and a cmakefind directory, and the repository carries continuous integration configuration under .github.

The Windows tree also carries its own licence copy at windows-install/wincommon/LICENSE.txt, alongside the top level LICENSE.md, and the top level includes a release.json and NEWS.md, which the README tells you to read for more information. The current version is 1.1.0.

The querylib library and the editor plugin path

The most interesting licensing detail in the project sits in the querylib directory, and it is the reason an editor integration is realistic.

Files under querylib are licensed under the MIT licence, separate from the MPL-2.0 that covers the rest of the project. The README describes querylib as a library to query CodeQuery database files, and explains the reason for the split: because this library is MIT-licensed, it may be used to create plugins for editors, IDEs and other software without restrictions. Its only dependency is on sqlite3.

That is a deliberate architectural decision, and a sensible one. The heavy part of CodeQuery is the desktop GUI, which is nice to have but is not what an editor plugin needs. What an editor plugin needs is exactly the read side of the database, and MIT licensing means a plugin author is not forced to adopt MPL-2.0 for their editor integration.

Two integrations exist today: the vim plugin vim-codequery by devjoe, and the Visual Studio Code extension codequery4vscode by the project author, published on the Marketplace as ruben2020.codequery4vscode. The README welcomes contributors to develop plugins for other editors.

The rest of the project is licensed under the Mozilla Public License version 2.0, and the README notes that this applies to both the distributed Source Code Form and the distributed Executable Form, so the obligations travel with the binaries as well as the source. Third party attribution is collected in THIRDPARTY.md.

Editorial conclusion

Use CodeQuery when you need to answer questions about a large mixed-language codebase that cscope and ctags cannot answer individually, particularly callers and callees plus class membership, and you want the results in a window with syntax highlighting and exportable graphs. Do not adopt it for a small project, since the index and the GUI cost more than they save, and remember it is an indexer over other tools, so cscope or ctags still has to be present for the languages you scan. Before your first run, install the cscope and ctags databases for your tree, check whether you need pycscope or starscope for Python, Ruby, Go or JavaScript, and pin to version 1.1.0 since the repository publishes no GitHub releases and the last push was on 2026-07-12.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. Project website
4. README
5. ruben2020/codequery on GitHub