- docs
- Publish and integrate
- Publish and integrate
- Integrations
- Use OCX in an editor
Use OCX in an editor
This page shows how to give an editor the same pinned toolchain that your shell and your CI use. It covers the VS Code extension and the one query any other editor needs.
An editor does not source your shell profile, so a tool that works in your terminal can be “not found” in the editor’s run configuration. The fix is the same everywhere: give the editor the directory that OCX resolved, and never build that path by hand.
Use the VS Code extension
OCX for VS Code is the maintained route for VS Code. Get ocx-sh.ocx from the extension marketplace. It needs the ocx CLI on PATH, or ocx.path.executable set.
Open a folder that holds an ocx.toml. The extension composes the project toolchain with the CLI and injects the result into the extension host. Language servers and other extensions then find the tools your project declares. Editing ocx.toml or ocx.lock reloads the environment.
Three settings decide the rest:
| Setting | Default | Effect |
|---|---|---|
ocx.env.applyToTerminals |
false |
Puts the toolchain PATH on newly opened terminals and tasks |
ocx.groups |
[] |
Composes the named tool groups instead of only the default group |
ocx.restart.automatic |
false |
Restarts the extension host without asking when the environment changes |
The environment changes PATH, so it loads only in a trusted workspace. The extension also provides palette commands for ocx lock, ocx pull, ocx upgrade and ocx clean. Its README lists the commands, the settings and how to wire them into tasks.json.
Point any editor at the toolchain
An editor without an extension needs one directory on its PATH. Ask OCX for it:
ocx pullocx --format json shell state | jq -r .toolchain_bintoolchain_bin is the directory that holds a launcher for every tool of the project in effect. Paste it into the editor’s setting. In VS Code that is terminal.integrated.env.<platform> in .vscode/settings.json. Put the printed directory in front of the inherited PATH:
{ "terminal.integrated.env.linux": { "PATH": "/home/dev/.ocx/toolchain/active/bin:${env:PATH}" }}The directory above stands in for the value the query printed. Use terminal.integrated.env.osx or terminal.integrated.env.windows on those platforms.
Run ocx pull first. The query reports the directory even if nothing was rendered into it. A setting that points at an empty directory looks the same as a broken one. The shell state report describes the other fields, and Read OCX output from a script covers the format.
A package can also publish editor configuration of its own. The integrations field carries a vendor-keyed block such as com.microsoft.vscode, and ocx env --format json returns every block of the composition with its declaring package. A tool that wants those blocks reads the integrations array. OCX never interprets or merges the payloads, as Integrations explains.
Use OCX in a dev container
The OCX Dev Container Feature installs OCX in the image and restores the project toolchain when the container is created. It also adds the VS Code extension. Its own documentation covers the options, restricted networks and troubleshooting.