Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

docs(context-budget): scope transcript accounting to explicit private inputs

affaan-mf4d06f7211f6
diff --cc manifests/context-packs/[email protected]
index 000000000,d591dee56..9a0f16657
mode 000000,100644..100644
--- a/manifests/context-packs/[email protected]
+++ b/manifests/context-packs/[email protected]
@@@ -1,0 -1,1 +1,1 @@@
-{"coverage":{"skills":292,"withTriggers":32},"generatedAt":"2026-09-24T23:51:22.784Z","id":"skill-triggers@1","model":{"effort":null,"id":"hand-seeded","source":"manual-curation-pending-regeneration"},"registryDigest":"2c24ec8ddbe6837f0187e2c953e17e14d83b45d348850643e9bd806e00efe70c","schemaVersion":1,"triggers":{"skill:api-connector-builder":["add api integration","new provider connector","match existing integration pattern"],"skill:api-design":["rest endpoint design","pagination api","status codes","api versioning","rate limiting api","resource naming","filtering api","api error responses","offset pagination","limit query parameter","pagination defaults"],"skill:backend-patterns":["express api","node backend architecture","nextjs api routes","server side patterns","data access layer","static file server","url path handling","file server"],"skill:browser-qa":["deployed feature test","visual regression screenshots","core web vitals check","axe accessibility audit","ship do not ship","staging verification"],"skill:canary-watch":["post deploy monitoring","smoke test url","production url check","console errors production","sse stream check","after deploy verification"],"skill:code-tour":["onboarding walkthrough","explain subsystem","architecture tour","pr walkthrough","rca tour"],"skill:coding-standards":["code review standards","naming conventions","readability review","immutability conventions","fix naming typo","export naming","consistent exports"],"skill:content-hash-cache-pattern":["cache file processing","content addressed cache","sha256 hash cache"],"skill:database-migrations":["zero downtime migration","schema change production","add column large table","backfill data","expand contract","concurrent index","migration rollback","prisma migration","django migration"],"skill:deployment-patterns":["ci cd setup","dockerize app","health checks","rollback strategy","production readiness","deploy pipeline","containerize application"],"skill:design-system":["design tokens","visual consistency audit","css custom properties","ui audit","design system bootstrap"],"skill:django-patterns":["django orm","drf api","django rest framework","django caching","django signals","django middleware"],"skill:django-security":["django authentication","csrf protection","sql injection prevention","xss prevention","django deployment security","role based access control","authorization middleware","permissions checks"],"skill:docker-patterns":["dockerfile review","docker compose setup","container security","multi service orchestration"],"skill:error-handling":["error types","retry logic","circuit breaker","user facing errors","exception handling patterns","typed errors","error boundaries","go error handling","custom error class","error codes","config validation"],"skill:evm-token-decimals":["token decimals","wei conversion","erc20 balance off","bridge token precision"],"skill:frontend-a11y":["aria attributes","screen reader support","focus management","semantic html","form labeling","keyboard navigation react","a11y lint errors"],"skill:git-workflow":["merge vs rebase","commit conventions","resolve merge conflict","branching strategy","clean up commits","pull request cleanup","git history tidy"],"skill:hexagonal-architecture":["ports and adapters","dependency injection boundaries","decouple domain from io"],"skill:kubernetes-patterns":["kubernetes manifests","kubectl debugging","pod probes","k8s rbac","autoscaling config","configmap secrets"],"skill:orch-fix-defect":["fix a bug","broken behavior","regression fix","reproduce bug","defect repair"],"skill:postgres-patterns":["slow postgres query","query optimization","index design","rls policies","supabase schema","postgres indexing","database performance","schema design postgres","postgres driver","node postgres","query planner"],"skill:python-patterns":["pythonic code","pep 8","type hints python","python code review","idiomatic python"],"skill:python-testing":["pytest fixtures","mocking python","parametrized tests","coverage python","tdd python"],"skill:redis-patterns":["cache aside pattern","distributed lock","redis rate limiting","cache invalidation"],"skill:regex-vs-llm-structured-text":["parse invoice","extract receipt data","text extraction pipeline","parse form fields","cheap document parser","extract table data","parse log lines","parse access logs","common log format","log line parsing"],"skill:rust-patterns":["rust ownership","borrow checker","rust error handling","traits rust","rust concurrency","idiomatic rust"],"skill:search-first":["find existing library","npm package research","before writing custom code","evaluate existing tools","add dependency research"],"skill:security-review":["security audit","authentication review","sanitize user input","secrets handling","payment security checklist","prevent injection attacks","secure api endpoints","authn authz review","vulnerability checklist","input validation security","parameterized queries","sql injection"],"skill:security-scan":["audit claude config","claudemd security","mcp server audit","agentshield scan","hook configuration audit","settings json security"],"skill:tdd-workflow":["write test first","failing test","red green refactor","test driven development","regression test first","write a regression test"],"skill:verification-loop":["pre pr checks","verification report","quality gates","build lint test coverage","before creating a pr"]},"triggersDigest":"25b97a9e06fc336c7cf95ab854ed1a41033a54bcd6e1fb1cf69dc906332462aa"}
++{"coverage":{"skills":292,"withTriggers":32},"generatedAt":"2026-09-24T23:51:22.784Z","id":"skill-triggers@1","model":{"effort":null,"id":"hand-seeded","source":"manual-curation-pending-regeneration"},"registryDigest":"26b59617cd5a7ae27dd6328a482eaf953a083d611df89fa120c8bf61a17b0c3c","schemaVersion":1,"triggers":{"skill:api-connector-builder":["add api integration","new provider connector","match existing integration pattern"],"skill:api-design":["rest endpoint design","pagination api","status codes","api versioning","rate limiting api","resource naming","filtering api","api error responses","offset pagination","limit query parameter","pagination defaults"],"skill:backend-patterns":["express api","node backend architecture","nextjs api routes","server side patterns","data access layer","static file server","url path handling","file server"],"skill:browser-qa":["deployed feature test","visual regression screenshots","core web vitals check","axe accessibility audit","ship do not ship","staging verification"],"skill:canary-watch":["post deploy monitoring","smoke test url","production url check","console errors production","sse stream check","after deploy verification"],"skill:code-tour":["onboarding walkthrough","explain subsystem","architecture tour","pr walkthrough","rca tour"],"skill:coding-standards":["code review standards","naming conventions","readability review","immutability conventions","fix naming typo","export naming","consistent exports"],"skill:content-hash-cache-pattern":["cache file processing","content addressed cache","sha256 hash cache"],"skill:database-migrations":["zero downtime migration","schema change production","add column large table","backfill data","expand contract","concurrent index","migration rollback","prisma migration","django migration"],"skill:deployment-patterns":["ci cd setup","dockerize app","health checks","rollback strategy","production readiness","deploy pipeline","containerize application"],"skill:design-system":["design tokens","visual consistency audit","css custom properties","ui audit","design system bootstrap"],"skill:django-patterns":["django orm","drf api","django rest framework","django caching","django signals","django middleware"],"skill:django-security":["django authentication","csrf protection","sql injection prevention","xss prevention","django deployment security","role based access control","authorization middleware","permissions checks"],"skill:docker-patterns":["dockerfile review","docker compose setup","container security","multi service orchestration"],"skill:error-handling":["error types","retry logic","circuit breaker","user facing errors","exception handling patterns","typed errors","error boundaries","go error handling","custom error class","error codes","config validation"],"skill:evm-token-decimals":["token decimals","wei conversion","erc20 balance off","bridge token precision"],"skill:frontend-a11y":["aria attributes","screen reader support","focus management","semantic html","form labeling","keyboard navigation react","a11y lint errors"],"skill:git-workflow":["merge vs rebase","commit conventions","resolve merge conflict","branching strategy","clean up commits","pull request cleanup","git history tidy"],"skill:hexagonal-architecture":["ports and adapters","dependency injection boundaries","decouple domain from io"],"skill:kubernetes-patterns":["kubernetes manifests","kubectl debugging","pod probes","k8s rbac","autoscaling config","configmap secrets"],"skill:orch-fix-defect":["fix a bug","broken behavior","regression fix","reproduce bug","defect repair"],"skill:postgres-patterns":["slow postgres query","query optimization","index design","rls policies","supabase schema","postgres indexing","database performance","schema design postgres","postgres driver","node postgres","query planner"],"skill:python-patterns":["pythonic code","pep 8","type hints python","python code review","idiomatic python"],"skill:python-testing":["pytest fixtures","mocking python","parametrized tests","coverage python","tdd python"],"skill:redis-patterns":["cache aside pattern","distributed lock","redis rate limiting","cache invalidation"],"skill:regex-vs-llm-structured-text":["parse invoice","extract receipt data","text extraction pipeline","parse form fields","cheap document parser","extract table data","parse log lines","parse access logs","common log format","log line parsing"],"skill:rust-patterns":["rust ownership","borrow checker","rust error handling","traits rust","rust concurrency","idiomatic rust"],"skill:search-first":["find existing library","npm package research","before writing custom code","evaluate existing tools","add dependency research"],"skill:security-review":["security audit","authentication review","sanitize user input","secrets handling","payment security checklist","prevent injection attacks","secure api endpoints","authn authz review","vulnerability checklist","input validation security","parameterized queries","sql injection"],"skill:security-scan":["audit claude config","claudemd security","mcp server audit","agentshield scan","hook configuration audit","settings json security"],"skill:tdd-workflow":["write test first","failing test","red green refactor","test driven development","regression test first","write a regression test"],"skill:verification-loop":["pre pr checks","verification report","quality gates","build lint test coverage","before creating a pr"]},"triggersDigest":"25b97a9e06fc336c7cf95ab854ed1a41033a54bcd6e1fb1cf69dc906332462aa"}
diff --cc skills/context-budget/SKILL.md
index 0fa5cc3e3,1061041c6..084b30901
--- a/skills/context-budget/SKILL.md
+++ b/skills/context-budget/SKILL.md
@@@ -43,47 -43,6 +43,56 @@@ Scan all component directories and esti
- Estimate schema overhead at ~500 tokens per tool
- Flag: servers with >20 tools, servers that wrap simple CLI commands (`gh`, `git`, `npm`, `supabase`, `vercel`)
- **Session scaffolding** (measured from the transcript)
++**Persisted-record bytes** (optional)
+
- Everything above is loaded once at startup. A *reconnect* re-injects much of it again as `attachment`
- lines in the session transcript — and that re-injection is charged to the same context window.
++For a local file diagnostic, explicitly select a stable, regular JSONL file or a snapshot you
++intend to inspect. Replace the example path below; this does not find or reconnect a session.
++The snippet prints aggregate byte counts only. It reads one line at a time, so memory use depends
++on the largest record; avoid very large records and actively growing files.
+
+```sh
- f=$(ls -t ~/.claude/projects/"${PWD//\//-}"/*.jsonl 2>/dev/null | head -1)
- [ -n "$f" ] || { echo "no transcript for this project yet"; exit 0; }
- python3 - "$f" <<'EOF'
- import json,sys
- tot=att=0
- for line in open(sys.argv[1], encoding="utf-8", errors="replace"):
- if not line.strip(): continue
- tot+=len(line.encode())
- try:
- if json.loads(line).get("type")=="attachment": att+=len(line.encode())
- except Exception: pass # a malformed line counts as conversation, never crashes
- if tot==0: print("empty transcript"); raise SystemExit
- pct = att*100.0/tot
- print(f"transcript {tot}B | scaffolding {att}B ({pct:.1f}%) | rest {tot-att}B")
- if att*10 > tot*4: print(f"WARNING: scaffolding is {pct:.1f}% of the transcript (>40%)")
++python3 - "/path/to/selected-session.jsonl" <<'EOF'
++import json
++import sys
++
++total = attachment = other = unclassified = 0
++try:
++ with open(sys.argv[1], "rb") as source:
++ for raw in source:
++ size = len(raw)
++ total += size
++ try:
++ record = json.loads(raw.decode("utf-8"))
++ except (UnicodeDecodeError, json.JSONDecodeError):
++ unclassified += size
++ continue
++ record_type = record.get("type") if isinstance(record, dict) else None
++ if not isinstance(record_type, str):
++ unclassified += size
++ elif record_type == "attachment":
++ attachment += size
++ else:
++ other += size
++except OSError:
++ print("Cannot read selected JSONL file.", file=sys.stderr)
++ raise SystemExit(1)
++
++pct = attachment * 100.0 / total if total else 0.0
++print(f"persisted {total}B | attachment records {attachment}B ({pct:.1f}%) | "
++ f"other records {other}B | unclassified {unclassified}B")
+EOF
+```
+
- Measured on a session that had reconnected once: **33,884 of 49,830 bytes — 68% scaffolding**
- (`skill_listing` 14.6KB, `mcp_instructions_delta` 8.1KB, `deferred_tools_delta` 7.1KB,
- `agent_listing_delta` 2.6KB) against 15.9KB of conversation.
-
- **What this number is, and what it is not.**
-
- - It *is* a cost signal. Scaffolding is real context spend, and it is rebuilt on every reconnect —
- so trimming a skill or an MCP server saves tokens **once per reconnect**, not once per session.
- That strengthens every recommendation elsewhere in this skill.
- - It is **not** a headroom estimate, in either direction. Attachments *are* charged, so excluding
- them overstates free space. And after a compaction the pre-compaction turns remain in the JSONL
- while the model's active context holds only the much smaller summary — so counting persisted bytes
- overstates what is actually loaded. **A transcript is a durable log, not a view of the context
- window; do not report remaining room from its size.**
- - Report it as two separate figures — scaffolding share of the transcript, and conversation bytes —
- and treat both as diagnostics rather than as a fullness gauge.
++The three categories add up to the original file bytes, including line endings and blank lines.
++`attachment` is an exact record-type filter, not a guarantee about a harness's current internal
++schema. Other records have a different string `type`; malformed JSON, invalid UTF-8, nonobject
++values, missing or non-string types, and blank lines are unclassified. Neither category means
++"conversation," and the percentage is only a share of persisted bytes.
++
++These counts do not establish active context, remaining room, token usage, billing, or what a
++reconnect loads. For current harness-reported context and usage, use the version-appropriate
++[`/context` and `/usage` commands (`/cost` is an alias)](https://code.claude.com/docs/en/commands).
+
**CLAUDE.md** (project + user-level)
- Count tokens per file in the CLAUDE.md chain
- Flag: combined total >300 lines