# 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](https://agentclientprotocol.com) agent that other UIs can drive, [T3 Code](https://t3.codes) 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](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](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](https://console.anthropic.com/settings/keys):
>
> ```bash
> 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.](docs/user/install.md#quick-start)

### Release binary

Linux and macOS, amd64 and arm64, with `checksums.txt` on the [releases page](https://github.com/johannSo/codey/releases):

```bash
# 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

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

### From source

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

### First run

```bash
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](docs/user/safety.md) before you point Codey at anything you care about.

## Documentation

Full docs live in [docs/](docs). There's no docs site.

- [Install and first run](docs/user/install.md): credentials, gateways, and the Claude Code login
- [Flags](docs/user/flags.md): including compaction thresholds and turn caps
- [The TUI](docs/user/tui.md): keys, images, questions, the mouse, `!` shell, `/model`, `/effort`
- [Tabs, worktrees and sessions](docs/user/tabs.md)
- [Subagents](docs/user/subagents.md) and the agents sidebar
- [Setup, `/settings` and where Codey keeps things](docs/user/setup.md)
- [Tools](docs/user/tools.md) and diagnostics after every edit
- [Skills](docs/user/skills.md), Claude Code's included
- [Web search](docs/user/web-search.md)
- [MCP servers](docs/user/mcp.md), and trusting a project's `.mcp.json`
- [Claude Code's settings](docs/user/claude-code-settings.md): permissions and CLAUDE.md
- [Hooks](docs/user/hooks.md) and [herdr](docs/user/hooks.md#herdr)
- [Using it in place of `claude`](docs/user/in-place-of-claude.md): `-p`, `--output-format`, `--allowedTools`
- [Inside another editor](docs/user/editors.md): ACP, and Codey as a T3 Code provider
- [Safety](docs/user/safety.md)

Working on Codey itself? Start at [docs/internals/overview.md](docs/internals/overview.md).

## Evals

```bash
./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](METRICS.md).

## License

MIT; see [LICENSE](LICENSE).