Skip to content

feat: token guard, usage report and handoff note for Claude Code - #5313

Open
cell3790 wants to merge 2 commits into
Graphify-Labs:v8from
cell3790:feat/token-guard
Open

cell3790 wants to merge 2 commits into
Graphify-Labs:v8from
cell3790:feat/token-guard

Conversation

@cell3790

Copy link
Copy Markdown

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 elif branches in cli.py; the existing hook-guard code and install.py are untouched.

  • 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 install|uninstall|status|savings manages five Claude Code hooks:
    • bash-cap (PostToolUse/Bash): output above 20,000 chars is cut to head and tail through updatedToolOutput; 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 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.

Docs: docs/token-guard.md.

This is three commands in one PR because they serve one purpose and the hooks point at handoff and savings. I can split it into three PRs if you prefer.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Tests or CI
  • Refactor
  • Security fix

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. reread denies at most once per file version and always allows the retry. bash-cap saves 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-guard and none of hook-guard, hook-check or graphify-out/, so _is_graphify_hook_command and _strip_graphify_hooks ignore them (tested). token-guard install preserves all other settings, is idempotent, writes atomically and refuses an unparseable settings file.

  • No transcript content is persisted. usage reports counts, sizes, paths, models and dates. The savings ledger holds kind, size and session key. handoff holds 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_DIR overrides).

  • 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:

  • Live coverage is partial. The budget hook was seen firing in a real Claude Code 2.1.322 session. The reread deny, the bash-cap replacement and the daily message were exercised only with synthetic payloads through the installed CLI, against the documented hook schema.
  • systemMessage on SessionStart is documented as a universal field but not stated explicitly for that event.
  • Windows was not exercised. O_APPEND/O_EXCL use and path handling are untested there.
  • The transcript format is undocumented. Parsers match what current transcripts contain and skip anything else.
  • Estimates. Savings are characters / 4 and exclude the effect of later re-reads. Fixed overhead is first-request context (capped at twice the median) times requests.
  • A recorded read may have failed. Reads are recorded in PreToolUse, so a read that Claude Code then rejects costs one wrong notice; the retry is allowed.
  • No LLM labelling or README change is included.

How was this tested?

macOS 15, Python 3.12, uv run --frozen (plain uv run rewrote uv.lock here, so the lockfile is unchanged in this PR).

uv run --frozen pytest tests/test_tokenguard.py tests/test_usage.py tests/test_handoff.py -q
  207 passed

uv run --frozen pytest tests -q            # this branch
  27 failed, 11338 passed, 400 skipped, 1 xfailed
uv run --frozen pytest tests -q            # origin/v8 at 340268a, same machine
  27 failed, 11131 passed, 400 skipped, 1 xfailed
  The 27 failures are the same tests on both (test_ext_tagged_id_clash.py,
  test_pascal_singleton_resolution.py, test_skillgen.py); none is in a file
  this PR touches. I did not install --all-extras.

uv run --frozen ruff check .
  All checks passed!

uv run --frozen pyright graphify/tokenguard.py graphify/usage.py graphify/handoff.py \
    tests/test_tokenguard.py tests/test_usage.py tests/test_handoff.py
  0 errors
  (repo-wide pyright reports unresolved optional imports in this environment,
  with or without this PR)

graphify usage --days 7                    # real ~/.claude/projects, 6 GB: about 20 s for the full history
graphify handoff --transcript <637 MB transcript> --stdout   # 1.3 s
graphify token-guard install / status / savings              # against real user settings

Tests use synthetic transcripts and payloads under tmp_path and the sandboxed home from tests/conftest.py; they do not read the real ~/.claude.

Graphify-specific checklist

  • I updated generated skill artifacts (uv run python -m tools.skillgen --bless) when changing their source fragments. (No skill fragments changed.)
  • I confirmed that AST/structural extraction remains deterministic (no ambient state dependencies like ENV variables). (Extraction is untouched; the new env vars only affect the hooks.)
  • I reviewed changes for security implications (no unsafe interpolation into shell/Python).
  • I confirmed no API keys or local-only graph data are included.
  • (If applicable) I disclosed AI authorship in my commit messages.

