Skip to content

feat: opt-in per-session context export - #16

Merged
vtmocanu merged 2 commits into
mainfrom
feat/ctx-export
Oct 13, 2026
Merged

vtmocanu merged 2 commits into
mainfrom
feat/ctx-export

Conversation

@vtmocanu

Copy link
Copy Markdown
Owner

Summary

Opt-in context export for other local tools (first consumer: a coordinator skill that reads each session's context fill).

  • STATUSLINE_CTX_EXPORT=1 (default off): every render writes one JSON line to ${XDG_STATE_HOME:-~/.local/state}/cc-statusline/ctx/<session_id>.json (dir mode 700, file mode 600, temp file plus atomic rename). Override the directory with CC_STATUSLINE_CTX_EXPORT_DIR.
  • Schema v1: v, session_id, used_pct (as displayed), used_tokens, context_window_size, source (native, tokens, held, unknown), stale, ts (publication time), model_id, effective_model_id, cc_version. source is computed before any display default or clamp, so a 0% / 200k fallback or a GPT held value is never presented as a fresh measurement. Documented in the README with the consumer contract (exact only for native/tokens and 0 <= now - ts < 180; ignore unknown fields).
  • Best-effort GC: at most about once a day (a .gc epoch stamp), a foreground sweep deletes records not rewritten for at least seven days and stale temporaries; the sweeping session publishes its own record first and never sweeps it.
  • Display output is unchanged with the export on or off.

Design notes

  • Synchronous local write (one subshell under umask 077, printf, mv), failures silent and the previous record kept. Measured on macOS: about 5 ms per render; a sweep over 300 files about 10 ms.
  • Strings are charset-gated before printf, so no JSON escaping is needed; a value failing its gate is "" or null.
  • Accepted edge: a record refreshed at the exact instant of a sweep can be deleted; that session's next render rewrites it.

Validation

  • task ci green locally in both locales (1266 render, 75 fetch, 3 installer tests).
  • New tests: off by default, exact schema, modes, ts advance, relative XDG_STATE_HOME, unknown/malformed context shapes, gated strings, unsafe session ids, a file in place of the directory, failed publication keeps the old record, a parallel-writer torn-read race, the GPT hold path, and the GC sweep, throttle, future/malformed stamps and symlinks.
  • Design and code reviewed by a Codex peer (APPROVE at 639e354).

🤖 Generated with Claude Code

STATUSLINE_CTX_EXPORT=1 makes each render write one private JSON record
per session to ${XDG_STATE_HOME:-~/.local/state}/cc-statusline/ctx/<sid>.json
so other local tools (a coordinator skill) can read a session's context
fill without parsing transcripts.

The record carries the displayed used_pct plus a source field computed in
jq before any bash default or clamp (native, tokens, held, unknown), so a
consumer never mistakes the 0% / 200k display fallback or a GPT held value
for a fresh measurement. used_tokens and context_window_size are null when
not measured. ts is publication time and advances on idle redraws.

Writes are synchronous and local: one subshell under umask 077, printf to
a temp file, atomic mv; every failure is silent and keeps the previous
record. Measured on macOS: about 5 ms per render. A best-effort sweep,
throttled by a .gc stamp to about once a day, deletes records not
rewritten for at least seven days (about 10 ms over 300 files).

Tests cover off-by-default, schema, modes, ts advance, relative
XDG_STATE_HOME, unknown shapes, gated strings, unsafe session ids, a
file in place of the directory, failed publication, a torn-read race,
the GPT hold path, and the sweep and its throttle.
An empty, null, partial, negative, fractional or oversized current_usage,
or a fractional or oversized window size, was exported as a tokens
measurement although the displayed value was a default. Require the same
bounded-integer shape CTX_USAGE validates; anything else is unknown.
Display is unchanged.
@coderabbitai

coderabbitai Bot commented Oct 13, 2026

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 2a0d69b5-9592-4f78-b803-20b69ae4ac39
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@vtmocanu
vtmocanu merged commit 9818684 into main Oct 13, 2026
2 checks passed
@vtmocanu
vtmocanu deleted the feat/ctx-export branch October 13, 2026 07:25
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