Files
headroom/AGENTS.md
64dbd5cc49 docs: add AGENTS.md for agents using Headroom and agents changing the repo (#4532)
## Description

Agent-readiness crawlers and coding agents read `AGENTS.md` before
anything else, and this repo had none (nor a `CLAUDE.md`), even though
`headroom learn` writes them for other projects. In the recorded sandbox
runs both Claude Code and Codex read the installed source to learn the
result fields and `HEADROOM_OFFLINE`, and Codex fetched
`github.com/headroom-sdk/headroom` from memory (404).

Depends on #4529 for the `/docs/fastapi` link.

## Type of Change

- [x] Documentation update

## Changes Made

- `AGENTS.md`, block 1 "to use Headroom in an app": install,
`compress()`, result fields, offline semantics, the zero-network check,
the ASGI-middleware caveat, the canonical repo and the two wrong URLs
agents remember.
- Block 2 "to change this repo": layout, setup and check commands (from
`CONTRIBUTING.md` and the `Makefile`), Conventional Commits, no
`CHANGELOG.md` edits, Real behavior proof, one docs site, API names in
examples must exist in `headroom/compress.py`, one savings claim, and
the `version-sync.py` / `verify-versions.py` pair.

## Testing

- [x] Manual testing performed

### Test Output

```text
20031 -> 95 FATAL kept: True
curl -I github.com/chopratejas/headroom -> 301 https://github.com/headroomlabs-ai/headroom
curl -I github.com/headroom-sdk/headroom -> 404
```

## Real Behavior Proof

- Environment: macOS arm64, published `headroom-ai==0.42.0` wheel in a
clean venv.
- Exact command / steps: ran the zero-network one-liner from the file
verbatim; checked every command in block 2 against `Makefile` targets
(`ci-precheck`, `ci-precheck-rust`, `install-git-hooks`) and
`CONTRIBUTING.md`; `curl -I` on `github.com/chopratejas/headroom` (301
to headroomlabs-ai) and `github.com/headroom-sdk/headroom` (404).
- Observed result: `20031 -> 95 FATAL kept: True`; all named targets
exist.
- Not tested: nothing executes this file.

## Runtime Rollout Safety

- Rollout-managed feature(s): none; documentation and metadata only, no
runtime code path changes
- Minimum rollout channel: n/a
- Stable/default behavior changed: no
- Kill switch / disable path: n/a (revert the PR)
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert the commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-11-03 23:37:41 -06:00

3.4 KiB

AGENTS.md

If you landed here to use Headroom in an app

The PyPI package is headroom-ai; the import and the CLI are headroom.

pip install headroom-ai
from headroom import compress

result = compress(messages, model="gpt-4o")  # OpenAI or Anthropic message dicts
# send result.messages instead of messages; log result.tokens_before / tokens_after / tokens_saved

In-process, no API key, no model download. HEADROOM_OFFLINE=1 makes the run zero-network (no update check, no model or pricing-table downloads, no beacon). Verify without a provider key:

HEADROOM_OFFLINE=1 python -c "from headroom import compress; log='\n'.join(f'INFO step {i} ok' for i in range(3000))+'\nFATAL disk full'; r=compress([{'role':'user','content':'What failed?'},{'role':'assistant','content':None,'tool_calls':[{'id':'c1','type':'function','function':{'name':'logs','arguments':'{}'}}]},{'role':'tool','tool_call_id':'c1','content':log}], model='gpt-4o'); print(r.tokens_before, '->', r.tokens_after, 'FATAL kept:', 'FATAL' in str(r.messages))"
  • FastAPI example: https://docs.headroomlabs.ai/docs/fastapi
  • Full docs index for agents: https://docs.headroomlabs.ai/llms.txt (hand-curated subset: llms.txt in this repo)
  • Coding agents (Claude Code, Codex, Cursor, Copilot): uv tool install --python 3.13 "headroom-ai[all]" then headroom wrap claude
  • headroom.integrations.asgi.CompressionMiddleware is for apps that serve /v1/chat/completions-style routes, not for an app that calls a provider; use compress() for that
  • Canonical repo: https://github.com/headroomlabs-ai/headroom. github.com/chopratejas/headroom redirects here; there is no headroom-sdk org. The PyPI distribution named headroom is a different project.

If you are changing this repo

  • Layout: Python package in headroom/, Rust core and PyO3 extension in crates/ (built by maturin), TypeScript SDK in sdk/typescript/, docs site (Next.js + Fumadocs) in docs/content/docs/, agent plugins in plugins/, examples in examples/.
  • Setup: uv sync --extra dev and make install-git-hooks (pre-commit, commitlint, pre-push). Python checks: uv run ruff check ., uv run ruff format ., uv run pytest. Rust checks: make ci-precheck-rust. All gates: make ci-precheck. See CONTRIBUTING.md.
  • Commits and PR titles are Conventional Commits (feat:, fix:, docs:, ...). Never edit CHANGELOG.md; release-please writes it from PR titles.
  • Every external PR needs a "Real behavior proof" section (setup, exact commands, observed output, what was not tested). Bug fixes need a test that fails before the fix.
  • One docs site: docs/, deployed by Vercel to docs.headroomlabs.ai. wiki/ and the gh-pages branch are not published; do not add content there.
  • Public API examples in README.md, llms.txt, AGENTS.md and docs/ must use names that exist in headroom/compress.py (compress, CompressResult.messages, .tokens_before, .tokens_after, .tokens_saved, .compression_ratio, .transforms_applied).
  • Savings claims anywhere in the repo must match the measured table under "Proof" in README.md: 21-57% on the four agent scenarios, 90%+ on repeated JSON arrays and log lines, little on prose.
  • Version-carrying files (pyproject.toml, plugin and marketplace manifests, sdk/typescript/package.json, server.json) are kept in step by scripts/version-sync.py and gated by scripts/verify-versions.py; add any new one to both.