Sanary Build Interface
Sanary Build Interface (SBI) runs Claude Code or Codex against your current VS Code workspace and shows you the result. It also lets Sanary's monitoring apps see which of your workspaces is active. SBI is free, needs no account, and has no telemetry.
Requires macOS 13 or later on Apple Silicon (arm64) and VS Code 1.100 or later. It does not run on Intel Macs, Windows, or Linux.
Unofficial. Claude and Claude Code are products of Anthropic; Codex and OpenAI are products of OpenAI. Sanary Build Interface is an independent Sanary product and is not affiliated with, endorsed by, or sponsored by Anthropic or OpenAI. It works with the Claude Code and Codex command-line tools that you install yourself.
日本語： Sanary Build Interface（SBI）は、VS Code のワークスペースで Claude Code / Codex を実行し、結果を表示します。無料・アカウント不要・テレメトリなし。macOS 13 以降（Apple Silicon 専用）。Anthropic / OpenAI とは無関係の非公式製品です。サポート・プライバシー・規約は、下の「Support, privacy and terms」のリンクをご覧ください。
Supported Coding Agents
Requirements
- macOS 13 or later on Apple Silicon (arm64). See Supported platform.
- The Claude Code CLI and/or the Codex CLI installed on your machine
(whichever Agent(s) you intend to use — see Agent executable
discovery below).
- VS Code 1.100 or later.
macOS (Apple Silicon / arm64) only, this version. The extension
bundles native binaries built for darwin-arm64; it does not run on Intel
Macs, Windows, or Linux, and is packaged so that VS Code only offers it on
darwin-arm64.
Installation
Install the .vsix like any other VS Code extension (Extensions: Install
from VSIX…, or code --install-extension <file>.vsix).
The extension activates once VS Code has finished starting; it does not
run in an untrusted workspace or a virtual (remote-file-system) workspace.
Quick Start
- Install the extension.
- Open a workspace folder.
- Open the Command Palette.
- Run SBI: Run Agent (or use
@sbi /claude … / @sbi /codex … in Chat).
- Choose an Agent (Claude Code or Codex).
- Enter an instruction.
The result appears in the SBI Output Channel and as a notification.
On first activation, the extension checks whether a compatible SBI
Runtime is already listening on 127.0.0.1:8788. If one is found, it is
reused as-is; otherwise the extension starts its own bundled Runtime. An
existing, unrelated (or incompatible) service already using that port is
never killed, overridden, or otherwise touched.
Several VS Code windows
All windows share the one Runtime on :8788. The window that started it stops
it when that window closes; every other window notices within about twenty
seconds and starts a new one, so the Runtime stays available until the last
window is closed. An Agent execution that was running through the closed
window's Runtime is interrupted when that happens.
Agent executable discovery
The extension needs to know where the Claude Code / Codex CLI
executables are installed, checked in this order:
- The
sbi.claudeCodeExecutablePath / sbi.codexExecutablePath VS Code settings.
- The
CLAUDE_CODE_EXECUTABLE_PATH / CODEX_EXECUTABLE_PATH environment variables, if already set in the environment VS Code itself was launched from.
PATH (plus a couple of well-known install locations not always on PATH).
If an Agent's executable can't be found this way, running that Agent
fails with a message naming which one is missing. Nothing is installed
automatically.
What SBI changes on your machine
Everything below stays on your Mac. SBI sends nothing to Sanary or to any
other remote server.
- A local Runtime (
sbi-server, bundled) listening on 127.0.0.1:8788 only.
It talks to SBB on 127.0.0.1:8787 and to Sanary Build Gateway (SBG) on
127.0.0.1:8790 when they are running.
- Claude Code hooks. SBI adds
UserPromptSubmit and Stop hook entries to
~/.claude/settings.json and copies a small helper (sbi-claude-hook) to
~/.sbi/hooks/, so a Claude Code session in your workspace can be shown and
evaluated. When a hook fires, the helper passes your prompt, the session's
working directory and the Agent's last reply to the local Runtime (on this
Mac), which relays them to SBB for evaluation if SBB is running. Your other
settings and hooks are kept as they are; an unparseable settings.json is
never touched.
- Codex hooks. If Codex is installed, SBI adds the same two hooks to
~/.codex/hooks.json (helper: ~/.sbi/hooks/sbi-codex-hook) and records
Codex's trust for exactly those hooks in one clearly marked block in
~/.codex/config.toml. Nothing outside that block is edited; if your
config.toml defines hooks of its own, SBI adds nothing.
- Read-only observation. To show whether an Agent is working, SBI reads
Claude Code's session files (
~/.claude/sessions) and Codex's session
transcripts (~/.codex/sessions), and watches file changes, debug sessions
and terminal activity in the open workspace as an "active / idle" signal. It
never reads the contents of what you type in the terminal. On the monitoring
board the workspace is identified by its folder name and a one-way hash of
its path.
- Sanary Build Gateway and SBR (optional). If SBB, which hosts SBG on your
Mac, is running, the SBI Runtime reports to SBG on
127.0.0.1:8790:
the workspace folder name, whether the workspace is open and active, and whether
Claude Code or Codex is working. For an Agent run that starts from an instruction
sent by SBB (SBC) or an SBR device, it also reports a short work status — the
beginning of that instruction (up to 100 characters) and short result or
SBB-note lines (up to 160 characters each).
For Claude Code / Codex hooks it reports a one-line task summary (the first
line of your prompt, up to 40 characters) and SBB's short reason for its
decision. Your full prompts and replies are not sent to SBG; they go only to
SBB, on your Mac, for evaluation. SBG keeps this in memory (it stores only its
pairing records and its Remote Access setting). If you pair the SBR iPhone app,
SBG serves it to your paired device over your local network, authenticated with
the device credential issued at pairing. Neither SBI nor SBG sends it to any
Sanary server.
- Xcode. The SBI Runtime can also observe Xcode's built-in coding agents
(read-only, on the same Mac). This extension does not write to Xcode's
configuration.
Disable and uninstall
- Disabling the extension, or closing VS Code, leaves your Claude Code and
Codex configuration exactly as it is, so re-enabling just works. While the
extension is not running the hooks reach nothing and let every prompt pass.
- Uninstalling removes what SBI itself added: its hook entries in
~/.claude/settings.json and ~/.codex/hooks.json (the file too, if nothing
else was in it), its trust block in ~/.codex/config.toml, and
~/.sbi/hooks/. Your own hooks and settings are never touched. VS Code runs
this cleanup once, the next time it starts after the uninstall. An update (another version of
the extension installed alongside) is recognised and removes nothing.
- If you used an earlier version that registered SBI hooks in Xcode's own
Claude / Codex configuration, the first start of this version removes those
registrations (once).
SBB (optional)
SBB (Sanary Build Bridge) is a separate, optional Sanary app for macOS. If
it is running, SBI also sends an Agent's result to it for evaluation and shows
the decision next to the result. If it is not, the Agent still runs normally;
the evaluation is shown as unavailable, never as approved. SBI does not need SBB
to be installed.
Troubleshooting
- "
:8788 is occupied by a service that is not a compatible SBI Runtime" —
another program uses the port; quit it and reload the window.
- "the SBI Runtime on
:8788 is outdated" — an sbi-server that does not
offer everything this version needs (for example one left running by an older
install, or started by another window with an older extension) holds the port.
SBI does not reuse it, and does not stop it for you, so running an Agent
through SBI and workspace presence are unavailable until it is gone. To fix it:
- Find the process:
lsof -nP -iTCP:8788 -sTCP:LISTEN in Terminal (or look for
sbi-server in Activity Monitor). The Output Channel lists the missing
capabilities.
- Quit it (Activity Monitor → Quit, or
kill <pid>).
- Reload the window (Developer: Reload Window). SBI then starts its own
current Runtime; other open windows pick it up within about twenty seconds.
the SBI Runtime on :8788 does not advertise "localRequestGuard" (Output Channel) — the running Runtime, for
example one embedded in an older SBB, predates the check that keeps a web page in your browser from sending requests
to it. It keeps working and is not stopped for you. To use the hardened Runtime, quit that one and reload the window.- Logs are in the SBI Output Channel.
Current limitations
- macOS (Apple Silicon) only — see Supported platform.
- Only Claude Code and Codex are supported; no other Coding Agent.
- Multi-root workspaces use the first workspace folder only.
- Agent executable discovery does not install anything automatically.
- If VS Code is killed rather than closed, a Runtime it started can outlive it;
the next start reuses it.
Support, privacy and terms
SBI uses no account, no server storage and no analytics, and sends nothing to
Sanary; under the Sanary Privacy Policy, such an app collects no personal
information. What SBI reads and writes on your Mac, and what it hands to SBB /
SBG, is listed under What SBI changes on your machine. The Claude Code and
Codex CLIs you run send data to their own providers, exactly as they do without
SBI, and SBI does not change that. This extension itself includes no telemetry.
