CC AIO MON — Claude Code Terminal Monitor

The Bandit badge tracks report publication; findings are reviewed in code scanning.

Real-time terminal monitor for Claude Code CLI. Track context window usage, API rate limits, session costs, burn rate, and cache performance — all in one compact TUI dashboard. Stdlib only (Python 3.8+), cross-platform.

Independent community project. Not affiliated with or endorsed by Anthropic. See NOTICE for provenance & trademark attribution.

How it works: Claude Code pipes session telemetry as JSON to statusline.py via stdin on session start or resume, after each assistant message, a completed /compact, a permission mode change or vim mode toggle, when a rate-limit reset or prompt-cache expiry passes, and every refreshInterval seconds if set (300ms debounce). The script parses the JSON, renders a single ANSI-colored status line in the terminal, and writes the data to $TMPDIR/claude-aio-monitor/ as atomic JSON snapshots + append-only JSONL history. A separate monitor.py process polls these temp files and renders a fullscreen TUI dashboard; sessions in the Claude desktop app, which never run the statusline, are read from their transcripts instead. Both scripts share shared.py for burn rate ($/min) and context rate (%/min) calculation. A pulse.py background worker probes Anthropic backend stability (status.claude.com status page + HTTPS endpoint) for a "safe to code / not safe to code" verdict — disable with CC_AIO_MON_NO_PULSE=1. Five runtime Python files, stdlib only, no build step.

Input	Claude Code statusLine JSON protocol via stdin — model info, context window, rate limits, cost, token counts, session metadata
Output	ANSI truecolor terminal — single-line statusline + fullscreen TUI dashboard with progress bars, smart alerts, cross-session cost aggregation
Data flow	Claude Code → stdin JSON → statusline.py → temp files → monitor.py → TUI
Files	statusline.py (statusline renderer + IPC writer), monitor.py (TUI dashboard), shared.py (shared helpers + rate math), update.py (self-updater), pulse.py (Anthropic backend stability monitor)
IPC	Atomic JSON snapshots + JSONL history in $TMPDIR/claude-aio-monitor/ — no sockets, no databases

_{Fullscreen dashboard — context window, API ratio, cache hit rate, rate limits, burn rate and cross-session cost at a glance. Shown here for a desktop app session, where values are estimated from the transcript.}

_{Statusline — a single-line status bar (model, context, rate limits, cost, burn) for your Claude Code prompt.}

Why CC AIO MON?

Project	Data source	Limitation
claude-monitor	Reads JSONL cost logs	Estimated data, not real-time
ccusage	CLI usage aggregator	Historical only, no live view
ccstatusline	Status line script	No TUI, no multi-session
CC AIO MON	Official stdin JSON protocol	Real-time, stdlib only, most complete

Other monitors scrape log files or estimate costs from token counts. For Claude Code in a terminal, CC AIO MON reads the official Claude Code statusline JSON — the cost, context and rate limits Claude Code itself reports. Claude desktop app sessions have no statusline, so for them the monitor estimates the same metrics from the session transcript and labels them as estimates.

_{Menu (m) — the navigation hub: views, system actions, and the scroll-key reference.}

_{Legend (l) — hotkeys first, then the full glossary of every metric code (scroll for more).}

Setup

Optional first step: run check-requirements.ps1 (Windows) or check-requirements.sh (macOS/Linux) from the repo root to verify Python 3.8+ and Git and to see whether the Claude Code CLI is on PATH. The scripts then point you to the matching platform guide below.

Platform	Guide
Windows	Python Launcher (py), Windows Terminal, PowerShell
macOS	python3, Terminal.app or iTerm2
Linux	python3, any truecolor terminal

Features

