cursorless-dev · AndreasArvidsson · Jul 12, 2025 · Jun 27, 2025 · Jun 29, 2025 · Jun 29, 2025
diff --git a/.gitignore b/.gitignore
@@ -54,3 +54,7 @@ cursorless.nvim/node/test-harness
 
 # nix
 .direnv/
+
+# unignore .vsix files in data/vsix 
+# required for vscodium dev env setup until https://github.com/jrieken/vscode-tree-sitter-query/issues/28 is closed
+!data/vsix/*.vsix
@@ -1,7 +1,9 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Contributing
 
-Welcome! So glad you've decided to help make Cursorless better. You'll want to start by getting [set up](#initial-setup) and learning how to [run / test a local copy of the
-extension](#running--testing-extension-locally). You may also find the [VSCode API docs](https://code.visualstudio.com/api) helpful to learn about VSCode extension development.
+Welcome! So glad you've decided to help make Cursorless better. You'll want to start by getting [set up](#initial-setup) and learning how to [run / test a local copy of the extension](#running--testing-extension-locally). You may also find the [VSCode API docs](https://code.visualstudio.com/api) helpful to learn about VSCode extension development.
 
 ## Initial setup
 
@@ -10,7 +12,8 @@ extension](#running--testing-extension-locally). You may also find the [VSCode A
 - [Git](https://git-scm.com/)
 - [Node.js](https://nodejs.org/en/)
 - [Corepack](https://nodejs.org/api/corepack.html) or [pnpm](https://pnpm.io/installation)
-- [VSCode](https://code.visualstudio.com/); minimum version for local development is 1.72.0 in order to support settings profiles for sandboxed development. Please file an issue if that is a problem.
+- [VSCode](https://code.visualstudio.com/) or [VSCodium](https://vscodium.com/); Please file an issue if you are unable to use [settings profiles](https://code.visualstudio.com/updates/v1_72#_settings-profiles), as they are required for the development environment.
+Both VSCode and VSCodium will be referred to as VSCode except when instructions differ between the editors.
 
 ### Steps
 
@@ -22,32 +25,62 @@ extension](#running--testing-extension-locally). You may also find the [VSCode A
    pnpm install
    pnpm compile
    ```
+Don't fret if `pnpm compile` fails! While required for running tests locally on your machine, you will still be able to run tests through GitHub Actions, and it will not prevent you from contributing otherwise. 
 
-4. Run
+4. Run the following in the terminal:
 
-   ```bash
-   code --profile=cursorlessDevelopment
-   ```
+   <Tabs groupId="vsx">
+      <TabItem value="vscode" label="VSCode" default>
+      ```bash
+      code --profile=cursorlessDevelopment
+      ```
+      </TabItem>
+      <TabItem value="vscodium" label="VSCodium">
+      ```bash
+      codium --profile=cursorlessDevelopment
+      ```
+      </TabItem>
+   </Tabs>
 
-   and then close the window that opens (eg say `"window close"`). This step is necessary to create the [VSCode settings profile](https://code.visualstudio.com/updates/v1_72#_settings-profiles) that acts as a sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. Once https://github.com/microsoft/vscode/issues/172046 is resolved, we will be able to remove this step, as the profile can then automatically be created.
+   and then close the window that opens (eg say `"window close"`). This step is necessary to create the [settings profile](https://code.visualstudio.com/updates/v1_72#_settings-profiles) that acts as a sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. Once https://github.com/microsoft/vscode/issues/172046 is resolved, we will be able to remove this step, as the profile can then automatically be created.
 
 5. Run the following in the terminal:
 
-   ```bash
-   pnpm init-vscode-sandbox
-   ```
-
-   The `pnpm init-vscode-sandbox` command creates a local [VSCode settings profile](https://code.visualstudio.com/updates/v1_72#_settings-profiles) that acts as a sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. This approach is [suggested](https://code.visualstudio.com/updates/v1_72#_extension-debugging-in-a-clean-environment) by the VSCode documentation. If you need to update any of the extension dependencies in the sandbox, you can add `--force` to the command. If you'd like to use additional extensions when debugging locally, you can use the following command:
-
-   ```bash
-   code --profile=cursorlessDevelopment --install-extension some.extension
-   ```
+   <Tabs groupId="vsx">
+      <TabItem value="vscode" label="VSCode">
+      ```bash
+      pnpm init-vscode-sandbox
+      ```
+      </TabItem>
+      <TabItem value="vscodium" label="VSCodium">
+      ```bash
+      pnpm init-vscode-sandbox
+      ```
+      VSCodium users will also need to manually download and install the `jrieken:vscode-tree-sitter-query` extension, as it is [currently not avalible](https://github.com/jrieken/vscode-tree-sitter-query/issues/28) on the OpenVSX Marketplace.
+      Instructions on how to manually download the extension can be found [in this Stack Overflow post](https://stackoverflow.com/a/79565372) ([archived](https://web.archive.org/web/20250421130639/https://stackoverflow.com/questions/79359919/how-can-i-manually-download-vsix-files-now-that-the-vs-code-marketplace-no-long/79565372#79565372)), while manual installation instructions can be found directly below—replace `some.extension` with the acquired `.vsix` file's path instead of an extension id.
+      </TabItem>
+   </Tabs>
+
+   Said command adds extensions to the aforementioned settings profile that acts as a sandbox containing a specific set of VSCode extensions that will be run alongside Cursorless when you launch Cursorless in debug or test mode. This approach is [suggested](https://code.visualstudio.com/updates/v1_72#_extension-debugging-in-a-clean-environment) by the VSCode documentation. If you need to update any of the extension dependencies in the sandbox, you can add `--force` to the command. If you'd like to use additional extensions when debugging locally, you can use the following command:
+
+   <Tabs groupId="vsx">
+      <TabItem value="vscode" label="VSCode">
+      ```bash
+      code --profile=cursorlessDevelopment --install-extension some.extension
+      ```
+      </TabItem>
+      <TabItem value="vscodium" label="VSCodium">
+      ```bash
+      codium --profile=cursorlessDevelopment --install-extension some.extension
+      ```
+      </TabItem>
+   </Tabs>
 
    where `some.extension` is the id of the extension you'd like to install into the sandbox.
 
    Note that you do not need to install the Cursorless extension into the `cursorlessDevelopment` profile. A local development version of Cursorless will be automatically installed there every time you debug the extension, as described below.
 
-   Also note that if you are adding support for a new language that isn't in the default list of [language identifiers](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) supported by VSCode, you may need to add an extension dependency. See [Adding a new language](./adding-a-new-language.md#2-ensure-file-type-is-supported-by-vscode) for more details.
+   Also note that if you are adding support for a new language that isn't in the default list of [language identifiers](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) supported by VSCode/VSCodium, you may need to add an extension dependency. See [Adding a new language](./adding-a-new-language.md#2-ensure-file-type-is-supported-by-vscode) for more details.
 
 6. Copy / symlink [`cursorless-talon-dev`](../../cursorless-talon-dev) into your Talon user directory for some useful voice commands for developing Cursorless.
 
@@ -106,9 +139,18 @@ vsce package -o bundle.vsix
 
 Once you have your package then you can install it into the sandbox using the following command:
 
-```
-code --profile=cursorlessDevelopment --install-extension bundle.vsix
-```
+   <Tabs groupId="vsx">
+      <TabItem value="vscode" label="VSCode">
+      ```bash
+      code --profile=cursorlessDevelopment --install-extension bundle.vsix
+      ```
+      </TabItem>
+      <TabItem value="vscodium" label="VSCodium">
+      ```bash
+      codium --profile=cursorlessDevelopment --install-extension bundle.vsix
+      ```
+      </TabItem>
+   </Tabs>
 
 ## Installing a local build of the Cursorless extension
 

@@ -8,7 +8,7 @@ The implementation of the local version of the cheatsheet is split between the T
 
 When you add a new scope type, action, modifier, etc, you'll need to ensure that it shows up both locally and on the website. It will usually automatically show up in the local cheatsheet. You can verify this by saying `"cursorless cheatsheet"` with your development version of `cursorless-talon` active in your Talon user directory, and inspecting the cheatsheet that appears. If it does not, you'll need to make fixes to [the Talon side of the cheatsheet](../../../../../cursorless-talon/src/cheatsheet).
 
-In either case, to get your changes to appear on the website, you need to update the defaults in [`defaults.json`](../../../../../packages/cheatsheet/src/lib/sampleSpokenFormInfos/defaults.json). First make sure you have the `cursorless-talon-dev` user file set in your Talon home directory, as indicated in the [initial contributor setup instructions](CONTRIBUTING.md#initial-setup). Then you can say `"cursorless update cheatsheet"` to update the default spoken forms. Note that this will use your custom spoken forms, so you may need to do some manual cleanup.
+In either case, to get your changes to appear on the website, you need to update the defaults in [`defaults.json`](../../../../../packages/cheatsheet/src/lib/sampleSpokenFormInfos/defaults.json). First make sure you have the `cursorless-talon-dev` user file set in your Talon home directory, as indicated in the [initial contributor setup instructions](CONTRIBUTING.mdx#initial-setup). Then you can say `"cursorless update cheatsheet"` to update the default spoken forms. Note that this will use your custom spoken forms, so you may need to do some manual cleanup.
 
 ## Running the cheatsheet in development mode
 

@@ -8,7 +8,7 @@ Note that Cursorless is maintained as a monorepo, hosted at [`cursorless`](https
 
 ### 1. Follow the initial contributor setup guide
 
-Follow the steps in [CONTRIBUTING.md](./CONTRIBUTING.md#initial-setup).
+Follow the steps in [CONTRIBUTING.mdx](./CONTRIBUTING.mdx#initial-setup).
 
 ### 2. Get production Cursorless neovim working
 
@@ -45,7 +45,7 @@ In order to test out your local version of the extension or to run unit tests lo
 
 NOTE: This will spawn a standalone nvim instance that is independent of VSCode. Consequently after you're done debugging, you need to close nvim.
 
-If you don't have the `cursorless-talon-dev` files in your Talon user directory as described in step 6 of [CONTRIBUTING.md](./CONTRIBUTING.md#initial-setup), then you instead need to run the `workbench.action.debug.selectandstart` command in VSCode and then select either "Neovim: Run" or "Neovim: Test".
+If you don't have the `cursorless-talon-dev` files in your Talon user directory as described in step 6 of [CONTRIBUTING.mdx](./CONTRIBUTING.mdx#initial-setup), then you instead need to run the `workbench.action.debug.selectandstart` command in VSCode and then select either "Neovim: Run" or "Neovim: Test".
 
 ### Running lua tests
 

@@ -7,8 +7,47 @@ import { extensionDependencies } from "@cursorless/common";
 import * as cp from "child_process";
 
 const extraExtensions = ["pokey.command-server"];
+const vsCodeToolName = "code";
+const vsCodiumToolName = "codium";
 
 async function main() {
+
+  // CLI tool name check
+
+  var cliToolName: string = vsCodeToolName;
+  var foundTool: boolean = false;
+
+  console.log("Checking avalible VSC cli tool...");
+
+  while (!foundTool) {
+    try {
+      const checkToolSubprocess = cp.spawn(cliToolName, ["-v"], {
+      stdio: "inherit",
+      shell: true,
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      checkToolSubprocess.on("error", reject);
+      checkToolSubprocess.on("exit", (code) => {
+        if (code === 0) {
+          foundTool = true;
+          resolve();
+        } else {
+          reject(new Error(`Process returned code ${code}`));
+        }
+      });
+    });
+
+    } catch(error) {
+      if (cliToolName === vsCodeToolName) {
+        cliToolName = vsCodiumToolName;
+      } else if (cliToolName === vsCodiumToolName) {
+        console.error("No VSC command line interface found!");
+        process.exit(2);
+      }
+    }
+  }
+  console.log("Found '%s' cli tool!", vsCodeToolName)
   try {
     const args = [
       "--profile=cursorlessDevelopment",
@@ -21,8 +60,16 @@ async function main() {
       args.push("--force");
     }
 
+    // Do not attempt to install jrieken:vscode-tree-sitter-query if editor is VSCodium
+    if (cliToolName === vsCodiumToolName) {
+      const index: number = args.findIndex((value) => value.includes("vscode-tree-sitter-query"))
+      args.splice(index, 1)
+      console.log("Not installing jrieken:vscode-tree-sitter-query as it is not on the OpenVSX Marketplace.")
+      console.log("You should install this extension manually. Check the Cursorless contributor documentation for more info.")
+    }
+
     // Install extension dependencies
-    const subprocess = cp.spawn("code", args, {
+    const subprocess = cp.spawn(cliToolName, args, {
       stdio: "inherit",
       shell: true,
     });