CodeQL for Zed

Write CodeQL queries in Zed.
Tree-sitter syntax support. The official CodeQL language server.

Install · Features · Configuration · Troubleshooting

Install

1. Install the CodeQL CLI 2.26.1 or newer separately, and make sure codeql version works in a terminal.
2. In Zed, open the Extension Gallery with Cmd+Shift+X on macOS or Ctrl+Shift+X on Linux and Windows. Search for CodeQL and select Install.
3. Open a .ql or .qll file to start the language server.

The extension is listed in the Zed Extension Gallery. No configuration is needed when Zed can find codeql on PATH. If it cannot, set an explicit executable path.

Features

While editing	Support
Read and navigate	Syntax highlighting, symbol outline, and Vim-mode text objects
Write queries	Bracket pairing, indentation, and completion
Inspect code	Hover information and go to definition
Catch errors	Diagnostics from the official CodeQL CLI language server
Use an existing setup	PATH discovery, custom executable paths, arguments, and environment variables

Tree-sitter handles syntax; the official CodeQL CLI language server provides semantic features. Both .ql queries and .qll libraries are recognized.

This extension focuses on editing queries. It does not bundle CodeQL, create databases, run repository scans, parse SARIF, or upload source code and results. Query execution stays in your existing CodeQL CLI workflow.

Configuration

If the CLI is installed outside Zed's PATH, set lsp.codeql.binary.path and the complete argument list in Zed settings:

{
  "lsp": {
    "codeql": {
      "binary": {
        "path": "/absolute/path/to/CodeQL CLI/codeql",
        "arguments": [
          "execute",
          "language-server",
          "--check-errors",
          "ON_CHANGE"
        ]
      }
    }
  }
}

When overriding the binary path, include arguments explicitly. A path-only override can start the CLI without its language-server subcommand, causing it to print help and exit with a connection-reset error.

With automatic PATH discovery, the extension supplies this command by default:

codeql execute language-server --check-errors ON_CHANGE

Custom arguments and environment variables

binary.arguments replaces the entire default argument list. It must start with execute, language-server; include any flags after those two arguments.

This Windows example selects a CLI, adds a query-pack search path, and overrides an environment variable:

{
  "lsp": {
    "codeql": {
      "binary": {
        "path": "C:/Tools/CodeQL CLI/codeql.exe",
        "arguments": [
          "execute",
          "language-server",
          "--check-errors",
          "ON_CHANGE",
          "--search-path=C:/CodeQL Packs"
        ],
        "env": {
          "CODEQL_HOME": "C:/Tools/CodeQL CLI"
        }
      }
    }
  }
}

Commands use an argument array rather than a shell string, so paths containing spaces remain a single argument. Values in binary.env override matching shell environment variables.

The extension also forwards lsp.codeql.initialization_options and lsp.codeql.settings to the language server.

Troubleshooting

Symptom	What to check
codeql not found	Run codeql version. If it works only in a terminal, configure an absolute binary path and the full arguments shown above, then restart the language server.
Server reset the connection with CLI usage text	Check that binary.arguments includes execute, language-server, --check-errors, ON_CHANGE. A path-only override can launch plain codeql instead of the language server.
CLI does not start	Check executable permissions, Zed's PATH, and the Zed log. Use CodeQL CLI 2.26.1 or newer.
Custom arguments fail	Supply the full argument list, starting with execute, language-server, not just flags.
Query or import errors	From the query-pack root, run codeql pack install, then codeql query compile path/to/query.ql. Check the pack dependencies and search path.

For a reproducible extension issue, open a bug report with the Zed version, CodeQL CLI version, operating system, and relevant logs.

Development

Clone this repository, then run zed: install dev extension in Zed and select the repository directory. After changing Rust code, the manifest, or language queries, run zed: rebuild dev extension.

See CONTRIBUTING.md for the full workflow and CHANGELOG.md for version history.

Local checks and compatibility

The validation scripts require Python 3.11 or newer. Install the fixture pack dependencies before running the CodeQL smoke checks:

cargo fmt --check
cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release --target wasm32-wasip2
python3 scripts/validate_extension.py
codeql pack install fixtures/qlpack
python3 scripts/codeql_smoke.py --codeql /path/to/codeql --fixtures fixtures/qlpack

If query packs are in a non-standard location, pass --search-path /path/to/packs to the smoke script.

Component	Verification baseline
Zed	macOS Zed 1.16.1; documented baseline 1.16 or newer
Linux x64	Ubuntu 22.04 CI runner
Windows x64	Windows Server 2022 CI runner; real-device regression pending
CodeQL CLI	CI matrix: 2.26.1 and 2.26.3
Paths	Spaces in executable paths; Windows drive-path configuration

CI checks formatting, Rust tests, Clippy, the WASM build, extension resources, query compilation, and native LSP diagnostics on Linux and Windows.

License

MIT. Tree-sitter query files are adapted from the MIT-licensed tree-sitter-ql project by Sam Lanning and contributors, pinned to commit 5b8ee9adaa1f2a1ea958064b61f8feb0a5a886c0. See THIRD_PARTY_NOTICES.md.

The CodeQL CLI is distributed separately by GitHub and remains subject to its own license and terms.