Installation

Install unch with npm, Homebrew, shell installer, PowerShell, go install, or build from source.

Fastest path

Use npm for the simplest cross-platform install.

Native installers

Homebrew, shell installer, and PowerShell installer are available when you prefer platform-native flows.

Most flexible

Use go install or build from source when you want a local checkout or custom toolchain flow.

Requirements

The npm package and release installers use published archives by default, so Go is not required on supported targets.

If you install with go install, build from source, or install on a target without a matching release archive, you need:

• Go 1.25+
• a working C toolchain

On Windows source builds, that means an MSYS2 or MinGW-style toolchain, or an equivalent setup.

Choose an install path

npm (recommended)

npm install -g @uchebnick/unch

This installs the unch CLI and downloads the matching native release binary for your platform.

Verify it:

unch --version
unch --help

To use unch inside Codex as MCP tools plus the unch skill:

unch codex install

Then restart Codex. The setup command uses codex mcp add for the MCP server and writes the skill to ~/.codex/skills/unch/SKILL.md.

If you prefer not to add Codex integration, you can skip unch codex install.

Homebrew (macOS)

brew install uchebnick/tap/unch

Upgrade later with:

brew upgrade unch

Shell installer (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/uchebnick/unch/main/install.sh | sudo sh -s -- -b /usr/local/bin

This installs unch into a system PATH directory so you can run it immediately after the installer finishes.

On Apple Silicon macOS, use /opt/homebrew/bin instead of /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/uchebnick/unch/main/install.sh | sudo sh -s -- -b /opt/homebrew/bin

Pin a version or choose a destination:

curl -fsSL https://raw.githubusercontent.com/uchebnick/unch/main/install.sh | sudo sh -s -- -b /usr/local/bin
curl -fsSL https://raw.githubusercontent.com/uchebnick/unch/main/install.sh | sudo sh -s -- -b /usr/local/bin -v <tag>

install.sh verifies downloaded release archives against the published checksums.txt file. It is smoke-tested in CI on Ubuntu, Debian, Arch, and NixOS-like Linux environments, including the default no--b path selection flow.

PowerShell (Windows)

iwr https://raw.githubusercontent.com/uchebnick/unch/main/install/install.ps1 -useb | iex

Default install location:

$HOME\AppData\Local\Programs\unch\bin

After downloading the script locally, you can override the target or pin a version:

.\install\install.ps1 -BinDir "C:\Tools\unch\bin" -Version <tag>

unch is available immediately in the current PowerShell session after the installer finishes. To keep it available in future PowerShell or terminal sessions, add $HOME\AppData\Local\Programs\unch\bin to your user PATH.

The PowerShell installer is smoke-tested in CI on Windows x86_64 and arm64.

go install

go install github.com/uchebnick/unch/cmd/unch@latest

This install path requires a cgo-capable Go toolchain. It is smoke-tested in CI in the official Debian-based Go container image. To pin a specific release, use @<tag>.

Older references to github.com/uchebnick/unch-searcher should be treated as legacy.

Build from source

git clone https://github.com/uchebnick/unch.git
cd unch
go build -o unch ./cmd/unch

On Windows:

go build -o unch.exe ./cmd/unch

Published release archives

Platform	Architectures	Status
macOS	arm64, x86_64	Supported
Linux	arm64, x86_64	Supported
Windows	arm64, x86_64	Supported

Verify the install

unch --version
unch --help

If you installed through npm and want Codex integration:

unch codex install

Configure OpenRouter

If you want to use OpenRouter for embeddings instead of the local llama.cpp runtime:

unch auth openrouter --token sk-or-...
unch index --provider openrouter --model openai/text-embedding-3-small

By default unch auth openrouter stores the token in:

~/.config/unch/tokens.json

That keeps the token out of your project checkout and out of your shell environment.

For one repository only, use:

unch auth openrouter --token sk-or-... --local

That writes:

.semsearch/tokens.json

When should I prefer release installers?

Prefer the release installers when your platform has a matching published archive and you just want a working binary quickly.

That path does not require Go and is the one covered by install smoke checks in CI.

When should I use go install or build from source?

Use source-based install when you want to work from a checkout, pin your own toolchain, or run on a target without a matching release archive.

What is special about Windows source builds?

Windows source builds need a working C toolchain.

In practice that means MSYS2, MinGW, or an equivalent environment that can build the Tree-sitter and SQLite dependencies.

If unch is installed but not found, make sure the installer destination is on your PATH.