Codey

Codey is a coding agent harness in Go. Point it at a repository, tell it to make the failing test pass, and measure how often it actually does.

It is one static binary: a full-screen TUI on a terminal, a drop-in for claude -p in scripts and CI, and an Agent Client Protocol agent that other UIs can drive, T3 Code included.

It works with an Anthropic API key, or with any gateway, proxy or local server that speaks the Messages API. If you already use Claude Code, Codey picks up its MCP servers, its permission rules, its CLAUDE.md files and, if you ask, its skills.

"Wait, what is this for?"

Measuring. The code is the byproduct. The deliverable is METRICS.md: pass rate, edit success, turns and cost across an eval suite, with one row for each change that could move them. PLAN.md is the build plan this follows.

Codey is still a full agent, with subagents, tabs and git worktrees, skills, MCP, web search, language-server diagnostics on every edit, and hooks. It is built so you can measure it.

Installation

[!WARNING] Codey needs a credential. The usual one is an Anthropic API key from console.anthropic.com/settings/keys:

export ANTHROPIC_API_KEY=sk-ant-...

• A gateway or local server: -base-url with -api-key or -auth-token, or ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN
• A Claude Code login: off unless you opt in with -claude-code-auth. That credential was issued to Claude Code, and using it from another client is outside Anthropic's terms for it. Read this first.

Release binary

Linux and macOS, amd64 and arm64, with checksums.txt on the releases page:

# linux or darwin, amd64 or arm64
curl -L https://github.com/johannSo/codey/releases/latest/download/codey_linux_amd64.tar.gz | tar xz codey

Put codey somewhere on your PATH. Release binaries are not signed. On macOS, a copy downloaded with a browser needs xattr -d com.apple.quarantine codey before it will run.

With Go

go install github.com/johannSo/codey/cmd/codey@latest

From source

git clone https://github.com/johannSo/codey
cd codey
go build -o codey ./cmd/codey

First run

codey -C /path/to/a/throwaway/clone                   # full-screen TUI
codey -C /path/to/repo -p "why does TestFoo fail?"    # one prompt, then exit

The first run on a terminal opens a short setup wizard that asks for the model, effort, approvals, web search and theme. /setup opens it again later, and /settings changes one setting at a time.

Some notes

Codey is early. Expect rough edges.

Approval prompts are not a sandbox. -yolo belongs inside a container or against a throwaway clone. Read Safety before you point Codey at anything you care about.

Documentation

Full docs live in docs/. There's no docs site.

• Install and first run: credentials, gateways, and the Claude Code login
• Flags: including compaction thresholds and turn caps
• The TUI: keys, images, questions, the mouse, ! shell, /model, /effort
• Tabs, worktrees and sessions
• Subagents and the agents sidebar
• Setup, /settings and where Codey keeps things
• Tools and diagnostics after every edit
• Skills, Claude Code's included
• Web search
• MCP servers, and trusting a project's .mcp.json
• Claude Code's settings: permissions and CLAUDE.md
• Hooks and herdr
• Using it in place of claude: -p, --output-format, --allowedTools
• Inside another editor: ACP, and Codey as a T3 Code provider
• Safety

Working on Codey itself? Start at docs/internals/overview.md.

Evals

./evals/selftest.sh    # no API calls: checks the tasks measure something
go run ./evals -n 3    # the real thing

Ten tasks, a fresh temp directory per run, full transcripts under evals/runs/<timestamp>/. The results are in METRICS.md.

License

MIT; see LICENSE.