Repository navigation
feat(examples): claude-loaded, a session context inspector - #8
Merged
Merged
Conversation
added 2 commits
August 9, 2026 10:13
Adds examples/claude-loaded/ — one bash script that lists the files loaded into a Claude Code session's context (the CLAUDE.md chain, the auto-memory index, and every file a Read pulled in) with a per-file token estimate, plus a --budget mode that checks only the re-sent-every-turn set against a ceiling and needs no session or transcript, so it can run from a SessionStart hook. It does not import claude_batch_runner. It sits in examples/ as a peer of health-check/ and workflows/ because a campaign inherits whatever CLAUDE.md and auto-memory bloat a session already carries and pays for it once per unit. The new README documents three things the script reports badly, all verified against a live run rather than assumed: every "read" row carries the same whole-session size instead of a per-file one, token counts are a 3.6-chars-per-token estimate, and the "cost per turn" its --help advertises is never printed. Script is byte-identical to its source; only docs are authored here.
…t, format STARTED The per-file "read" accounting passed --arg p "$path" into a jq filter that never referenced $p, so it summed every tool_result in the transcript once per path. Every read row printed the same number -- the whole session's tool output -- and their sum overshot the real total, clamping "Everything else" to 0. A tool_result carries only its tool_use_id, so the path has to come from the matching tool_use in the preceding assistant message: pass 1 maps id -> path for Read calls, pass 2 maps id -> result size, awk joins them and keeps the largest result per path. It also drops the per-path re-scan of the whole transcript, so a 4.3MB transcript now reports in 0.4s. fmt_cost was defined and never called, so COST_RATE_USD_M changed no output while --help advertised "steady-state cost per turn". Wired it up rather than deleting it: the whole window is re-sent as a cache read every turn, so TOTAL at the cache-read rate is a well-defined per-turn floor, and the env var is already documented. The rate is now validated, because it is interpolated into an awk program and a non-numeric value is injected awk code. --all printed startedAt raw: the harness writes epoch milliseconds and cut -dT is a no-op on a number. Both shapes are handled now. README and CHANGELOG drop the three known-issue entries and keep the honest residue: the estimate is 3.6 chars/token, a read row measures the tool result rather than the file on disk, and the cost line is an estimate at one rate.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
claude-loadedunderexamples/, alongsidehealth-check,agentsandworkflows. It reports which files are loaded into a Claude Code session's context with per-file token counts, plus a budget mode (--budget N, exit 1 on breach) and--prune.It lands here rather than in its own repository because its prerequisite is Claude Code itself — the same prerequisite this repo already has — and this repo already hosts adjacent Claude Code tooling under
examples/. One 540-line script does not warrant its own README, LICENSE, CI and release process.Diff cap
793 insertions / 2 deletions, over the 300 cap, pushed with a documented
DIFF_CAP_OVERRIDE=1and explicit owner approval. 540 of those lines are the tool imported byte-identical with zero deletions; roughly 253 are authored (README, changelog, index wiring, and the fixes below). There is no honest trim: the overage is the script, and splitting a single executable across PRs is not a real option.Three defects fixed before this shipped
Found by running the tool, not by reading it. Publishing a tool whose headline feature is broken, and then listing it as a working thing, is the failure this project's fact gates exist to prevent — so they were fixed first rather than documented as known issues.
jqinvocation passed--arg p "$path"and never referenced$pin the filter, so it summed everytool_resultin the transcript once per file. Symptom: ten rows all reporting an identical19.0K, totalling 189.9K against a real 128.4K, which clamped "Everything else" to 0. Replaced with a two-passjq+awkjoin keyed ontool_use_id(verified thattool_use.idcorrelates 1:1 withtool_result.tool_use_idin a real transcript before relying on it). Same transcript now reports 9.1K static + 9.1K read + 110.2K other = 128.4K, and the rescan loop is gone — a 4.3 MB transcript reports in 0.39s.fmt_costwas dead code while--helpadvertised "steady-state cost per turn". Wired up rather than deleted, sinceCOST_RATE_USD_Mis already a documented interface. Wiring it up exposed an awk injection —$RATEwas interpolated intoawk "BEGIN{...}", soCOST_RATE_USD_M='1;system("...")'would have executed. Unreachable while the function was dead; guarded in the same commit.--all's STARTED column printed raw epoch-millis —cut -dT -f2is a no-op on a numericstartedAt. Now handles ISO-with-millis, ISO-plain, epoch-millis and epoch-seconds.Test plan
pip install -e ".[dev]"),python -m pytest -q→ 75 passedbash -nclean--help,--budgetunder and over (exit 0 / exit 1),--prune,--json,--all, unknown arg (exit 1), unresolvable session, empty transcript