Getting started

Install

Pick the path that matches how current you want to be. The installer gives you the latest tagged release; go install ...@main gives you the branch, which is where the capability profiles, research budgets and custom agents actually live.

# latest tagged release (v0.2.6)
curl -fsSL https://raw.githubusercontent.com/ramsterr/Wombat/main/install.sh | bash

# current main — recommended if you want what this site documents
go install github.com/ramsterr/Wombat/cmd/wombat@main

# from a checkout
git clone --depth 1 --single-branch --no-tags https://github.com/ramsterr/Wombat.git
cd Wombat
go build -o wombat ./cmd/wombat

go install writes the binary to $(go env GOPATH)/bin. If the command is not found afterwards, add that directory to PATH. Homebrew users can install the tagged release with brew install ramsterr/wombat/wombat.

First run

wombat setup    # provider, API key, model
wombat doctor   # config, permissions, connectivity
wombat          # open the chat

setup runs automatically on first launch and writes ~/.wombat/config.json. It understands OpenAI-compatible APIs (including self-hosted gateways), Anthropic, OpenCode and local model servers. Keys can live in the environment instead of the file — OPENAI_API_KEY, ANTHROPIC_API_KEY, and the provider-specific variables each gateway uses.

wombat doctor is safe to run at any time: it prints the resolved config with keys redacted, checks permissions, and makes a small connectivity call to the provider.

Which interface you get

The classic terminal interface works out of the box with zero extra build steps. The newer opentui interface is optional: build it once inside the checkout and Wombat loads it automatically on the next start.

git clone https://github.com/ramsterr/Wombat.git
cd Wombat/tui
npm install
npm run build
cd ..
./wombat            # new UI loads because this checkout has the build

Both interfaces run the same agent, tools, sessions and permissions; only the rendering differs. Switch back with wombat classic, wombat chat, or WOMBAT_CLASSIC=1 wombat.

Run a task without the UI

wombat run "summarize this repository and find the test command"
wombat run --yolo "fix the failing tests and explain the change"
wombat run -m gpt-5 -p openai "port the CLI to the new flag parser"
wombat run --profile minimal "rename the helper and update call sites"

run executes one task and exits. -c continues the latest session, --quiet prints only assistant text, and --yolo auto-approves tool permissions for that run. The full flag list is in the CLI reference.

Updating

wombat upgrade                  # latest tagged release
wombat upgrade --check          # is there a newer release?
go install github.com/ramsterr/Wombat/cmd/wombat@main   # stay on the branch

Windows

Install WSL2 with wsl --install and run the macOS/Linux command inside Ubuntu. Git Bash works for the native build, but the bash tool needs a POSIX sh, so native PowerShell and cmd are not fully supported.

Where to go next