• Compact — every critical metric fits on one dashboard screen, no tabs, no wasted space. Detail modals (token stats, agents, legend, cost) scroll — mouse wheel or keyboard — when they outgrow the terminal, with a pinned header and a scroll-position hint.
• Stdlib only — Python 3.8+. No pip install, no venv, no node_modules.
• Simple setup — clone the repo, add one block to ~/.claude/settings.json, launch the monitor. See platform setup guide.
• Official stdin JSON — reads Claude Code's statusLine JSON protocol via stdin: the values Claude Code reports, in real time. Desktop app sessions, which have no statusline, are estimated from their transcripts.
• Two-tier architecture — statusline.py (single-line status bar, triggered per Claude Code event) + monitor.py (fullscreen TUI, polls temp files independently).
• Temp file IPC — atomic JSON snapshots + JSONL history in $TMPDIR/claude-aio-monitor/. No sockets, no databases, no shared memory. Works across terminal sessions.
• Progress bars with configurable ranges — BRN (default 0-10.0 $/min), CTR (default 0-10.0 %/min), CST (default 0-$1000) plus standard 0-100% bars for APR, CHR, CTX, 5HL, FBL, 7DL. Ceilings tunable via env vars (CC_MON_BRN_MAX, CC_MON_CTR_MAX, CC_MON_CST_MAX). Statusline 5HL/FBL/7DL segments also show a reset countdown (→ 2h 15m, → 6d 12h) alongside the percentage.
• Smart warnings — header alerts when context fills in < 30 min or burn rate exceeds threshold.
• Cross-session cost tracking — TDY (today) and WEK (rolling 7-day) aggregate cost across all active Claude Code sessions.
• Token usage stats — press t for a per-model token breakdown (In / Out / Calls, plus Cache Read and Cache Write rows when non-zero), session count, active days, streaks, longest session, and most active day. Reads ~/.claude/projects/ transcripts. Filterable by All Time / Last 7 Days / Last 30 Days. Initial loading and period changes run in the background so the modal remains responsive. Model bars and daily peak (PEAK) count all token types: input + output + cache_read + cache_write.
• Update manager — press u to check for updates. Shows current vs remote version, new commits, changelog preview, and safety warnings. Press a to apply.

_{Token stats (t) — per-model token breakdown, sessions, streaks and peak-day.}

_{Cost breakdown (c) — last-request and whole-session cost, cache savings, and burn rate over time.}

_{Anthropic Pulse (p) — backend stability score, active incidents, and API latency.}

_{Update manager (u) — current vs remote version, changelog preview, and one-key apply.}

• Cross-platform — Windows (Terminal, PowerShell, Git Bash), macOS (Terminal, iTerm2), Linux. CI-tested: Ubuntu (Python 3.8, 3.10, 3.11, 3.12, 3.13, 3.14), Windows (Python 3.12), macOS (Python 3.12).
• Nord truecolor palette — ANSI 24-bit color with semantic grouping: green = performance, cyan = context, yellow = rate limits, orange = cost/finance, red = critical. Note: the Nord red/green pair is not colorblind-safe (similar luminance for deuteranopia/protanopia); every metric also carries a text label + numeric value, so color is redundant context only.
• Responsive layout — statusline drops right segments for narrow terminals. Dashboard compresses sections automatically.
• Multi-session — auto-detects CLI sessions via temp files and desktop app sessions via their transcripts. Scrolling two-section picker (CLI / desktop app) for multiple sessions. Press s to switch anytime. The picker and dashboard header show Claude Code's auto-generated session title (ai-title records in the transcript) when no explicit session_name is set; falls back to the UUID prefix if neither is available. On the dashboard, an auto-generated ai-title label is capped at 24 characters; the picker shows the full title.
• Stale detection — sessions idle > 30 minutes get dimmed metrics with last known values preserved. See Session States for a visual example.
• Auto-purge — dead session files older than 48 hours are automatically cleaned up from the temp directory.
• Release check (RLS) — background version check against GitHub once per hour. Shows green "up to date" or blinking red "update available" in the dashboard. Disable with CC_AIO_MON_NO_UPDATE_CHECK=1.
• Menu modal — press m to open the navigation hub. Quick access to all features: refresh, session switch, legend, token stats, agents fan-out, cost breakdown, Anthropic Pulse, update manager.
• Agents fan-out — press a for a live view of the subagents / Workflow agents spawned by the watched session: active/total count, summed token usage, and a per-agent list (id, tokens, last tool) sorted by recency, refreshed while the modal is open. Press f to toggle an active-only filter that hides idle agents (a non-destructive "clear board" — nothing on disk is touched). Reads each agent's transcript under ~/.claude/projects/<proj>/<session>/subagents/agent-*.jsonl (lazy, TTL-cached, containment-checked). When a Task or Workflow fans out across dozens of agents, you can see it happen in real time.

