Install

HooCode ships two ways: a standalone binary with no runtime to install, and an npm package for machines that already have Node. Both give you the same hoocode (and hoo) command.

One-click install

macOS and Linux

curl -fsSL https://kolisachint.github.io/hoocode/install.sh | sh

Windows

irm https://kolisachint.github.io/hoocode/install.ps1 | iex

That is the whole thing. The installer:

1. Detects your platform — including musl vs glibc, which decides which Linux build you get. Alpine and static distroless images are supported.
2. Downloads the matching standalone binary from the latest GitHub release and verifies its SHA256 against the release’s checksums.txt.
3. Installs into ~/.hoocode/lib/hoocode and links ~/.hoocode/bin/{hoocode,hoo}.
4. Pre-seeds the external tools into ~/.hoocode/bin, which is exactly where HooCode looks for them — so your first run is fast and works offline.
5. Adds ~/.hoocode/bin to your PATH.

Nothing needs root or administrator rights. Everything lands under your own home directory, and re-running the installer upgrades in place.

Installer options

Both installers take the same options, as flags or as environment variables.

HOOCODE_RELEASE_BASE_URL expects the same layout a release has — <base>/<tag>/hoocode-<target>.tar.gz and <base>/<tag>/checksums.txt — so an air-gapped or bandwidth-limited network can mirror a release once and point every machine at it.

A piped script cannot take arguments, so to pass options either set the environment variable:

HOOCODE_SKIP_TOOLS=1 sh -c "$(curl -fsSL https://kolisachint.github.io/hoocode/install.sh)"

or download the script first:

curl -fsSL https://kolisachint.github.io/hoocode/install.sh -o install.sh
sh install.sh --no-tools --version v1.2.3

irm https://kolisachint.github.io/hoocode/install.ps1 -OutFile install.ps1
.\install.ps1 -NoTools

Install from npm

Needs Node.js ≥ 20. Works on any platform Node runs on, including ones with no prebuilt binary.

npm install -g @kolisachint/hoocode-agent
hoocode --help

pnpm add -g, yarn global add, and bun install -g all work too — HooCode detects which one installed it and offers the matching self-update command.

Download a binary by hand

Every release publishes a standalone archive per platform, plus a checksums.txt covering all of them.

Windows on ARM runs the x64 build under emulation; there is no native arm64 Windows binary yet, because the compiler has no such target.

Grab them from the releases page, verify, and unpack:

sha256sum -c checksums.txt --ignore-missing
tar -xzf hoocode-linux-x64.tar.gz -C ~/.hoocode/lib/hoocode

The binary expects the rest of the archive (themes, docs, canvas SDK, examples) to sit beside it, so unpack the whole thing rather than pulling out just the executable.

External tools

Five optional Rust binaries. HooCode works without every one of them — the installer pre-seeds them so that is never the reason your first session is slow.

HooCode fetches whichever of these it needs on demand anyway, so --no-tools is a valid choice — it only trades a slower first run.

Already have fd or rg from your package manager? HooCode uses whatever is on PATH before it downloads anything.

Restricted and offline environments

HooCode runs with no network access.

• HOOCODE_OFFLINE=1 (or --offline) disables every startup network operation — no binary downloads, no version checks. Search and file autocomplete fall back to the built-in pure-JS implementations, so both keep working.
• HOOCODE_NATIVE_SEARCH=1 forces the pure-JS path even when fd/rg are available. It also engages automatically when they are not.
• Pre-seed the binaries for native speed offline: install them from your OS package manager, or run the installer once on a connected machine and copy ~/.hoocode/bin across.

The interactive UI never blocks on these downloads — it starts immediately and wires fd in once resolved, so a slow or blocked network never delays launch.

Containers and Kubernetes

HooCode runs in containers, including as root and with a read-only root filesystem (config-directory writes fail silently rather than crashing). Three prerequisites are inherent to running an LLM agent and are not things HooCode can work around:

1. A provider credential. Set an API key (ANTHROPIC_API_KEY, OPENAI_API_KEY, …) or, for Copilot, the explicit COPILOT_GITHUB_TOKEN. A bare GH_TOKEN/GITHUB_TOKEN is not treated as an LLM credential.
2. Network egress to the model. The container’s egress policy must allow the provider host (e.g. api.anthropic.com), or point HooCode at an in-cluster OpenAI-compatible endpoint. A fully air-gapped pod cannot reach a hosted LLM.
3. A writable path for config and sessions. With readOnlyRootFilesystem: true, mount a writable volume (an emptyDir will do) for ~/.hoocode — or set HOOCODE_CODING_AGENT_DIR to one — and either run with --no-session or point --session-dir somewhere writable. Combine with HOOCODE_OFFLINE=1 to skip all startup network operations.

Alpine and other musl images are supported by the -musl archives; the installer picks the right one for you.

Build from source

bun is the toolchain. It is pinned to the npm-compatible hoisted linker in bunfig.toml, so it produces a flat node_modules. bun.lock is the authoritative lockfile.

git clone https://github.com/kolisachint/hoocode.git
cd hoocode

bun install          # install all dependencies
bun run build        # build all packages
bun run check        # lint, format, and type check
./test.sh            # run tests (skips LLM-dependent tests without API keys)

To produce the release archives locally:

./scripts/build-binaries.sh                      # every target
./scripts/build-binaries.sh --targets linux-x64  # just one
./scripts/build-binaries.sh --list               # what targets exist

bun build --compile cross-compiles, so one machine builds every platform’s archive.

Uninstall

rm -rf ~/.hoocode          # binary, tools, config, sessions and auth

Then drop the ~/.hoocode/bin line the installer added to your shell rc file. On Windows, remove %USERPROFILE%\.hoocode and the matching entry from your user PATH.

If you installed from npm: npm uninstall -g @kolisachint/hoocode-agent.

Something here wrong or missing? Open an issue — install problems are the most useful bug reports we get, because they are the ones that stop people before they start.

And if HooCode earns its place in your terminal, a star is the cheapest way to say so. ★