headroom
Capture ·
Install ·
CLI reference ·
Bounds ·
Troubleshooting
Claude Code and Codex enforce rolling usage limits but show the numbers only to a human, so the model never sees them and can keep working right up to the wall. headroom captures those readings and warns the model when it should conserve usage.
Install and first run
The shortest path:
uv tool install headroom-cli
headroom init --all
headroom status
To work from a clone instead, run one of these:
uv tool install .
pip install -e .
Then run headroom init --all and headroom status. Plain headroom init configures Claude Code only, while --codex configures Codex only. See the installation guide for safe previews and the plain-clone fallback.
Example output
headroom status reports every source and window:
Claude
5h: 12% used [ok], resets in 1h 59m
7d: unavailable
Codex
5h: unavailable
7d: >=94% used [critical], resets in 1h 59m
Near a limit, the prompt hook gives the model a short action:
Usage headroom: Codex weekly >=94% used (reading 1h 0m old), resets in 1h 59m.
Stop parallel subagent fan-out, use cheaper models, and checkpoint work now.
Documentation
| Document | What it covers |
|---|---|
| CLI reference | Every command, flag, environment variable, state file, exit code, and the opt-in update check. |
| Why the bounds are sound | Fresh, stale, and post-reset readings, reset validation, and severity. |
| How capture works | Claude statusline input, Codex app-server RPC, and rollout fallback. |
| Installation guide | Claude Code settings, the CODEX_HOME/hooks.json path, safe init previews, backups, and clone installs. |
| Troubleshooting | Unavailable or stale readings, unknown resets, doctor output, and state reset. |
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file headroom_cli-0.1.2.tar.gz.
File metadata
- Download URL: headroom_cli-0.1.2.tar.gz
- Upload date:
- Size: 109.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2c3657b1923268c9d5256a31ca62ead23d288c6f9589e149440e8431488237e8
|
|
| MD5 |
9d7dac087d4b91493090e3d93725b8b7
|
|
| BLAKE2b-256 |
e75cd8fd60097c064e8c0375c062f2de6c1877c14665025a84204b4f5cc3caf1
|
File details
Details for the file headroom_cli-0.1.2-py3-none-any.whl.
File metadata
- Download URL: headroom_cli-0.1.2-py3-none-any.whl
- Upload date:
- Size: 56.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7e187c07ae59e20fa6889b07b6117623aaee47cae3452f626c37ca3b15d2a703
|
|
| MD5 |
5708fccbbbee9d048cf1fe9c6c6ee0c6
|
|
| BLAKE2b-256 |
9115968b8328e4d4973e0149314b1dfc0551ceae42256f7769fc6260e5fd93b1
|