_{Agents fan-out (a) — live subagent / Workflow view: active/total, summed tokens, per-agent tokens and last tool.}

- **Cost breakdown** — press `c` for two scopes: **LAST REQUEST (est.)** shows last-message token costs from `current_usage`; **SESSION BREAKDOWN (est.)** aggregates the entire session from transcript JSONL with per-record model pricing and reconciliation against server-reported CST (warn tag if delta >15%). CST displays `0.00 $` for a reported zero and `n/a` for missing or invalid data. The detail explains missing usage or an unavailable transcript estimate, and shows the estimate total even without a reported CST. Also shows cache savings percentage and burn rate over time bars. When non-zero, **WSR / WFR** rows surface server-side tool calls (`web_search_requests` / `web_fetch_requests` from `usage.server_tool_use`) and **TIE / T5M** rows split cache-creation tokens between the 1-hour and 5-minute ephemeral TTLs. - **Anthropic Pulse** — press `p` for real-time Anthropic backend stability. Weighted score (0-100) from `status.claude.com` (indicator + incidents) + HTTPS probe on `api.anthropic.com/v1/messages` (TLS + HTTP latency). Rolling-median smoothed verdict (`SAFE TO CODE` / `DEGRADED` / `NOT SAFE TO CODE`). Per-model tagging of active incidents (opus/sonnet/haiku) — prefers `incidents[].components[]` array, falls back to regex on title. JSONL history in `$TMPDIR/claude-aio-monitor/pulse.jsonl` with hybrid cleanup (24h age cutoff on startup + runtime rotation at 1 MB). **Zero token cost, zero API key required.** - **Security hardened** — session ID regex validation (`[a-zA-Z0-9_-]{1,128}`) with Windows reserved-device-name rejection (`CON`/`PRN`/`AUX`/`NUL`/`COM0-9`/`LPT0-9`, case-insensitive), C0/C1 control character sanitization, atomic writes via `NamedTemporaryFile`, symlink/junction rejection on the temp data directory and `~/.claude/projects/`, transcript containment checks, and bounded reads for JSON, JSONL, transcripts, Pulse responses, and post-update source checks. - **Singleton lock** — only one interactive `py monitor.py` can run at a time; a second attempt exits with a clear error pointing at `$TMPDIR/claude-aio-monitor/monitor.lock`. The `--list` mode is exempt. - **Crash-log rotation** — `monitor-crash.log` rotates to `.log.1` at 1 MB so repeated crashes don't fill the disk. - **File-IPC schema versioning** — snapshots and history entries carry `_schema_version`; `monitor.load_state()` refuses snapshots newer than it understands. See [docs/FILE-IPC-CONTRACT.md](docs/FILE-IPC-CONTRACT.md).

Session States

The dashboard distinguishes active and inactive sessions. An active session receives fresh JSON snapshots from statusline.py on every Claude Code event. When no update arrives for more than 30 minutes, monitor.py marks the session as stale: the header switches to Session Inactive, the time-since-last-update is shown in parentheses (e.g. (617m)), and every metric is rendered in the dimmed variant of its color. Last known values are preserved — nothing is zeroed out — so you can still see where the session left off (context used, cost accumulated, rate-limit buckets, burn rate at time of freeze).

_{Session picker (s) — CLI and desktop app sessions in two sections; move the cursor and press Enter (see Session Picker).}

Press r to force a refresh (resets the stale timer if new data has arrived), or s to switch to a different session from the picker. If the session has truly ended and you want it out of the picker, delete its JSON/JSONL pair from $TMPDIR/claude-aio-monitor/.

Metrics at a Glance

