The extension needs the shoal binary
The extension holds no agent of its own. It spawns the installed engine as a child process, runs it as shoal proto, and speaks the protocol seam over stdio: engine events arrive on stdout as JSON lines, the panel’s ops go back on stdin, and startup narration comes over stderr. The tools, the approvals, the model, the session store: all of that lives in the child process.
So install Shoal first. shoal setup copies the binary into the per-user programs directory, puts it on PATH, and registers it with the operating system. Then save a default model, so the engine starts with no flags at all:
shoal setup
shoal config set model gpt-oss-20b-MXFP4.gguf
The extension does not trust PATH alone. An editor launched before shoal setup ran holds the environment it inherited for the rest of its life, so a PATH lookup would fail until the editor restarted. The installed location is known, so the extension checks it first: %LOCALAPPDATA%\Programs\Shoal\shoal.exe on Windows, ~/.local/bin/shoal elsewhere. When neither exists and PATH has nothing either, the panel names the binary it tried.
VS Code 1.85.0 or newer is required.
The extension installs from a vsix
The extension ships packaged. Install it with the editor’s own CLI, then reload the window:
code --install-extension shoal-0.21.0.vsix --force
An installed extension runs from its own copy under ~/.vscode/extensions and never reads the source folder again. Editing that folder changes nothing you can see until a new vsix is packaged and installed over the old one. install.ps1 and install.sh beside the extension source do that whole chain in one step: sync the shared client, package with vsce, install with --force. Reload the window afterwards either way.
Two settings live at machine scope
| Setting | Default | What it does |
|---|---|---|
shoal.command | shoal | Names the binary to spawn. Set it to a full path when the engine lives somewhere the lookup above will not find. |
shoal.extraArgs | [] | Extra flags appended to shoal proto, such as --model or --endpoint. With none, the engine resolves its own defaults from shoal config. |
{
"shoal.command": "D:\\tools\\shoal.exe",
"shoal.extraArgs": ["--endpoint", "http://127.0.0.1:8820", "--model", "gpt-oss-20b"]
}
Both are declared machine scope, and that is a security property rather than a preference. VS Code lets a workspace carry its own settings, which means a repository you cloned carries whatever its author wrote into .vscode/settings.json. Machine scope makes the editor ignore these two keys there. A repository cannot redirect the executable the extension spawns, and it cannot append a flag such as --auto-approve that would answer your approval prompts for you.
Shoal does not run in an untrusted workspace
The manifest declares no support for untrusted workspaces. Open a folder you have not trusted and the extension does not activate in it.
The reason is what activation does. The extension spawns the engine binary with the workspace folder as its working directory, and the agent inside executes approved tool calls in that directory. Trust is the gate in front of all of it, and the folder you just cloned is exactly the case the gate exists for. Trust the folder through the editor’s own prompt when you want Shoal working in it.