Installation and updates¶
Install zeroshot covers setup. This page describes how installation and updates behave.
Archive verification¶
Install the zeroshot command and its agent skills through the npm delivery package, which requires
Node.js 18 or newer. The installer selects the release target declared for the current system and
checks the downloaded archive against SHA256SUMS before writing the native executable.
Update behavior¶
A canonical CLI release can update its executable and managed agent skills in place. The command
selects the newest GitHub release for the current platform, verifies its archive and skill assets
against that release's SHA256SUMS, and verifies the new executable before replacing the old one:
The update does not elevate privileges. Before downloading release assets for a newer version,
it checks that the installation directory is writable. A current executable still reports
"updated":false when that directory is unwritable; managed skills are refreshed separately.
Updates of one installation replace it one at a time. An update that waited for another one and
finds the same release already installed reports "updated":false. Before installing a newer
release, an update also removes the files that interrupted updates left next to the executable.
A download fails with a timeout once the server has sent nothing for 30 seconds; a slow download
that keeps receiving data is never cut off. Failures name their cause, such as an unreachable or
refusing proxy, an untrusted certificate, or GitHub's explanation of a rate limit.
An unwritable installation or rejected archive ends with an npm reinstall command pinned to the
release being installed. A release lookup refused with HTTP 403 or 429 instead names
npm install --global @the-open-engine-company/zeroshot@latest, because no release version was
resolved. The updater uses anonymous GitHub requests.
Unchanged managed skill copies are installed or refreshed for Codex, GitHub Copilot, Pi, and Claude
Code. A user-edited or conflicting skill is preserved, and the command fails with its exact path
after completing any safe updates.
Older updaters install only the skills they know. If zeroshot-graph-design or zeroshot-plan is
missing after an executable upgrade, run zeroshot update again. The current updater refreshes all
managed skills even when the executable version is already current.
An in-place update of a writable npm installation is supported. It replaces the executables under
the package's bin/native directory without changing package.json or npm's installation records.
npm list --global therefore reports the npm package version originally installed, while
zeroshot --version reports the updated executable. A later npm install uses its selected package
version to replace the executables again. To synchronize npm's records with the CLI, reinstall the
desired version with npm install --global @the-open-engine-company/zeroshot@X.Y.Z.
Network access¶
zeroshot has no telemetry, analytics or crash reporting. The CLI makes network requests only for these:
| When | What it contacts |
|---|---|
| npm install | GitHub release downloads, for the platform executable |
zeroshot update |
The GitHub API for the latest release, then its downloads. Requests are anonymous. Nothing checks in the background |
| A run | The model providers, gateways and connections in your runtime plan, through the agents and scripts it starts |
| Delivery and review | The GitHub or GitLab host of the repository |
--target or zeroshot target login |
That target only, self-hosted or zeroshot Platform |
zeroshot starts Pi with PI_TELEMETRY=0 and Copilot with session telemetry off. Claude Code and
Codex follow their own settings. Agents and scripts can also reach whatever their own tools reach.
zeroshot ui serves the workspace UI from your machine and loads nothing from other hosts.
Managed skills¶
The package installs the zeroshot, zeroshot-memory-init, zeroshot-graph-design, and
zeroshot-plan skills for Codex, GitHub Copilot, and Pi under
$HOME/.agents/skills/<name>, and for Claude Code under
${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/<name>. No agent selection or
per-project installation is needed. npm 7 and newer do not run uninstall hooks; after removing the
package, remove only unmodified managed skill directories from these locations.
With automatic skill installation enabled, CLAUDE_CONFIG_DIR must be absolute when set so the
global skills have stable locations.
Use zeroshot-graph-design for a guided interview to design a graph for your repository.
To install or update only the executables, set ZEROSHOT_SKIP_SKILLS=1:
ZEROSHOT_SKIP_SKILLS=1 npm install --global @the-open-engine-company/zeroshot
ZEROSHOT_SKIP_SKILLS=1 zeroshot update
Only the exact value 1 enables the opt-out. Both commands skip all user-scope skill installation
and leave existing skills untouched, even when destinations conflict or are unwritable.
Export the variable in your shell configuration to keep future updates from recreating skills you
remove. In PowerShell, set $env:ZEROSHOT_SKIP_SKILLS = '1' before running either command.
Unset the variable to restore automatic installation and refresh of unchanged managed skills.
Windows paths¶
On Windows, the CLI and local in-process runs work natively from PowerShell or Command Prompt.
Install Git for Windows and put Git and your chosen harness on PATH; npm-installed .cmd
launchers are supported. Local configuration defaults to %LOCALAPPDATA%\zeroshot and run state
to %LOCALAPPDATA%\zeroshot\state. ZEROSHOT_CONFIG_DIR and ZEROSHOT_STATE_DIR can override
these with absolute paths. The hosted target image requires Linux.
Build the workspace UI¶
Embedding hosts use the workspace bridge contract.
Release executables embed the UI. To build it from source:
npm --prefix ui ci --ignore-scripts
npm --prefix ui run build
cargo build --release --package zeroshot --features ui
./target/release/zeroshot ui
Node.js is needed for this build, not to serve the resulting UI. Library consumers
can leave the ui feature disabled.
Release assets¶
Each GitHub release includes native archives,
the canonical zeroshot-skill.md, zeroshot-memory-init-skill.md,
zeroshot-graph-design-skill.md, and zeroshot-plan-skill.md, and SHA256SUMS; archive
names contain the release version and target triple.