Metric	What it shows	Range	Where
APR	API time / total session time	0-100%	dashboard
DUR	Session duration (sub-stat of APR)	—	dashboard
CHR	Cache read tokens / total cache	0-100%	dashboard
CTX	Context window usage	0-100%	statusline + dashboard
CCH	Prompt-cache countdown — time until the cached conversation goes cold (shown from 50 min down), then cold + the tokens the next message re-caches; Claude Code v2.1.251+ (see below)	—	statusline
5HL	5-hour rate limit usage + reset countdown (→ 2h 15m)	0-100%	statusline + dashboard
FBL	Fable weekly pool usage + reset countdown — shown only on plans that have the pool; read from Claude Code's cached /usage data (see below)	0-100%	statusline + dashboard
7DL	7-day rate limit usage + reset countdown (→ 6d 12h)	0-100%	statusline + dashboard
BRN	Cost burn rate	0-10.0 $/min (env: CC_MON_BRN_MAX)	statusline + dashboard
CTR	Context consumption rate	0-10.0 %/min (env: CC_MON_CTR_MAX)	dashboard
CST	Session cost	0-$1000 (env: CC_MON_CST_MAX)	statusline + dashboard
TDY	Today's cost (all sessions)	—	dashboard
WEK	Rolling 7-day cost (all sessions)	—	dashboard
LNS	Lines added / removed	—	dashboard
NOW	Current clock time	HH:MM:SS	dashboard
UPD	Last data update age	—	dashboard
RLS	Release status (up to date / update available)	—	dashboard
SES	Total sessions	—	usage stats modal
DAY	Active days	—	usage stats modal
STK	Streak (current/best)	—	usage stats modal
LSS	Longest session	—	usage stats modal
PEAK	Most active day (peak tokens)	—	usage stats modal
WSR	Web search requests (server-side tool use)	—	cost breakdown modal
WFR	Web fetch requests (server-side tool use)	—	cost breakdown modal
TIE	Cache-creation tokens, 1-hour ephemeral TTL	—	cost breakdown modal
T5M	Cache-creation tokens, 5-minute ephemeral TTL	—	cost breakdown modal

Usage

Statusline

Runs automatically on each Claude Code status update via stdin JSON. Outputs a single ANSI-colored line: Model │ CTX │ CCH │ 5HL → countdown │ FBL → countdown │ 7DL → countdown │ CST │ BRN. Trailing segments drop when terminal is narrow (FBL drops before 7DL; CCH drops after BRN and CST, before FBL). No background padding — CC notifications share the right side of the row. APR and CHR live only in the dashboard where the horizontal space isn't constrained.

FBL — Fable weekly pool. The Claude Code statusline protocol supplies the 5-hour and 7-day limits (plus spend_limit) but no per-model weekly pool, so FBL is read from Claude Code's own, undocumented usage cache (cachedUsageUtilization in ~/.claude.json, or $CLAUDE_CONFIG_DIR/.claude.json) — the data /usage shows. OAuth credentials are never read. The segment appears only when that cache holds a valid Fable bucket for the logged-in account; a copy older than 30 minutes (or twice the refresh interval, when that is longer) is shown dimmed with ~, and one older than a day or past its reset is hidden. The internal, version-dependent refresher is best effort: it sends a get_usage control request without a prompt to a detached claude -p, with hooks disabled and session persistence disabled. It starts only from an existing valid Fable cache. If the cache is missing or you switch accounts, run /usage once to bootstrap it. Set CC_AIO_MON_FABLE_REFRESH_SEC=0 to keep FBL read-only — see CONFIGURATION.md.

CCH — prompt-cache countdown. Read from the documented prompt_cache object (prompt cache fields, Claude Code v2.1.251+). After an idle gap longer than the cache TTL (1 h or 5 min), the next message writes the whole conversation prefix to the cache again; CCH shows how close that is. It stays hidden while more than 50 min remain, counts down in green (CCH 34m), turns yellow below 20 % of the TTL (12 min on 1h, 60 s on 5m) and red once the cache is cold: CCH cold 82.0k, where the number is recache_tokens_if_cold. No segment before the first response, on older Claude Code, or when the provider reports no prompt caching (caching_observed false).

