Codey is one static binary with nothing to install alongside it, so there are three ways to get it and they differ only in what you need to have already.
A release. The releases page
has an archive for Linux and macOS, each on amd64 and arm64, with
checksums.txt beside them. Unpack the one for your machine and put codey
somewhere on your PATH. The archive names carry no
version, so the latest one is always at the same address:
# linux or darwin, amd64 or arm64
curl -L https://github.com/johannSo/codey/releases/latest/download/codey_linux_amd64.tar.gz | tar xz codey
With Go. If you have Go installed, this builds the latest release and puts
it in $(go env GOPATH)/bin:
go install github.com/johannSo/codey/cmd/codey@latest
@latest can be any tag, and codey --version reports the one you asked for.
The Go it needs is the one go.mod names; an older go command fetches that
toolchain by itself unless GOTOOLCHAIN says not to.
From source. For working on Codey, or running a commit that is not released yet:
git clone https://github.com/johannSo/codey
cd codey
go build -o codey ./cmd/codey
A build from a checkout reports the version the source was last released as,
not the commit; git log is the better answer to "which one is this". The
examples in these docs run it as ./codey, from the directory it was built
in. Installed on your PATH it is just codey.
Release binaries are not signed or notarized. A download through a
browser is quarantined and Gatekeeper refuses to open it; xattr -d com.apple.quarantine codey lifts that. The curl above does not quarantine
what it fetches, and neither does go install.
./codey -C /path/to/a/throwaway/clone # full-screen TUI
./codey -C /path/to/repo -p "why does TestFoo fail?" # one prompt
Codey needs a credential, and the ordinary one is an Anthropic API key, which you create at console.anthropic.com/settings/keys:
export ANTHROPIC_API_KEY=sk-ant-...
Started with nothing at all, Codey stops and says how to get one rather than failing on the first request.
A different endpoint — a gateway, a proxy, a local server speaking the Messages API:
./codey -base-url http://127.0.0.1:4000 -api-key ... -C .
# or ANTHROPIC_BASE_URL / ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN
Flags beat the saved config, which beats the built-in defaults; the config is
what the setup wizard writes on a first run. -auth-token sends
Authorization: Bearer, which is what OAuth tokens and most gateways want;
-api-key sends x-api-key. A non-default endpoint announces itself on
stderr, because your prompt and every file the agent reads go wherever that URL
points.
On your own machine, if you are logged into Claude Code, Codey can borrow the
OAuth credential Claude Code keeps in ~/.claude/.credentials.json instead of
needing a key. It does this only when asked: -claude-code-auth for one run, or
"claude_code_auth": "on" in the config — which the setup wizard and
/settings both offer — for every run. Be aware of what that is: the
credential is issued to Claude Code, and using it from another client is
outside Anthropic's terms for it, which API keys and gateway tokens do not
carry. That is why it is off until you turn it on, and why it is not something
to set up on a machine other people use.
Even when asked for, it is the last resort. It is tried only when no flag and
no environment variable supplied a credential, and only against Anthropic's own
endpoint — a credential found on disk is not one you chose to send, so it is
never forwarded to a -base-url you pointed Codey at. -no-claude-code-auth
refuses it for one run, whatever -claude-code-auth and the config say.
Earlier builds borrowed the login silently whenever nothing else was set. If
you relied on that, the first start after upgrading asks once, on the terminal,
whether to keep doing so, and saves the answer as claude_code_auth — yes or
no, so it is not asked again. A -p run, a pipe, and codey models have
nobody to ask, so they just report that there is no credential and how to get
one.
On macOS Claude Code keeps this in the Keychain rather than a file, so there is nothing to borrow there. An expired access token is refreshed automatically; the credentials file is left alone unless the server rotates the refresh token, in which case the replacement is written back — leaving the dead one there is what would break your Claude Code login.