AI disclosure: the implementation and this description were written with Claude (see the Co-Authored-By trailers).

🤖 Generated with Claude Code

cell3790 and others added 2 commits November 18, 2026 15:38
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>
@cell3790
cell3790 requested a review from safishamsi as a code owner November 18, 2026 13:41
@github-actions

Copy link
Copy Markdown

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.

@graphify-labs graphify-labs Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Graphify code review View in Graphify

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-guard and 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-safety
  • tests/test_4874_jvm_resolution.py — full-run-safety
  • tests/test_4909_reference_binding_scale.py — full-run-safety
  • tests/test_4978_reconcile_cost.py — full-run-safety
  • tests/test_4992_ts_import_types.py — full-run-safety
  • tests/test_5072_splittable_under_cap_retry.py — full-run-safety
  • tests/test_affected_cli.py — impact, full-run-safety
  • tests/test_affected_defines.py — full-run-safety
  • tests/test_affected_member_seed.py — full-run-safety
  • tests/test_affected_overrides.py — full-run-safety
  • tests/test_affected_path_file_node.py — full-run-safety
  • tests/test_affected_seed_reference_forms.py — impact, full-run-safety
  • tests/test_agents_platform.py — impact, full-run-safety
  • tests/test_alias_folding.py — full-run-safety
  • tests/test_analyze.py — full-run-safety
  • tests/test_anthropic_custom_endpoint.py — full-run-safety
  • tests/test_antigravity_install.py — full-run-safety
  • tests/test_apm_fallback_version.py — full-run-safety
  • tests/test_architecture_doc.py — full-run-safety
  • tests/test_astro_extraction.py — full-run-safety
  • tests/test_astro_import_ids.py — full-run-safety
  • tests/test_atomic_canvas_export.py — full-run-safety
  • tests/test_atomic_version_stamp.py — full-run-safety
  • tests/test_atomic_writes.py — full-run-safety
  • tests/test_backend_env_isolation.py — full-run-safety
  • tests/test_backend_extras.py — full-run-safety
  • tests/test_backend_opt_in.py — full-run-safety
  • tests/test_benchmark.py — full-run-safety
  • tests/test_benchmark_raw_graph.py — full-run-safety
  • tests/test_benchmark_real_query.py — full-run-safety
  • tests/test_binary_media_words.py — full-run-safety
  • tests/test_blade_extractor.py — full-run-safety
  • tests/test_build.py — full-run-safety
  • tests/test_build_located_semantic_identity.py — full-run-safety
  • tests/test_build_merge_dedup_scope.py — full-run-safety
  • tests/test_build_merge_ghost_fold_4955.py — full-run-safety
  • tests/test_build_merge_hyperedges_and_prune.py — full-run-safety
  • tests/test_build_merge_shrink_guard.py — full-run-safety
  • tests/test_builtin_global_type_refs.py — full-run-safety
  • tests/test_c_include_resolution.py — full-run-safety
  • tests/test_cache.py — full-run-safety
  • tests/test_cache_long_paths.py — full-run-safety
  • tests/test_cache_stale_import_target.py — full-run-safety
  • tests/test_cache_windows_case_4925.py — full-run-safety
  • tests/test_callflow_html.py — full-run-safety
  • tests/test_cargo_introspect.py — full-run-safety
  • tests/test_cargo_missing_manifest.py — full-run-safety
  • tests/test_carried_hyperedge_remap.py — full-run-safety
  • tests/test_case_only_decl_ids_4904.py — full-run-safety
  • tests/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-fetch in graphify/tokenguard.py:116: unbounded read (no limit/bound): data = json.loads(sys.stdin.buffer.read().decode("utf-8", "replace"))
  • medium no-unbounded-fetch in graphify/tokenguard.py:884: unbounded read (no limit/bound): raw = fh.read()

Docs that may be stale (advisory)

…and 10 more.