Claude Code re-runs the statusline when a warm cache reaches expires_at, so cold appears on its own. Between events the countdown stands still; to make it move while you are idle, add refreshInterval (seconds) to the statusLine block in settings.json:

"statusLine": {
  "type": "command",
  "command": "...",
  "refreshInterval": 60
}

Trade-off: every refresh is a full statusline run, including the IPC write. An idle session's snapshot therefore stays fresh, so the dashboard does not switch to "Session Inactive" while Claude Code is open, and the session history gains one entry per refresh (BRN averages over that idle time). Leave refreshInterval unset if you rely on the inactive marker.

Token statistics label Fable 5 and 5.1, including dated and context-suffixed IDs, as FBL; the short fable alias is also recognized. Major-only IDs such as claude-opus-5 retain their family label. This changes labels only, not pricing.

Dashboard

On macOS/Linux use python3. On Windows use py.

python3 monitor.py              # auto-detect session
python3 monitor.py --session ID # specific session
python3 monitor.py --list       # list active sessions
python3 monitor.py --refresh 1000  # custom refresh interval (ms, default 500)

Keyboard Shortcuts

Key	Action	Context
q	Quit	dashboard
m	Menu (navigation hub)	dashboard
r	Force refresh (resets stale timer)	dashboard
s	Switch session (picker)	dashboard
t	Token usage stats (per-model breakdown)	dashboard
c	Cost breakdown (token costs, cache savings, burn rate over time)	dashboard
u	Update manager (version check, changelog)	dashboard
a	Agents fan-out (live subagent / Workflow view for the watched session)	dashboard
a	Apply update (fetches + runs git pull --ff-only)	inside update modal only
p	Anthropic Pulse (backend stability modal)	dashboard
l	Toggle legend overlay	dashboard
1 / 2 / 3	Switch period (all / 7d / 30d)	inside token-stats modal only
f	Toggle active-only filter (hide idle agents)	inside agents modal only
↑ ↓ / j k / PgUp PgDn / Home End / mouse wheel	Scroll the open modal (content taller than the terminal)	inside any modal
↑ ↓ / j k / PgUp PgDn / Home End / mouse wheel	Move the cursor	session picker only
Enter	Open the session under the cursor	session picker only

Session Picker

Shown on launch when more than one session exists. It has two sections:

• CLI SESSIONS — sessions with a statusline snapshot (Claude Code in a terminal). All metrics.
• DESKTOP APP SESSIONS — sessions found only as a transcript in ~/.claude/projects/, touched in the last 48 hours. See Desktop app sessions.

Every session is listed; the list scrolls to keep the cursor visible, with the header and key hints pinned. Active sessions come first in each section. Move with the arrows, j / k, Page keys or the mouse wheel and open with Enter. Auto-connects only when exactly one session exists and it is active. Press s to return to the picker from dashboard or menu; the cursor starts on the session you left. Each row shows the session label (full ai-title or desktop title, otherwise UUID prefix), the model code and a live / stale tag; desktop rows also show the entrypoint tag (desk for the desktop app).

Desktop app sessions

The Claude desktop app runs Claude Code without its terminal interface, so the statusLine command never runs and no snapshot reaches the temp directory. The monitor reads these sessions from their transcript instead and marks them desktop app, estimated (est. in a narrow terminal, where a long session name is cut with … so the tags stay visible):

• CST, BRN — estimated from per-model token prices, counting each request once. TDY / WEK still sum CLI sessions only.
• CTX — from the last request's input tokens, against the model's context window (1M for current models, 200K for Haiku 4.5 and older); set CC_MON_DESKTOP_CTX to override.
• Cost breakdown (c) — the same per-request estimate as CST. Each request is counted once (Claude Code repeats its usage on every content-block record) and 1-hour cache writes are priced at 2× input.
• APR, LNS — n/a; the transcript records no API time or line counts.
• 5HL / 7DL — shown only while a CLI session reports them (the limits are per account); otherwise n/a.

python3 monitor.py --list prints desktop sessions after CLI sessions with their entrypoint tag.

How It Works

