Tideline

A zero-token sentinel for your Claude usage windows. No API key, no account, stdlib-only Python 3.

Tideline watches how close you are to your Claude limits before you hit a wall — and can auto-pause your agent when you get near it. It leads with the rolling 5-hour Max window (the limit you actually hit day-to-day), with the weekly window as a secondary gauge. The alarm always watches the higher of the two.

Token Guardian — Max window sentinel
  88.0%  5h window     ████████████████░░░░
  gate 88.0% · weekly 55.0%   — alarm watches the higher of 5h / weekly
  5-hour  ████████████████░░  88.0%  · resets 18:39
  weekly  ██████████░░░░░░░░  55.0%  · resets Aug 2

Two tiers, degrades gracefully

1. Max-window % (headline). Reads your live 5h / weekly subscription usage from the OpenClaw CLI (openclaw status --usage --json). This is the authoritative tier and drives the gate + alerts. Needs the OpenClaw stack installed.
2. Local-transcript estimate (fallback, zero-token). Reads Claude Code's JSONL transcripts under ~/.claude/projects/ (read-only), prices them from a static table, and estimates spend + burn rate. Works with no OpenClaw — just Claude Code.

If you don't run OpenClaw, Tideline still works as a local-transcript spend estimator (tier 2); the live Max-window percentages (tier 1) simply stay blank.

The insight worth knowing

On Claude Code, cost-per-turn scales with context size. Each turn re-reads the whole transcript (mostly cheap cache-reads, but it adds up), so a long session gets steadily more expensive per message — and burns your 5h window faster. Tideline makes that visible and points at the one real lever: rotate to a fresh session when context gets heavy. Drop a short handoff note, start clean, and your per-turn cost resets.

Quick start

No install, no dependencies — just Python 3:

git clone https://github.com/oocm147/tideline.git
cd tideline
python3 tideline.py --json      # one-shot status as JSON

Usage

tideline.py --json              machine-readable status (gate %, 5h %, weekly %, burn)
tideline.py --web               auto-refreshing dashboard on http://127.0.0.1:8791
tideline.py --web --port 9000   dashboard on a different port
tideline.py --daemon            long-running sentinel: alerts at thresholds
tideline.py --once              run exactly one cycle (for cron / periodic checks)

Always-on (systemd user services)

Two small services — one alerts, one serves the dashboard. Example units:

# ~/.config/systemd/user/tideline.service   — alerts daemon
[Service]
ExecStart=/usr/bin/python3 %h/tideline/tideline.py --daemon
Restart=on-failure
[Install]
WantedBy=default.target

# ~/.config/systemd/user/tideline-web.service   — dashboard on :8791
[Service]
ExecStart=/usr/bin/python3 %h/tideline/tideline.py --web --port 8791
Restart=on-failure
[Install]
WantedBy=default.target

systemctl --user enable --now tideline.service tideline-web.service
# then bookmark http://localhost:8791

Configuration

All optional, via environment variables:

Variable	Default	Meaning
TIDELINE_TG_TARGET	(unset — off)	Telegram chat id for push alerts (needs OpenClaw CLI). Blank = log-only.
TIDELINE_COORD_LANE	agent:main:coord	OpenClaw agent lane the auto-pause trigger targets.

Pricing lives in the PRICING table at the top of tideline.py — edit it as rates change. Unknown models price as the (pricey) fallback, so a new model over-estimates rather than silently under-counting.

Auto-pause (optional)

In --daemon mode, when the gate crosses your top threshold Tideline can write a pause-trigger file that an OpenClaw agent watches — so your agent finishes its current step, writes a turnover note, and stops before it hits the wall. Purely opt-in and OpenClaw-specific; without it, the daemon just alerts.

Honest caveats

• The % tier needs OpenClaw; the $ tier is an estimate. The 5h/weekly percentages come from OpenClaw's usage feed. The dollar figure prices local token counts with a static table — a gauge, not an invoice.
• Reads a transcript format Claude Code owns. If a Claude Code update changes the JSONL shape, the parser may need a tweak. It fails safe (skips unreadable lines).
• Read-only on your transcripts. Tideline never writes to ~/.claude. It only writes its own state + alert log under ~/.openclaw/ (or your configured home).

License

MIT — see LICENSE.