Repository navigation
Conversation
Long Claude Code sessions spend most of their tokens re-reading a large context on every request. Three commands address that; none needs a graph. - graphify usage: reads the Claude Code transcripts and reports tokens by model, day and project, context size per request, the heaviest sessions, a fixed-overhead estimate, tool-result size per tool and repeated reads, as text, JSON or a self-contained HTML report. - graphify token-guard: Claude Code hooks that cap large Bash output (full output saved to a file), state the context size when it passes a budget, decline one repeated read of an unchanged file, and show once a day what was kept out of context. install/uninstall/status manage the settings entries; savings prints the per-day ledger. Every hook fails open. - graphify handoff: writes graphify-out/HANDOFF.md from the transcript, git state and the graph, with no LLM call, so a fresh session can replace a bloated one. See docs/token-guard.md. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Annotate the test helpers and narrow one Optional in usage.py. No behaviour change. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
|
Thanks for the pull request, @cell3790. A maintainer will review it soon. Want to talk it through while it is in review? Come join us on our Discord server. For longer-form discussion there is also GitHub Discussions. A couple of things that speed up review: make sure the test suite passes on Python 3.11 and 3.13, and that the change keeps extraction deterministic. |
There was a problem hiding this comment.
Graphify code review 
Review completed · c69b41918bae
Warning
Merge confidence: 3/5 · Review before merging · 🟠 High impact
3 P2 bugs
The change adds CLI commands for Claude Code usage summaries, session handoff notes, and context-saving hooks.
Full summary
The change adds CLI commands for Claude Code usage summaries, session handoff notes, and context-saving hooks. The hooks track repeated reads and context size, cap large Bash output, and manage their settings entries.
Bugs (3)
P2 · Record a range in _hook_reread only after Read succeeds: a failed or blocked read can otherwise make the next attempt spuriously denied. Inspect source
Detailed review · checked against the code
A failed first read can make the next read get denied
If a Read is blocked or fails after the hook runs, the next attempt can be denied even though its contents never entered context.
Expected: Only content successfully returned by Read should count as already present in context.
Actually: The next request for the same unchanged range can be denied once as a repeat; a further retry is allowed.
The installed PreToolUse Read hook runs _hook_reread before the tool call. For an allowed request, it adds the requested range to the session record and writes that record before returning, without any later confirmation that Read succeeded. If that tool call then fails or is blocked, the range remains recorded. A subsequent request for the same range and unchanged file is considered covered and, because denied is still false, receives a deny response saying the content is already in context. The following retry is allowed because the denial sets denied=true. Thus a failed first read can cause one spurious denial on the next attempt.
-
Independent source review: The existing reread tests cover successful reads, expected repeat denial, and allowance after that denial; they do not simulate a Read failure after the hook records a range. No inspected guard or completion-result path removes coverage after a failed Read.
-
The incorrect denial requires a Read to be blocked or fail after this PreToolUse hook has recorded it.
-
Some lookups asked for files or lines that do not exist; the review was told and carried on.
-
Also reported as: A failed first read can make the retry look redundant
P2 · Restrict _own_subcommand to commands owned by Graphify: uninstall currently removes unrelated hooks that contain token-guard followed by a recognized subcommand. Inspect source
Detailed review · checked against the code
Uninstall can remove a user's unrelated token-guard hook
A custom hook command containing token-guard reread or another recognized subcommand can be removed when the user runs graphify token-guard uninstall.
Expected: Uninstall removes Graphify's hooks while preserving unrelated user hooks.
Actually: The matching hook entry is stripped regardless of which executable or wrapper owns the command.
_own_subcommand searches anywhere in a command string for token-guard followed by a recognized subcommand, without checking that it is Graphify's executable. _strip_own removes any matching hook entry. During uninstall, _cmd_install calls _apply with no wanted hooks, and _apply applies that stripping to existing settings. Thus a user hook such as my-wrapper token-guard reread is removed even though Graphify did not install it.
- Independent source review: Graphify's own installed hook commands contain
token-guardand a recognized subcommand, so they match and are removed as intended. But an unrelated wrapper command with the same text also matches; the inspected uninstall path has no executable-identity check to preserve it.
P2 · Reject ambiguous prefixes in find_transcript instead of selecting _newest(matches): the handoff can otherwise summarize a different session than intended. Inspect source
Detailed review · checked against the code
An ambiguous session prefix can select the wrong handoff
When --session matches multiple transcript filenames by prefix, the handoff silently summarizes the newest match, which may belong to a different session.
When --session is a non-exact prefix matching multiple transcript files in the same searched directory, find_transcript returns _newest(matches) without checking uniqueness. The CLI passes the selected transcript to build_handoff, which creates the handoff from it. Thus the handoff can summarize a different session than intended. Exact filename matches are checked first, but do not prevent this ambiguous-prefix fallback.
-
Independent source review: The exact-name lookup and tests for an exact session ID and a prefix matching only one file were inspected. They do not handle a prefix matching multiple files; no ambiguity check is present in the fallback.
-
Some lookups asked for files or lines that do not exist; the review was told and carried on.
What this review covered
- We didn't review 1 file that isn't source code, such as docs, config, images, or generated or third-party code.
- Some lookups asked for files or lines that do not exist; the review was told and carried on.
- One review pass used all of its turns for reading code, so it reported from what it had already read.
- 8 of 8 changed files inspected. This is scope, not a correctness guarantee.
Code graph and static checks · 975 functions depend on this change
Impact & health
Impact — 975 functions depend on the 503 functions this change touches.
Health — this change adds coupling hotspots:
- worse:
dispatch_command()— 8 callers, 159 callees - new:
analyze()— 12 callers, 12 callees - new:
main()— 19 callers, 5 callees - new:
scan_transcript()— 12 callers, 6 callees - new:
main()— 10 callers, 6 callees - new:
render_handoff()— 7 callers, 8 callees - new:
build_handoff()— 9 callers, 6 callees - new:
main()— 11 callers, 4 callees - …and 19 more — each is listed as a finding
Formal checks — 975 functions this change can affect weren't formally checked in this review. Formal checks are informational only.
Gate & verification
✅ PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.
Advisory (not blocking):
- verification_scope: 969 function(s) in the blast radius were not formally verified this run
Test selection
596 of 596 test file(s) selected (100%) via static blast radius.
Escalated to a full run for safety (
noncode-change,uncovered-code) — the selection is not trustworthy on its own (see below). CI should run the whole suite.
tests/pi.test.ts— full-run-safetytests/test_4874_jvm_resolution.py— full-run-safetytests/test_4909_reference_binding_scale.py— full-run-safetytests/test_4978_reconcile_cost.py— full-run-safetytests/test_4992_ts_import_types.py— full-run-safetytests/test_5072_splittable_under_cap_retry.py— full-run-safetytests/test_affected_cli.py— impact, full-run-safetytests/test_affected_defines.py— full-run-safetytests/test_affected_member_seed.py— full-run-safetytests/test_affected_overrides.py— full-run-safetytests/test_affected_path_file_node.py— full-run-safetytests/test_affected_seed_reference_forms.py— impact, full-run-safetytests/test_agents_platform.py— impact, full-run-safetytests/test_alias_folding.py— full-run-safetytests/test_analyze.py— full-run-safetytests/test_anthropic_custom_endpoint.py— full-run-safetytests/test_antigravity_install.py— full-run-safetytests/test_apm_fallback_version.py— full-run-safetytests/test_architecture_doc.py— full-run-safetytests/test_astro_extraction.py— full-run-safetytests/test_astro_import_ids.py— full-run-safetytests/test_atomic_canvas_export.py— full-run-safetytests/test_atomic_version_stamp.py— full-run-safetytests/test_atomic_writes.py— full-run-safetytests/test_backend_env_isolation.py— full-run-safetytests/test_backend_extras.py— full-run-safetytests/test_backend_opt_in.py— full-run-safetytests/test_benchmark.py— full-run-safetytests/test_benchmark_raw_graph.py— full-run-safetytests/test_benchmark_real_query.py— full-run-safetytests/test_binary_media_words.py— full-run-safetytests/test_blade_extractor.py— full-run-safetytests/test_build.py— full-run-safetytests/test_build_located_semantic_identity.py— full-run-safetytests/test_build_merge_dedup_scope.py— full-run-safetytests/test_build_merge_ghost_fold_4955.py— full-run-safetytests/test_build_merge_hyperedges_and_prune.py— full-run-safetytests/test_build_merge_shrink_guard.py— full-run-safetytests/test_builtin_global_type_refs.py— full-run-safetytests/test_c_include_resolution.py— full-run-safetytests/test_cache.py— full-run-safetytests/test_cache_long_paths.py— full-run-safetytests/test_cache_stale_import_target.py— full-run-safetytests/test_cache_windows_case_4925.py— full-run-safetytests/test_callflow_html.py— full-run-safetytests/test_cargo_introspect.py— full-run-safetytests/test_cargo_missing_manifest.py— full-run-safetytests/test_carried_hyperedge_remap.py— full-run-safetytests/test_case_only_decl_ids_4904.py— full-run-safetytests/test_case_sensitive_resolution.py— full-run-safety- … and 546 more
⚠️ non-code file(s) changed (docs/token-guard.md) → running the full suite for safety (a code graph can't see config/fixture/data deps)
⚠️ changed code file(s) with no mapped test (docs/token-guard.md) — a coverage gap or a missing link — running the full suite rather than only the selected tests
Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.
Risky patterns (advisory)
- medium
no-unbounded-fetchingraphify/tokenguard.py:116: unbounded read (no limit/bound): data = json.loads(sys.stdin.buffer.read().decode("utf-8", "replace")) - medium
no-unbounded-fetchingraphify/tokenguard.py:884: unbounded read (no limit/bound): raw = fh.read()
Docs that may be stale (advisory)
.github/PULL_REQUEST_TEMPLATE.md§ Graphify-specific checklist (lines 33-39): references changed symbolsrunARCHITECTURE.md§ Pipeline (lines 5-12): references changed symbolsanalyze,reportARCHITECTURE.md§ Module responsibilities (lines 13-41): references changed symbolsanalyze,reportARCHITECTURE.md§ Calling extract() from your own code (lines 42-65): references changed symbolssrcARCHITECTURE.md§ Testing (lines 338-415): references changed symbolsanalyze,kindBENCHMARKS.md§ Reproducing (lines 190-203): references changed symbolsrunCHANGELOG.md§ 0.9.112 (2026-11-17) (lines 5-29): references changed symbolsrunCHANGELOG.md§ 0.9.107 (2026-11-11) (lines 80-95): references changed symbolsrunCHANGELOG.md§ 0.9.106 (2026-11-10) (lines 96-114): references changed symbolslinesCHANGELOG.md§ 0.9.105 (2026-11-09) (lines 115-141): references changed symbolsfmt,git
…and 10 more.
Every flagged function
main()ingraphify/tokenguard.py:1034· 19 callers, 5 callees: 19 callers depend on it (afferent coupling)analyze()ingraphify/usage.py:140· 12 callers, 12 callees: fans out to 12 callees (efferent coupling); 12 callers depend on it (afferent coupling)scan_transcript()ingraphify/handoff.py:386· 12 callers, 6 callees: fans out to 6 callees (efferent coupling); 12 callers depend on it (afferent coupling)main()ingraphify/usage.py:826· 11 callers, 4 callees: 11 callers depend on it (afferent coupling)main()ingraphify/handoff.py:827· 10 callers, 6 callees: fans out to 6 callees (efferent coupling); 10 callers depend on it (afferent coupling)build_handoff()ingraphify/handoff.py:795· 9 callers, 6 callees: fans out to 6 callees (efferent coupling); 9 callers depend on it (afferent coupling)dispatch_command()ingraphify/cli.py:1970· 8 callers, 159 callees: fans out to 159 callees (efferent coupling); 8 callers depend on it (afferent coupling)render_handoff()ingraphify/handoff.py:676· 7 callers, 8 callees: fans out to 8 callees (efferent coupling); 7 callers depend on it (afferent coupling)_hook_reread()ingraphify/tokenguard.py:376· 0 callers, 12 callees: fans out to 12 callees (efferent coupling)find_transcript()ingraphify/handoff.py:151· 8 callers, 4 callees: 8 callers depend on it (afferent coupling)_ledger_append()ingraphify/tokenguard.py:220· 8 callers, 4 callees: 8 callers depend on it (afferent coupling)render_html()ingraphify/usage.py:706· 5 callers, 7 callees: fans out to 7 callees (efferent coupling)graph_pointers()ingraphify/handoff.py:536· 4 callers, 5 callees: high coupling complexity (Ca·Ce = 20)render_text()ingraphify/usage.py:514· 3 callers, 4 callees: high coupling complexity (Ca·Ce = 12)_hook_daily()ingraphify/tokenguard.py:686· 1 callers, 11 callees: fans out to 11 callees (efferent coupling)_cmd_status()ingraphify/tokenguard.py:987· 1 callers, 7 callees: fans out to 7 callees (efferent coupling)_hook_budget()ingraphify/tokenguard.py:558· 0 callers, 11 callees: fans out to 11 callees (efferent coupling)_hook_bash_cap()ingraphify/tokenguard.py:628· 0 callers, 9 callees: fans out to 9 callees (efferent coupling)test_graph_section_in_note()intests/test_handoff.py:491· 0 callers, 7 callees: fans out to 7 callees (efferent coupling)test_note_excludes_tool_output_and_assistant_prose()intests/test_handoff.py:283· 0 callers, 7 callees: fans out to 7 callees (efferent coupling)test_scan_separates_human_prompts_from_everything_else()intests/test_handoff.py:154· 0 callers, 7 callees: fans out to 7 callees (efferent coupling)test_edit_and_read_ranking()intests/test_handoff.py:208· 0 callers, 6 callees: fans out to 6 callees (efferent coupling)test_main_writes_default_output()intests/test_handoff.py:512· 0 callers, 6 callees: fans out to 6 callees (efferent coupling)test_reference_material_capped_at_ten()intests/test_handoff.py:236· 0 callers, 6 callees: fans out to 6 callees (efferent coupling)test_scan_counts_requests_and_last_context()intests/test_handoff.py:187· 0 callers, 6 callees: fans out to 6 callees (efferent coupling)test_task_list_last_state()intests/test_handoff.py:244· 0 callers, 6 callees: fans out to 6 callees (efferent coupling)test_ledger_holds_no_content_paths_commands_or_prompts()intests/test_tokenguard.py:613· 0 callers, 6 callees: fans out to 6 callees (efferent coupling)
What does this PR do?
Long Claude Code sessions spend most of their tokens re-reading a large context on every request, and graphify's existing hooks only address the first read of a file. On the machine this was built on, 58,000 requests over two months averaged 356k tokens of context; requests sent with more than 200k of context were 88% of all tokens; Bash output was two thirds of all tool-result text; repeated reads of the same file were about 10% of Read calls.
This adds three commands that work without a graph. They live in three new modules and are wired through three
elifbranches incli.py; the existinghook-guardcode andinstall.pyare untouched.graphify usagereads the Claude Code transcripts and reports tokens by model, day and project, context size per request, the heaviest sessions, a fixed-overhead estimate, tool-result size per tool and repeated reads, as text,--jsonor a self-contained--htmlreport.graphify token-guard install|uninstall|status|savingsmanages five Claude Code hooks:bash-cap(PostToolUse/Bash): output above 20,000 chars is cut to head and tail throughupdatedToolOutput; the full output is saved to a file named in the cut.budget(UserPromptSubmit): states the context size when it first passes 200k tokens and at each further 100k.reread(PreToolUse/Read): declines once a repeated read of an unchanged file whose range is already in context; the retry is allowed.reset(SessionStart/compact): clears the read records, since compaction drops file contents.daily(SessionStart/startup): once a day, a user-visible line with what was kept out of context the day before. It adds nothing to the model's context.graphify handoffwritesgraphify-out/HANDOFF.mdfrom the transcript, git state and the graph, with no LLM call, so a fresh session can replace a bloated one.Docs:
docs/token-guard.md.This is three commands in one PR because they serve one purpose and the hooks point at
handoffandsavings. I can split it into three PRs if you prefer.Type of change
Verification & Invariants
Invariants this code protects:
A hook never blocks or breaks a tool call by mistake. Every hook fails open: any exception or unparseable stdin prints nothing and exits 0.
rereaddenies at most once per file version and always allows the retry.bash-capsaves the full output before it prints a replacement, and prints nothing if the save fails.Nothing in graphify's own install is disturbed. The hook commands contain
token-guardand none ofhook-guard,hook-checkorgraphify-out/, so_is_graphify_hook_commandand_strip_graphify_hooksignore them (tested).token-guard installpreserves all other settings, is idempotent, writes atomically and refuses an unparseable settings file.No transcript content is persisted.
usagereports counts, sizes, paths, models and dates. The savings ledger holds kind, size and session key.handoffholds truncated user prompts with secrets masked, paths, counts and a git summary.Extraction is not involved. No extractor, graph or cache code is changed, and no persisted graph state is affected. State lives under
~/.cache/graphify/token-guard(GRAPHIFY_TOKEN_GUARD_DIRoverrides).Read the CONTRIBUTING.md guide.
Reproduced the issue and identified the invariant. (Not a bug fix.)
Made the smallest fix necessary. (Not a bug fix.)
Added a regression test (if bug fix) or isolated boundary test.
Kept the PR description synchronized with the final implementation.
Documented any limitations / unsupported cases explicitly.
Limitations:
budgethook was seen firing in a real Claude Code 2.1.322 session. Therereaddeny, thebash-capreplacement and thedailymessage were exercised only with synthetic payloads through the installed CLI, against the documented hook schema.systemMessageon SessionStart is documented as a universal field but not stated explicitly for that event.O_APPEND/O_EXCLuse and path handling are untested there.How was this tested?
macOS 15, Python 3.12,
uv run --frozen(plainuv runrewroteuv.lockhere, so the lockfile is unchanged in this PR).Tests use synthetic transcripts and payloads under
tmp_pathand the sandboxed home fromtests/conftest.py; they do not read the real~/.claude.Graphify-specific checklist
uv run python -m tools.skillgen --bless) when changing their source fragments. (No skill fragments changed.)AI disclosure: the implementation and this description were written with Claude (see the
Co-Authored-Bytrailers).🤖 Generated with Claude Code