Installation

koda is a single static binary with no runtime dependencies. Install it from a package manager if you have one, or run the installer script, which builds from source and will offer to install Rust first if it is missing.

First run, from the shell100×30 · 0:21

The three commands that tell you the install worked: the version, the models your server reports, and one real answer.

Package managers

macOS / Linux

brew tap simpletoolsindia/koda   # once, ever
brew install koda

After the tap, the short name is all you need — brew install koda, brew upgrade koda, brew uninstall koda. The formula installs the prebuilt binary for your platform (macOS and Linux, Intel and ARM), so it is a download rather than a build, and it brings ripgrep with it for the fast path in koda’s search.

On Homebrew 6 and newer, a third-party tap has to be trusted once before it can be loaded. If you see Refusing to load formula ... from untrusted tap:

brew trust simpletoolsindia/koda

Then tap and install as above. Older Homebrew does not ask.

Why the tap, when brew install redis needs no such thing?

Because redis is in homebrew-core, the repository Homebrew ships with, and a bare name with no tap only resolves there. homebrew-core will not take a new formula until the project is notable: 30 forks, 30 watchers or 75 stars — and 90 forks, 90 watchers or 225 stars when the repository’s own owner submits it — plus a repository at least 30 days old. koda does not clear that bar yet. The formula name koda is unclaimed in homebrew-core, so nothing is lost by waiting; when the project qualifies, brew install koda works with no tap at all and this page will say so.

Windows

The manifest is submitted to the winget community repository and under review. Once it is merged, this is the whole installation:

winget install koda

koda is a portable package there: winget unpacks koda.exe into its own links directory and puts that on your PATH, so there is nothing to click through and winget uninstall koda removes it cleanly.

Until it merges, take the binary straight from the latest release — koda-<version>-x86_64-pc-windows-msvc.zip, unzip it, and put koda.exe somewhere on your PATH. The installer script below does the same thing from source.

The installers

macOS / Linux

Clone and run the script for an interactive menu — install, install system-wide, update, uninstall:

git clone https://github.com/simpletoolsindia/koda.git && cd koda
./install.sh

Or take the one-liner, which clones for you:

curl -fsSL https://raw.githubusercontent.com/simpletoolsindia/koda/master/install.sh | bash

It installs to ~/.local/bin, so no sudo is needed. For a system-wide install:

PREFIX=/usr/local ./install.sh

On macOS the installer re-signs the copied binary so Gatekeeper does not kill it.

Windows

PowerShell, with an interactive menu. It adds koda to your user PATH.

git clone https://github.com/simpletoolsindia/koda.git; cd koda
.\install.ps1

Or the one-liner:

irm https://raw.githubusercontent.com/simpletoolsindia/koda/master/install.ps1 | iex

It installs to %LOCALAPPDATA%\koda\bin. Override the location with -Prefix.

By hand

Anything with Rust 1.82 or newer:

git clone https://github.com/simpletoolsindia/koda.git && cd koda
cargo build --release
cp target/release/koda ~/.local/bin/

On Windows, copy to %LOCALAPPDATA%\koda\bin; on a system-wide Unix install, /usr/local/bin.

A packager who wants the smaller binary can drop the document readers:

cargo build --release --no-default-features

That removes PDF, Word and Excel parsing, which account for about 1.4 MB.

The two optional extras

At the end of an interactive install you are asked about two programs. koda needs neither of them to run.

Extra	What it buys you	If you decline
ripgrep	Faster search across large projects.	koda’s in-process search is used instead.
tesseract	Offline OCR, so a screenshot reaches a model with no vision.	Set ocr_model to a vision model instead — see Files, images & OCR.

Both are a single [Y/n] prompt. When the installer is piped (curl … | bash) it has no terminal to ask at, so both are skipped without one.

Building a different branch

The installers build master. To build something else, either check it out and run the script from the checkout, or name it:

KODA_BRANCH=my-branch ./install.sh

Verify it worked

koda --version
koda config          # the effective configuration, after every layer is applied

If koda is not found, the bin directory is not on your PATH. The installer prints the exact line to add to your shell profile; on macOS and Linux that is usually:

export PATH="$HOME/.local/bin:$PATH"

Updating and removing

Re-run ./install.sh and pick update from the menu — it pulls the branch you are on and rebuilds. Uninstall removes the binary. Your configuration (~/.config/koda/config.toml) and per-project data (<project>/.koda/) are left alone; delete those by hand if you want them gone.