Claude Code ──stdin JSON──> statusline.py ──> terminal (single-line ANSI status bar)
                                 |
                                 v
                         $TMPDIR/claude-aio-monitor/        (macOS/Linux: /tmp | Windows: %TEMP%)
                         ├── {session_id}.json    (atomic snapshot)
                         └── {session_id}.jsonl   (append-only history)
                                 |
                                 v
                           monitor.py ──> terminal (fullscreen TUI)

Both scripts import shared.py for shared BRN/CTR calculation.

1. Claude Code emits JSON telemetry to statusline.py via stdin on session start or resume, after each assistant message, a completed /compact, a permission mode change or vim mode toggle, at a rate-limit reset or prompt-cache expiry, and every refreshInterval seconds if set (300ms debounce). The Claude desktop app runs Claude Code without a terminal and never runs the statusline; monitor.py reads those sessions from ~/.claude/projects/ transcripts.
2. statusline.py parses JSON, renders single-line ANSI status bar (model, context, prompt-cache countdown, rate limits with reset countdown, cost, burn rate), writes atomic snapshot (.json) + appends to history (.jsonl).
3. monitor.py polls temp directory (data files refresh every 500 ms; UI tick 50 ms for keyboard responsiveness), reads snapshots + history, renders fullscreen TUI with progress bars and computed metrics.
4. shared.py provides calc_rates() — computes BRN ($/min) and CTR (%/min) from JSONL history timestamps.

Color Thresholds

Range	Color	Meaning
< 50%	Green	Healthy
50-79%	Yellow	Approaching limits
>= 80%	Red	Critical

Exception: 5HL/FBL/7DL labels use yellow as base color (even below 50%) to visually distinguish rate limits from performance metrics. 5HL and FBL turn dim with ~ before the percentage once the value shown is older than 30 minutes (5HL: a last known value shown because the current event carried no rate limits). CCH uses its own time-based scale: green countdown, yellow below 20 % of the cache TTL, red once the cache is cold.

Configuration

Variable	Default	Scope	Description
CLAUDE_STATUS_WARN	50	statusline + dashboard	Yellow threshold (%)
CLAUDE_STATUS_CRIT	80	statusline + dashboard	Red threshold (%)
CLAUDE_WARN_BRN	3.0	dashboard	Burn rate warning threshold ($/min)
CC_MON_BRN_MAX	10.0	dashboard	Burn rate bar ceiling ($/min). Set higher if your bar pins (24/7 Opus API).
CC_MON_CST_MAX	1000.0	dashboard	Cost bar ceiling ($ per session). Raise for long-running API sessions.
CC_MON_CTR_MAX	10.0	dashboard	Context change rate ceiling (%/min).
CC_MON_DESKTOP_CTX	0 (model window)	dashboard	Context-window size (tokens) for desktop app sessions.
CC_AIO_MON_FABLE_REFRESH_SEC	300	statusline	FBL usage-cache refresh interval; 0 keeps FBL read-only
CC_AIO_MON_REMOTE	(unset)	dashboard + updater	Accepted origin URL for self-update (e.g. your fork)
CLAUDE_CONFIG_DIR	(unset)	all	Claude Code config directory (transcripts and .claude.json); defaults to ~/.claude and ~
CC_AIO_MON_NO_UPDATE_CHECK	(unset)	dashboard	Set to 1 to disable background release check
CC_AIO_MON_NO_PULSE	(unset)	dashboard	Set to 1 to disable background Anthropic Pulse worker (no outbound network)

Full reference with types and edge cases: docs/CONFIGURATION.md.

Env-var prefix convention: CLAUDE_* variables are shared with broader Claude tooling (warn/crit thresholds, burn warn); CC_AIO_MON_* are project-wide toggles (opt-out switches for background worker threads); CC_MON_* are dashboard-specific limit overrides for bar ceilings.

Bars are designed for typical heavy usage (24/7 API Opus). If your bar pins at 100%, raise the corresponding env var. Defaults are generous — most users should never see them pinned.

export CLAUDE_STATUS_WARN=60
export CLAUDE_STATUS_CRIT=90

IPC and security details

IPC Details

