# AGENTS.md

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

## Setup

```
uv sync
```

## Commands

```
make help
make test          # run the test suite, must pass before any commit
make test-parity
make bench
make build-proxy
make build-wheel
```

## Layout

- `tests/`    834 source files
- `headroom/` 530 source files
- `crates/`   198 source files
- `sdk/`      55 source files
- `plugins/`  35 source files
- `scripts/`  33 source files

## Conventions

- Tests live alongside the code they cover, following `crates/headroom-core/tests/auth_mode.rs`.
- CI defines what passing means. See `.github/workflows/changelog-guard.yml`, and keep it green.
- TODO: add the two or three conventions a newcomer always gets wrong here.

## Gotchas

- `headroom/proxy/handlers/openai.py` is 488KB. It will not fit comfortably in context, so read it in parts.
- Copy `.env.example` before running anything that needs configuration.

---

Drafted by agentreadme.com from what is in this repository. Everything marked TODO
needs a human. Check it in as AGENTS.md at the root.