SKILL.md
name:
contextburn
description:
Measure coding-agent context/token efficiency from existing Claude Code transcript logs, identify repeated context re-reading, and produce privacy-bounded efficiency evidence. IMPERIAL governed adapter for arsentev-ai/contextburn.
triggers:
token-efficiency
context-window
claude-code
transcript-analysis
context-burn
cost-observability
agent-efficiency

ContextBurn — IMPERIAL bounded token-efficiency capability

Upstream: arsentev-ai/contextburn Pinned commit reviewed: 5d5d149a5c4123521d08f8b0e5ddb89c1b19cb61 License: MIT Native runtime baseline: Python 3; upstream CLI itself is dependency-free for its basic local transcript analysis.

What upstream provides

ContextBurn reads Claude Code transcript JSONL files already present on a compatible machine and estimates how much token traffic became model output versus repeated context re-reading. Upstream documents local-only analysis with no network calls for the core CLI.

IMPERIAL installation mode

Installed across the three IMPERIAL runtime nodes as a governed observability profile. Val Town serverless nodes do not have a verified local ~/.claude/projects/**/*.jsonl transcript store and therefore are not claimed as native ContextBurn hosts. Native execution requires a compatible host with Python 3 and explicit access to the relevant local transcript directory.

Compatible-host baseline:

cp bin/contextburn ~/bin/contextburn
chmod +x ~/bin/contextburn
contextburn detail 24
contextburn --json

Allowed use

  • measure context/token efficiency for authorized agent sessions;
  • identify repeated context re-reading and expensive long-session behavior;
  • compare session strategies without changing model authority;
  • feed aggregate efficiency metrics into HANTER/Audit observability;
  • support NO-RECHECK and quota-preservation decisions with evidence.

Privacy and security

  • Do not export raw PRIVATE/SECRET/RESTRICTED transcripts to external services.
  • Prefer aggregate counters and hashes over full prompt/body capture.
  • Never log credentials, OAuth tokens, private keys, cookies or secrets from transcripts.
  • Raw transcripts remain source evidence and are read-only unless separately authorized.
  • Guardian Core, Approval Gateway, Audit Ledger, Zero Trust, AI Passport and Public/Private Boundary remain authoritative.

FREE_ONLY

Core local analysis requires no paid API. Do not activate any paid telemetry backend or paid model route for this skill. Spend remains 0 USD.

Truth boundaries

  • SKILL_BOUND != LOCAL_CLAUDE_TRANSCRIPTS_PRESENT
  • TOKEN_EFFICIENCY_METRIC != TASK_QUALITY
  • LOW_CONTEXT_BURN != CORRECT_RESULT
  • OBSERVABILITY != AUTHORITY
  • NO_NETWORK_CORE != PERMISSION_TO_EXPORT_TRANSCRIPTS

Authorship of this IMPERIAL adapter: Alexander Romaskevich / RomaskevicH. Upstream project authorship remains with Evgenii Arsentev and upstream contributors under the MIT license.