# vscode-codeql-starter: a workspace for writing your own CodeQL queries > The vscode-codeql-starter repository is a starter workspace for the CodeQL extension for Visual Studio Code, preloaded with the open-source CodeQL standard libraries and one ready-made folder of example custom queries for each of seven languages. It suits a security engineer who wants to write and run their own CodeQL queries locally, and the trade is that it is a template rather than a tool, with the actual work happening in the extension and in the CodeQL CLI that the standard libraries are tracked against. **github/vscode-codeql-starter** — Starter workspace to use with the CodeQL extension for Visual Studio Code. - Repository: https://github.com/github/vscode-codeql-starter - Stars: 597 · Forks: 272 - Language: CodeQL - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/github-vscode-codeql-starter ## A template workspace, not a scanner The vscode-codeql-starter repository is a starter workspace to use with the CodeQL extension for Visual Studio Code, and the README is explicit that it is a starting point rather than a product. For more information it points at the `vscode-codeql` repository, which is where the extension itself lives. The distinction matters for what you should expect to find. There is no analysis engine here, no configuration to point at your own source, and no dashboard. What there is, in the top level listing, is a `vscode-codeql-starter.code-workspace` file, a `codeql-workspace.yml`, a `ql` directory, and seven directories named `codeql-custom-queries-cpp`, `codeql-custom-queries-csharp`, `codeql-custom-queries-go`, `codeql-custom-queries-java`, `codeql-custom-queries-javascript`, `codeql-custom-queries-python` and `codeql-custom-queries-ruby`. There are also `.devcontainer/`, `.github/`, `CODEOWNERS`, a code of conduct and a contributing guide. So the shape is a ready-made VS Code workspace in which the CodeQL extension is expected to be installed, with a place to put your own queries for each supported language and the standard libraries already fetched. The project is MIT licensed, the primary language is recorded as CodeQL, and the topic tags are codeql, vscode, vscode-extension and works-with-codespaces, that last one explaining the presence of the `.devcontainer/` directory for running the workspace inside a GitHub Codespace. The repository is not archived and the last push was on 2026-10-20. There are no GitHub releases, which is what you would expect from something whose entire purpose is to be cloned as a starting point. ## The standard libraries arrive as a submodule The one piece of setup that is easy to get wrong is the submodules, and the README is explicit about it. You clone the repository to your computer, and you make sure to include the submodules, either by `git clone --recursive` or by `git submodule update --init --remote` after clone. It also tells you to use `git submodule update --remote` regularly to keep the submodules up to date. That second instruction is the one worth pausing on, because it says the submodule content moves. The `ql` folder contains the open-source CodeQL standard libraries for C/C++, C#, Go, Java, JavaScript/TypeScript, Python and Ruby, and it tracks the branch tagged `codeql-cli/latest` in the main CodeQL repository. So the libraries are a moving target that you refresh, not a pinned snapshot you install once, and the update command is the same one you would use to pull a normal dependency. Why this matters operationally is that a query you write against the standard libraries is written against a version of them, and the version moves. The `codeql-cli/latest` tag is a moving branch rather than a fixed release, so a library change can alter what your query sees without any change on your side. The repository's own guidance to update regularly is at least a way to notice that happening deliberately rather than discovering it when a query starts returning nothing. The submodule approach also explains the design decision to distribute the libraries this way. The standard libraries are the shared data model that CodeQL queries are written against, and they are large. Fetching them as a submodule rather than copying them into the repository keeps the clone small and makes the update a single git operation, at the cost of a clone step that is easy to forget. ## Seven language folders, each with example queries to edit The part of the workspace you actually work in is the set of custom query folders, and the README describes what you get in them. The folders named `codeql-custom-queries-` are ready for you to start developing your own custom queries for each language, while using the standard libraries. And there are some example queries to get you started. So there are seven of them, one per language the standard libraries cover: C++, C#, Go, Java, JavaScript, Python and Ruby. Each is a scaffold with working examples in it, which is the difference between a template and an empty directory. A query author who has never written a CodeQL query gets a directory with a compilable example and the standard libraries beside it, and the fastest way to learn the language is to edit one that already runs. The custom queries use the standard libraries rather than replacing them, which is the point of having both in the workspace. You are not restricted to what the published query packs detect, and you are not restricted to working from scratch either. The libraries are shared, so a custom query for, say, a C++ framework that your organisation uses is written in the same terms as every other query against that language. The README then points you at the extension documentation for the remaining work: to set up the extension, add a database and run queries against it. That is the part this repository does not do for you, because adding a database means pointing CodeQL at a checkout of a target project, which is a decision about what you are analysing rather than a decision about how you write queries. ## Sharing the queries with your team through a private repository The README has a section on using the starter in a private repository, and it exists for a specific reason that is stated plainly. If you want to privately share your CodeQL queries with your teammates using this project as a template, you create an empty, private project in the organization you want. You clone this project locally, add a remote to the local copy with `git remote add my-org git@github.com:/vscode-codeql-starter.git`, and push the code to the new remote with `git push my-org main`. The reason for the awkwardness is stated in one line: GitHub does not allow private forks of public repositories. So the standard workflow of forking does not work, and you have to push a copy into a fresh empty private project instead. That is why the steps begin with creating an empty project rather than clicking Fork, and it is a small detail that will otherwise waste an afternoon for anyone assuming the usual fork button works. The result is that a team ends up with a private repository whose structure mirrors the public template, containing the team's own custom queries, and each member clones that with submodules rather than the public one. The standard libraries still come from the same upstream submodule, so the sharing is of queries and not of the libraries. Two other administrative details are in the repository root. There is a `CODEOWNERS` file, which is how a team assigns review responsibility for the query files, and a `.github/` directory for the workflows. Issues and suggestions for the project itself are not reported here but in the `vscode-codeql` repository, since this is a template and the extension is the thing that has bugs. ## What lives in the licence and who maintains what The licence section is worth reading carefully, because it splits into three different terms and the middle one is not MIT. This project is licensed under the MIT License, and the CodeQL extension for Visual Studio Code is licensed under the MIT License as well. But the version of CodeQL used by the CodeQL extension is subject to the GitHub CodeQL Terms and Conditions, which are a separate set of terms from the MIT licence that the code is under. So the arrangement is: the workspace template is MIT, the extension is MIT, and the CodeQL binary itself, which the extension downloads and runs, is governed by the GitHub CodeQL terms. That distinction is easy to miss because everything is packaged as one workflow, and it is the sort of thing that matters if you are building a process around CodeQL in a company with an open source review. The repository is maintained by GitHub, and the community routes are split the same way. Contributions to the starter are welcome with details in CONTRIBUTING.md, and there is a code of conduct. But issues and suggestions about the project should be reported in the `vscode-codeql` repository, which is the extension's own tracker. For a template, that split is right. The extension is where the behaviour and the bugs live, and the template is just the arrangement of files that makes the extension pleasant to use. Anyone filing a bug about the starter will be redirected, which tells you what kind of repository this is. The final piece is the Dev Container. The `.devcontainer/` directory at the root is what makes the works-with-codespaces tag meaningful, and it means the workspace can be opened in a hosted dev environment with the toolchain already present, which is a reasonable convenience when the extension, the CodeQL CLI and the standard libraries all have to line up before a query will run. ## Conclusion Adopt vscode-codeql-starter if you want to write custom CodeQL queries locally in an editor rather than only running the published query packs in CI, since it arrives with the standard libraries and example queries already wired up. Do not adopt it expecting a scanning product, because this repository contains no analysis of its own, and check first that you clone it with submodules, since the standard libraries are a submodule and the workspace will not be usable without them. ## FAQ ### What is the vscode-codeql-starter repository? It is a starter workspace to use with the CodeQL extension for Visual Studio Code, containing a .code-workspace file, the standard libraries in the ql folder and one codeql-custom-queries directory per language. It is a template rather than a scanning product, and the actual analysis work is done by the extension. ### How do I set up the vscode-codeql-starter? Install Visual Studio Code, install the CodeQL extension for Visual Studio Code, clone the repository making sure to include the submodules, then open the vscode-codeql-starter.code-workspace file through File and Open Workspace. After that you follow the extension documentation to set up the extension, add a database and run queries. ### Why do I need to clone with submodules? The ql folder contains the open-source CodeQL standard libraries, and it is a submodule tracking the branch tagged codeql-cli/latest in the main CodeQL repository. Without the submodule the workspace has no standard libraries to query against, and the README tells you to run git submodule update --remote regularly to keep them current. ### Which languages can I write custom queries for? The workspace has a custom queries folder for each of C++, C#, Go, Java, JavaScript, Python and Ruby, and each folder is ready to use with the standard libraries and contains example queries to start from. ### How do I share my custom queries with my team privately? GitHub does not allow private forks of public repositories, so you create an empty private project in your organisation, clone the starter locally, add a remote pointing at the new project with git remote add, and push the code to it with git push. ### Is vscode-codeql-starter still being maintained? The repository is not archived and the last push was on 2026-10-20, with no GitHub releases. The template and the extension are MIT licensed, while the version of CodeQL used by the extension is subject to the GitHub CodeQL Terms and Conditions. ## Sources - [github/vscode-codeql-starter on GitHub](https://github.com/github/vscode-codeql-starter) - [Issues](https://github.com/github/vscode-codeql-starter/issues) - [License: MIT](https://github.com/github/vscode-codeql-starter/blob/main/LICENSE) - [README](https://github.com/github/vscode-codeql-starter/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/github-vscode-codeql-starter