Skip to content

docs(ai-cli): note that green leaves no context breadcrumb - #128

Merged
aguil merged 1 commit into
masterfrom
docs/statusline-breadcrumb-lifecycle
Aug 9, 2026
Merged

docs(ai-cli): note that green leaves no context breadcrumb#128
aguil merged 1 commit into
masterfrom
docs/statusline-breadcrumb-lifecycle

Conversation

@aguil

@aguil aguil commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Docs-only follow-up to #125.

docs/ai-cli-context-statusline.md said where session breadcrumbs live but not
when they exist. #125 changed that: the statusline now persists a breadcrumb
only while a session is yellow or red, so during a normal green session
~/.cache/ai-context-alerts/<session_id>.json is simply absent — which reads as
a broken cache if you go looking for it.

Adds the lifecycle to the existing paragraph:

  • Breadcrumbs exist only while yellow or red.
  • Green writes nothing and deletes any existing file; absence is the green
    state, and the Stop hook short-circuits on a missing file.
  • 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.

Each claim was checked against the merged code rather than from memory:

Claim Source
Green deletes, else writes nothing executable_ai-statusline green branch — rm -f "$state_path" guarded by prev_level != green
Hook short-circuits on absence executable_context-threshold-stop.sh:21[ ! -f "$state_path" ] && exit 0
Skip when level + pct unchanged the elif write gate comparing level / pct / new_ui_alerted
pct is whole-percent executable_ai-statusline:53cut -d. -f1

No behavior change. pre-commit --all-files and both Neovim suites pass;
prettier was clean on the first pass.

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.
@aguil
aguil merged commit 6744436 into master Aug 9, 2026
1 check passed
@aguil
aguil deleted the docs/statusline-breadcrumb-lifecycle branch August 9, 2026 15:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant