Ceiling Guard

Ceiling Guard

[](https://github.com/ak2tx/ceiling-guard/actions/workflows/ci.yml) [](https://pypi.org/project/ceiling-guard/)

Don't lose another agent run to a plan limit.

Ceiling Guard shows how much of your Claude Code, Codex or Grok subscription window is left, warns your agent before it runs out, and writes a handoff for the next run. It reads usage the official CLIs already record on your machine — no provider credentials, no proxy, no account access.

Codex and Grok usage appears immediately. Claude publishes its percentage only during a non-interactive run, so wrap one Claude command to start tracking it.

Zero dependencies. Python 3.11+. Linux, macOS, Windows, or a container.

uv tool install ceiling-guard     # or, if you have it: pipx install ceiling-guard

cg setup                          # guided: finds your CLIs, seeds a reading, done

`cg setup` is the whole first run. It reports which agent CLIs it can see, offers to seed the Claude reading (Claude publishes its usage only while a run is in flight, so one short wrapped job is needed), installs the Agent Skill, and shows you the numbers. Re-run it any time to change settings.

Or drive it yourself:

cg quota                                    # read-only, nothing to configure
cg wrap -- claude -p "continue the migration"
cg statusline                               # -> cg 48%

**If you have neither `uv` nor `pipx`, use a venv — not `pip --user`.** On Debian, Ubuntu and every other PEP 668 distribution, the system Python is externally managed and `python3 -m pip install --user ceiling-guard` is refused outright:

python3 -m venv ~/.venvs/cg && ~/.venvs/cg/bin/pip install ceiling-guard
~/.venvs/cg/bin/cg quota

Measured on Ubuntu 24.04.4, Python 3.12.3, no pip cache: **2.9 seconds** from no install to a true reading, over three c