• State files: atomic write via NamedTemporaryFile + os.replace() (no partial reads)
• History: append-only JSONL, written only after snapshot succeeds — keeps .json and .jsonl in sync
• Auto-trimmed when file exceeds 1 MB (keeps last 1000 entries)
• Stale .tmp files older than 60 seconds cleaned up automatically
• Dead sessions older than 48 hours auto-purged (.json + .jsonl pair deleted)
• Session detection: files older than 30 minutes marked as stale — metrics dimmed, Session Inactive (Nm) header shown with minutes-since-last-update, last known values preserved (see Session States)

Security

Measure	Protection
Session ID validation	Strict regex [a-zA-Z0-9_-]{1,128} prevents path traversal; Windows reserved device names (CON/PRN/AUX/NUL/COM0-9/LPT0-9) rejected case-insensitively
Input sanitization	C0/C1 control characters + bidi overrides stripped before terminal output
File size limits	JSON capped at 1 MB, JSONL at 2 MB (10 MB for cross-session aggregation) — oversized files skipped
Atomic writes	Unpredictable temp filenames prevent symlink attacks
Directory validation	lstat() + S_ISDIR verification — rejects symlinks, NTFS junctions, and defends against TOCTOU races
TOCTOU prevention	Single open + bounded read instead of separate stat + read
Directory permissions	Temp directory created with 0o700 where supported
CJK-aware truncation	unicodedata.east_asian_width() prevents terminal overflow from fullwidth characters
Thread safety	_update_result protected by threading.Lock — safe across Python implementations
Graceful shutdown	SIGTERM handler + atexit restore terminal state
Render isolation	Corrupted data caught per-frame — TUI never crashes

Requirements

• Python 3.8+
  • macOS / Linux: usually pre-installed (python3 --version to verify)
  • Windows: must be installed separately (not bundled with Windows)
  • No pip packages needed — stdlib only. See platform setup guide.
• Claude Code CLI with statusline support — for the statusline and full metrics. Claude desktop app sessions are shown without it (estimated from transcripts).
• Truecolor terminal — Windows Terminal, iTerm2, Alacritty, Kitty, or any terminal supporting ANSI 24-bit color
• 80 columns minimum recommended

Known Limitations

• Refresh between events — the statusline runs only on Claude Code events (see How It Works), so between them the dashboard shows the last reported values. Set refreshInterval in the statusLine block to refresh on a timer.
• Desktop app sessions are estimates — see Desktop app sessions.
• Pricing drift — model prices are hardcoded snapshots of Anthropic's published rates at release time. If Anthropic adjusts pricing, cost breakdown numbers drift until the next release. Cost breakdown stores explicit per-model per-1M-token rates; cache-read rates are roughly 0.1× and 5-minute cache writes 1.25× the model's input rate, 1-hour cache writes 2×. Current priced families: Fable (5 / 5.1 / 5.2), Mythos (5 / 5.1 / 5.2), Opus (4.1 / 4.5 / 4.6 / 4.7 / 4.8 / 5 / 5.5), Sonnet (4.5 / 4.6 / 5 / 5.5), Haiku (3.5 / 4.5 / 5.5). Cache-read rates are lower on Fable and Mythos 5.1 / 5.2 (0.025×), Opus 5.5 (0.05×), and Sonnet 5.5 (0.05×). Haiku 5.5 bills a prompt above 100K tokens at 5× its base rates. The Sonnet 5 and Haiku 5.5 cache rates assume the standard multipliers.
• Local timezone everywhere — all timestamps (header clock, daily aggregation, rollback tags like pre-update-YYYYMMDD-HHMMSS, pulse JSONL entries) use the machine's local timezone, not UTC. If you ship temp-dir logs to a maintainer in a different zone, clock labels will not line up — report the date plus your TZ offset when filing an issue.

Troubleshooting

Platform-specific troubleshooting is in the setup guides:

• Windows — Troubleshooting
• macOS — Troubleshooting
• Linux — Troubleshooting

Updating

Recommended: use the bundled update.py script — it safely checks for updates, previews changes, and applies them:

