From b62d8397af4b69c6837b3086574a507f8fe530eb Mon Sep 17 00:00:00 2001 From: aguil Date: Sun, 9 Aug 2026 09:24:39 -0600 Subject: [PATCH] docs(ai-cli): note that green leaves no context breadcrumb The statusline only persists a breadcrumb while context is yellow or red. At green it writes nothing, and drops any existing file when usage falls back below the yellow threshold -- absence is how the green state is represented, and the Stop hook short-circuits on a missing file. The doc described where breadcrumbs live without saying when they exist, so a missing file during a normal green session reads as a broken cache. Also records that an unchanged yellow/red refresh skips the rewrite, since that is the other reason the file's mtime can look stale. Follow-up to #125, which introduced the write-skipping behavior. --- docs/ai-cli-context-statusline.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/ai-cli-context-statusline.md b/docs/ai-cli-context-statusline.md index c720714..d7fee27 100644 --- a/docs/ai-cli-context-statusline.md +++ b/docs/ai-cli-context-statusline.md @@ -22,7 +22,12 @@ BEL once per level per session. Usage dropping back below yellow clears the latch. Session breadcrumbs live under -`${XDG_CACHE_HOME:-~/.cache}/ai-context-alerts/.json`. +`${XDG_CACHE_HOME:-~/.cache}/ai-context-alerts/.json`, and exist +**only while a session is yellow or red**. Green writes nothing and deletes any +existing file, so a missing breadcrumb is the normal green state rather than a +broken cache — the Stop hook short-circuits on it. While yellow or red, a +refresh that changes neither the level nor the whole-percent usage skips the +rewrite, so the file's mtime can lag the statusline by design. ### Claude Code Stop hook