JQ Sidekick
JQ Sidekick brings the real jq command-line processor into a focused VS Code sidebar. It works with active JSON and JSONC editors, including unsaved changes.
Features
- Search and extract values with any jq filter.
- Explore the active JSON as a colorful, type-aware clickable tree with an explicit light/dark palette and insert exact or array-wildcard jq paths.
- Preview filters automatically while typing, with debouncing and cancellation of stale runs.
- Keep the sidebar compact with Explorer/Result tabs, automatic suggestion chips, and native history/action pickers.
- Preview one or many JSON results with safe syntax coloring and without converting large numbers through JavaScript.
- Open results in a new editor or export one value as JSON and multiple values as JSON Lines.
- Preview transformations before replacing the selected JSON value or entire document.
- Format, compact, and validate JSON from the sidebar or Command Palette.
- Recall the most recent successful filters for each workspace.
- Cancel long-running work; execution also has configurable time and output limits.
The extension ships jq 1.8.2 in platform-specific VSIX packages. It does not need a system jq installation.
Usage
- Open a JSON or JSONC document. Select a valid JSON value to use it as input, or leave the selection empty to use the whole document.
- Open JQ Sidekick in the Activity Bar.
- Click a node in JSON Path Explorer, or enter a filter such as
.users[] | select(.active). The result previews automatically while Live preview is enabled; choose Run or press Ctrl+Enter (Cmd+Enter on macOS) to run manually.
- Open, export, or apply the previewed result.
Choose Suggest to generate up to twenty jq filters from the active selection or document shape. Suggestions include exact deep paths such as .contributes.commands[0].title, reusable array paths such as .contributes.commands[].title, projection, filtering, sorting, unique values, grouping and counts, numeric calculations, string transformations, and nested traversal when those operations fit the data. Select a filter from VS Code's Quick Pick to run it and preview the result; it never modifies the source unless you later choose Apply.
In JSON Path Explorer, click a node to use its exact path. For nodes inside arrays, the adjacent [] button creates a reusable path across every array item. Large documents are bounded to keep the sidebar responsive. Turn off Live when you want filters to run only on demand. Use the clock button for filter history, Suggest for the full suggestion picker, and … for Format, Compact, and Validate. Manual actions open the Result tab; live previews keep your current tab selected.
Apply is available only when jq returns exactly one JSON value and the source has not changed since the filter ran. Applying to JSONC produces strict JSON and removes comments from the replaced range. Every edit uses VS Code's normal undo stack.
Development
npm install
npm run acquire-jq -- --target win32-x64
npm run build
npm test
Press F5 in VS Code to start an Extension Development Host. Use your current platform target in the acquire command.
Create an installable package with:
npm run package:vsix -- --target win32-x64
Supported targets are win32-x64, linux-x64, linux-arm64, darwin-x64, and darwin-arm64. Packages are written to .artifacts/vsix.
Publishing
Run ./publish.ps1 for an interactive single-target release, or ./publish.ps1 -All to build all five platform packages. The script validates the release, prompts for a semantic version, checksum-verifies every bundled jq binary, optionally installs the host VSIX, and can publish the exact packages with Microsoft Entra ID or VSCE_PAT authentication.
To select one package non-interactively before the confirmation prompts:
./publish.ps1 -Platform linux -Cpu arm64
Security and limitations
jq is started directly without a command shell. Input is sent over stdin, and only a minimal process environment is exposed. Browser-hosted VS Code is unsupported because the extension uses a native jq executable. Raw text output, custom jq modules, and arbitrary jq command-line arguments are not supported in this release.
License
JQ Sidekick is MIT licensed. Bundled jq is also MIT licensed; see the included THIRD_PARTY_NOTICES.md file.