Every flagged function

  • main() in graphify/tokenguard.py:1034 · 19 callers, 5 callees: 19 callers depend on it (afferent coupling)
  • analyze() in graphify/usage.py:140 · 12 callers, 12 callees: fans out to 12 callees (efferent coupling); 12 callers depend on it (afferent coupling)
  • scan_transcript() in graphify/handoff.py:386 · 12 callers, 6 callees: fans out to 6 callees (efferent coupling); 12 callers depend on it (afferent coupling)
  • main() in graphify/usage.py:826 · 11 callers, 4 callees: 11 callers depend on it (afferent coupling)
  • main() in graphify/handoff.py:827 · 10 callers, 6 callees: fans out to 6 callees (efferent coupling); 10 callers depend on it (afferent coupling)
  • build_handoff() in graphify/handoff.py:795 · 9 callers, 6 callees: fans out to 6 callees (efferent coupling); 9 callers depend on it (afferent coupling)
  • dispatch_command() in graphify/cli.py:1970 · 8 callers, 159 callees: fans out to 159 callees (efferent coupling); 8 callers depend on it (afferent coupling)
  • render_handoff() in graphify/handoff.py:676 · 7 callers, 8 callees: fans out to 8 callees (efferent coupling); 7 callers depend on it (afferent coupling)
  • _hook_reread() in graphify/tokenguard.py:376 · 0 callers, 12 callees: fans out to 12 callees (efferent coupling)
  • find_transcript() in graphify/handoff.py:151 · 8 callers, 4 callees: 8 callers depend on it (afferent coupling)
  • _ledger_append() in graphify/tokenguard.py:220 · 8 callers, 4 callees: 8 callers depend on it (afferent coupling)
  • render_html() in graphify/usage.py:706 · 5 callers, 7 callees: fans out to 7 callees (efferent coupling)
  • graph_pointers() in graphify/handoff.py:536 · 4 callers, 5 callees: high coupling complexity (Ca·Ce = 20)
  • render_text() in graphify/usage.py:514 · 3 callers, 4 callees: high coupling complexity (Ca·Ce = 12)
  • _hook_daily() in graphify/tokenguard.py:686 · 1 callers, 11 callees: fans out to 11 callees (efferent coupling)
  • _cmd_status() in graphify/tokenguard.py:987 · 1 callers, 7 callees: fans out to 7 callees (efferent coupling)
  • _hook_budget() in graphify/tokenguard.py:558 · 0 callers, 11 callees: fans out to 11 callees (efferent coupling)
  • _hook_bash_cap() in graphify/tokenguard.py:628 · 0 callers, 9 callees: fans out to 9 callees (efferent coupling)
  • test_graph_section_in_note() in tests/test_handoff.py:491 · 0 callers, 7 callees: fans out to 7 callees (efferent coupling)
  • test_note_excludes_tool_output_and_assistant_prose() in tests/test_handoff.py:283 · 0 callers, 7 callees: fans out to 7 callees (efferent coupling)
  • test_scan_separates_human_prompts_from_everything_else() in tests/test_handoff.py:154 · 0 callers, 7 callees: fans out to 7 callees (efferent coupling)
  • test_edit_and_read_ranking() in tests/test_handoff.py:208 · 0 callers, 6 callees: fans out to 6 callees (efferent coupling)
  • test_main_writes_default_output() in tests/test_handoff.py:512 · 0 callers, 6 callees: fans out to 6 callees (efferent coupling)
  • test_reference_material_capped_at_ten() in tests/test_handoff.py:236 · 0 callers, 6 callees: fans out to 6 callees (efferent coupling)
  • test_scan_counts_requests_and_last_context() in tests/test_handoff.py:187 · 0 callers, 6 callees: fans out to 6 callees (efferent coupling)
  • test_task_list_last_state() in tests/test_handoff.py:244 · 0 callers, 6 callees: fans out to 6 callees (efferent coupling)
  • test_ledger_holds_no_content_paths_commands_or_prompts() in tests/test_tokenguard.py:613 · 0 callers, 6 callees: fans out to 6 callees (efferent coupling)

This branch has not been deployed

No deployments
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