# macOS / Linux
cd ~/.cc-aio-mon
python3 update.py             # check only (no changes)
python3 update.py --apply     # check + git pull

# Windows (PowerShell)
cd "$env:USERPROFILE\.cc-aio-mon"
py update.py                  # check only (no changes)
py update.py --apply          # check + git pull

The script is read-only by default — it shows you what would change (version, new commits, CHANGELOG preview) and only pulls when you add --apply. It aborts safely if your working tree is dirty, you're on a different branch, or history has diverged.

From inside the monitor: you can also update without leaving the TUI — press u to open the update manager (current vs remote version, new commits, changelog preview, safety warnings), then a to apply. It runs the same git pull --ff-only + post-pull syntax check as update.py --apply; restart the monitor afterwards to load the new code.

Rollback safety: before each --apply pull, a pre-update-YYYYMMDD-HHMMSS git tag is created automatically. If anything breaks after the update, recover with:

git reset --hard pre-update-YYYYMMDD-HHMMSS

(The exact tag name is printed during update.) Both update paths record the original commit before pulling. Failed Git checks block the pull; missing, unreadable or syntactically invalid runtime files fail verification. The CLI exits with code 1 and the TUI displays an error with the recovery commit. “Update complete” is shown only after successful verification. Recovery is manual; no reset is performed automatically.

Manual fallback — if you prefer plain git:

# macOS / Linux
git -C ~/.cc-aio-mon pull

# Windows (PowerShell)
git -C "$env:USERPROFILE\.cc-aio-mon" pull

The path in settings.json does not change between versions — git pull updates the project source, and Claude Code picks up the new code on the next session. No changes to settings.json needed.

After updating, restart Claude Code to pick up the new statusline. Optionally re-run check-requirements.ps1 / check-requirements.sh from the repo directory to verify system requirements still pass.

Documentation

• docs/ARCHITECTURE.md — contributor-oriented architecture overview
• docs/FILE-IPC-CONTRACT.md — schema of the two-process file IPC
• docs/RELEASE.md — release process checklist
• .github/SECURITY.md — security policy

Contributing

Contributions welcome. Keep it stdlib only, ship shared.py alongside entry scripts, test on Windows and Unix. Before submitting, run the test suite and the compile check (python3 on macOS/Linux, py on Windows):

python3 tests.py
python3 -c "import py_compile, shared; [py_compile.compile(f, doraise=True) for f in shared.PY_FILES]"

Tests live in tests/ (per-module split as of v1.12.0); python3 tests.py runs them all via unittest discover. See CONTRIBUTING.md for full guidelines.

The file list comes from shared.PY_FILES (single source of truth since v1.10.2). update.py's post-pull syntax check uses the same tuple, so a new runtime module added to the project only needs to be appended to PY_FILES in one place.

Open an issue first for anything non-trivial so the approach can be discussed before work begins. See CONTRIBUTING.md for full guidelines.

License

MIT License. See LICENSE for details.

Legal & Affiliation

This project is an independent, community-maintained tool. It is not affiliated with, endorsed by, sponsored by, or officially supported by Anthropic, PBC.

"Anthropic", "Claude", and "Claude Code" are trademarks of Anthropic, PBC — used here for descriptive purposes only (nominative fair use). No claim of partnership, endorsement, or association is made or implied.

All source code is original work by the project contributors. No code was copied, decompiled, or derived from Anthropic's proprietary codebase. The tool interacts with Anthropic products through publicly documented extension points (Claude Code statusLine hook, status.claude.com public Statuspage API) and the user's own local files (~/.claude/projects/ transcripts, ~/.claude.json). One optional feature goes further: the FBL refresher reads Claude Code's undocumented cachedUsageUtilization cache and asks the user's own claude CLI for an update through its experimental get_usage control request (disable with CC_AIO_MON_FABLE_REFRESH_SEC=0). No reverse engineering, traffic interception, authentication bypass, or rate-limit circumvention was performed.

This tool does not modify, patch, or alter Claude Code or any Anthropic service — it observes data the user's own Claude Code installation writes or emits.

See NOTICE for full provenance, third-party references, and trademark attribution.

---

Changelog