perf(skills): cut skill tokens and load hooks from cached bytecode

Hooks start their script as __main__ from cached bytecode instead of recompiling it on every call, and the installer migrates registered old hook commands to that form. A disabled plugin is written as false instead of deleted, because a deleted key in settings.local.json lets a true in settings.json win; the auto-compact window drops to 300000. The coach hour prints one ready line chosen by the time of day instead of asking the agent to load the skill, kvb-cleanup moves its procedure into plan.md, and the token counter reads subagent transcripts too and counts with Counter and defaultdict instead of .get defaults.

🎯 Fix: 88 %
💥 Break: 8 %
💸 Tokens: –
⏱️ Velocity: –
🛡️ Security: 100 %
🏆 Score: 81
🚦 Gate: ⛔ fix 88 % < 90, break 8 % > 5

Created-with: https://s.veen.world/skills
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-18 19:40:37 +00:00
1 parent d695bb2b58
commit 6c63c364bd
13 files changed
+250 -130

No files matched your search

+13 -7
View File
@@ -55,11 +55,12 @@ for (const [name, entry] of Object.entries(MARKETPLACES)) {
} }
data.enabledPlugins = Object.assign(data.enabledPlugins || {}, PLUGINS); data.enabledPlugins = Object.assign(data.enabledPlugins || {}, PLUGINS);
for (const [plugin, marketplace] of Object.entries(RETIRED_PLUGINS)) { for (const [plugin, marketplace] of Object.entries(RETIRED_PLUGINS)) {
delete data.enabledPlugins[plugin]; // Trip-wire: this file can be settings.local.json; a deleted key there lets a true in settings.json win, a false overrides it.
data.enabledPlugins[plugin] = false;
delete data.extraKnownMarketplaces[marketplace]; delete data.extraKnownMarketplaces[marketplace];
} }
data.env = data.env || {}; data.env = data.env || {};
if (!data.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW) data.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = "500000"; if (!data.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW) data.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = "300000";
const PYTHON = "/usr/bin/python3 -I"; const PYTHON = "/usr/bin/python3 -I";
const ABSOLUTE = { python3: PYTHON, bash: "/usr/bin/bash" }; const ABSOLUTE = { python3: PYTHON, bash: "/usr/bin/bash" };
require("./council-deny").withCouncilDeny(data); require("./council-deny").withCouncilDeny(data);
@@ -129,15 +130,20 @@ const SCRIPT_HOOKS = [
["kvb-org-perform/scripts/log.py", "PostToolUse", "Bash", "persist", {}], ["kvb-org-perform/scripts/log.py", "PostToolUse", "Bash", "persist", {}],
["kvb-agent-optimize/scripts/graph.py", "PreToolUse", null, "hook", { timeout: 30 }], ["kvb-agent-optimize/scripts/graph.py", "PreToolUse", null, "hook", { timeout: 30 }],
]; ];
// Trip-wire: python3 recompiles the script it is started with on every call and caches only imported modules; loading it as __main__ by file path reuses its __pycache__.
const AS_MAIN = `'import importlib.util as u,sys;s=u.spec_from_file_location("__main__",sys.argv[1]);m=u.module_from_spec(s);sys.argv=sys.argv[1:];sys.modules["__main__"]=m;s.loader.exec_module(m)'`;
for (const [script, event, matcher, sub, extra] of SCRIPT_HOOKS) { for (const [script, event, matcher, sub, extra] of SCRIPT_HOOKS) {
data.hooks[event] = data.hooks[event] || []; data.hooks[event] = data.hooks[event] || [];
const registered = data.hooks[event].some((entry) =>
(entry.hooks || []).some((hook) =>
String(hook.command).includes(script) && String(hook.command).endsWith(` ${sub}`)));
if (registered) continue;
const file = JSON.stringify(path.join(path.dirname(settingsPath), "skills", ...script.split("/"))); const file = JSON.stringify(path.join(path.dirname(settingsPath), "skills", ...script.split("/")));
// Trip-wire: python3 on a missing file exits 2, which blocks every prompt or tool call; the test makes it exit 1. // Trip-wire: python3 on a missing file exits 2, which blocks every prompt or tool call; the test makes it exit 1.
const command = `[ -f ${file} ] && ${PYTHON} ${file} ${sub}`; const command = `[ -f ${file} ] && ${PYTHON} -c ${AS_MAIN} ${file} ${sub}`;
const legacy = [`${PYTHON} ${file} ${sub}`, `[ -f ${file} ] && ${PYTHON} ${file} ${sub}`];
const registered = data.hooks[event].flatMap((entry) => entry.hooks || []).find((hook) =>
String(hook.command).includes(script) && String(hook.command).endsWith(` ${sub}`));
if (registered) {
if (legacy.includes(registered.command)) registered.command = command;
continue;
}
const entry = { hooks: [{ type: "command", command, ...extra }] }; const entry = { hooks: [{ type: "command", command, ...extra }] };
data.hooks[event].push(matcher ? { matcher, ...entry } : entry); data.hooks[event].push(matcher ? { matcher, ...entry } : entry);
} }
+3 -2
View File
@@ -27,8 +27,9 @@ per day and never changes the exit code; pass its quotient or `?` to
`kvb-check-score --value`. `kvb-check-score --value`.
- **Cost**: listing words delta x 1.33 x requests x 0.1 (cached) plus each - **Cost**: listing words delta x 1.33 x requests x 0.1 (cached) plus each
changed `SKILL.md`'s tokens delta x its invocations, per day of the last changed `SKILL.md`'s tokens delta x (its invocations + 0.1 x the later
7 days' transcripts (other runtimes: JSONL of that shape). A new skill turns it stays resident), per day of the last 7 days' session and
subagent transcripts (other runtimes: JSONL of that shape). A new skill
takes its category's median, named in the line. takes its category's median, named in the line.
- **Value**: tokens/day saved, derived by one `--evidence` line, e.g. - **Value**: tokens/day saved, derived by one `--evidence` line, e.g.
`"3829 SendMessage wakes/day x 10 % avoided x 43k"`; else `?:?`. `"3829 SendMessage wakes/day x 10 % avoided x 43k"`; else `?:?`.
+71 -34
View File
@@ -4,9 +4,12 @@
Args: Args:
--repo: skills repository root; its scripts/budget.py counts the listing. --repo: skills repository root; its scripts/budget.py counts the listing.
--base: git ref the change starts from; the working tree is the after side. --base: git ref the change starts from; the working tree is the after side.
--transcripts: Claude Code transcripts root, e.g. ~/.claude/projects; every */*.jsonl of the --transcripts: Claude Code transcripts root, e.g. ~/.claude/projects; every session and
last 7 days gives the requests (unique assistant message ids) and the invocations per skill subagent transcript of the last 7 days (context.py of kvb-skill-silence lists them) gives
(unique Skill tool_use ids, a `<scope>:` prefix stripped). Read only; no text is printed. the requests (unique assistant message ids), the invocations per skill (unique Skill
tool_use ids, a `<scope>:` prefix stripped) and per skill its resident turns: every later
request of the same transcript, once per invocation, as Claude Code keeps an invoked
skill in context and re-injects it after a compaction. Read only; no text is printed.
--value: tokens per day the change saves; needs --evidence. --value: tokens per day the change saves; needs --evidence.
--evidence: one line that derives --value. --evidence: one line that derives --value.
--json: print the figures as JSON instead of the lines. --json: print the figures as JSON instead of the lines.
@@ -23,10 +26,11 @@ Output:
Line 2: `💰 value 1:<n> (cost <c>/day, value <v>/day; <evidence>)` when the value is at least Line 2: `💰 value 1:<n> (cost <c>/day, value <v>/day; <evidence>)` when the value is at least
the cost, `<n>:1` below it, `0:1` without a cost, `1:0` without a value; without --value the cost, `<n>:1` below it, `0:1` without a cost, `1:0` without a value; without --value
`💰 value ?:? (cost <c>/day; pass --value with evidence)`. Cost per day = listing words delta `💰 value ?:? (cost <c>/day; pass --value with evidence)`. Cost per day = listing words delta
* 1.33 tokens * requests per day * 0.1 (cached) + per changed SKILL.md its tokens delta * the * 1.33 tokens * requests per day * 0.1 (cached) + per changed SKILL.md its tokens delta *
skill's invocations per day. A skill without a base SKILL.md takes the median invocations of (the skill's invocations per day + 0.1 * its resident turns per day). A skill without a base
its category's base skills (the name up to its second dash; all base skills when it has SKILL.md takes the median invocations and the median resident turns of its category's base
none), and the line names it. skills (the name up to its second dash; all base skills when it has none), and the line
names them.
--json prints efficiency (null when new), the skills and listing totals, the tokens per skill --json prints efficiency (null when new), the skills and listing totals, the tokens per skill
and the value figures. and the value figures.
value: `💰 measured value <v>/day (median daily context <b>→<a> tokens over <n> active days value: `💰 measured value <v>/day (median daily context <b>→<a> tokens over <n> active days
@@ -49,6 +53,7 @@ import math
import statistics import statistics
import subprocess import subprocess
import sys import sys
from collections import Counter, defaultdict
from pathlib import Path, PurePosixPath from pathlib import Path, PurePosixPath
from types import ModuleType from types import ModuleType
@@ -192,55 +197,86 @@ def skill_uses(message: dict) -> list[tuple[str, str]]:
return found return found
def usage(root: Path, since: float) -> tuple[int, dict[str, int]]: def entries(path: Path, since: float):
"""Args:
path: one transcript.
since: the epoch second the window starts.
Returns:
The assistant messages of the window, in transcript order.
"""
with path.open(encoding="utf-8", errors="ignore") as handle:
for line in handle:
if '"assistant"' not in line:
continue
try:
entry = json.loads(line)
stamp = datetime.datetime.fromisoformat(entry["timestamp"]).timestamp()
except (ValueError, KeyError, TypeError):
continue
message = entry.get("message")
if entry.get("type") == "assistant" and stamp >= since and isinstance(message, dict):
yield message
def usage(root: Path, since: float) -> tuple[int, dict[str, int], dict[str, int]]:
"""Args:
root: the transcripts root.
since: the epoch second the window starts.
Returns:
The requests, per skill its invocations, and per skill its resident turns.
"""
listed = load(CONTEXT, "context", "lists the transcripts").transcripts(root)
requests: set[str] = set() requests: set[str] = set()
invocations: dict[str, set[str]] = {} invocations: dict[str, set[str]] = {}
for path in root.glob("*/*.jsonl"): resident: Counter[str] = Counter()
for path in listed:
if path.stat().st_mtime < since: if path.stat().st_mtime < since:
continue continue
with path.open(encoding="utf-8", errors="ignore") as handle: live: Counter[str] = Counter()
for line in handle: for message in entries(path, since):
if '"assistant"' not in line: request = str(message.get("id") or "")
continue if request and request not in requests:
try: requests.add(request)
entry = json.loads(line) resident.update(live)
stamp = datetime.datetime.fromisoformat(entry["timestamp"]).timestamp() for skill, use in skill_uses(message):
except (ValueError, KeyError, TypeError): seen = invocations.setdefault(skill, set())
continue if use not in seen:
message = entry.get("message") seen.add(use)
if entry.get("type") != "assistant" or stamp < since or not isinstance(message, dict): live[skill] += 1
continue return len(requests), {skill: len(uses) for skill, uses in invocations.items()}, resident
if message.get("id"):
requests.add(str(message["id"]))
for skill, use in skill_uses(message):
invocations.setdefault(skill, set()).add(use)
return len(requests), {skill: len(uses) for skill, uses in invocations.items()}
def weigh(root: Path, listing_delta: int, body: dict[str, int], new: set[str], base_skills: list[str]) -> dict: def weigh(root: Path, listing_delta: int, body: dict[str, int], new: set[str], base_skills: list[str]) -> dict:
requests, invocations = usage(root, datetime.datetime.now(datetime.UTC).timestamp() - DAYS * 86400) requests, invocations, resident = usage(root, datetime.datetime.now(datetime.UTC).timestamp() - DAYS * 86400)
per_day = {skill: count / DAYS for skill, count in invocations.items()} per_day = defaultdict(float, {skill: count / DAYS for skill, count in invocations.items()})
rates, assumed = {}, {} held = defaultdict(float, {skill: turns / DAYS for skill, turns in resident.items()})
rates, kept, assumed = {}, {}, {}
for skill in body: for skill in body:
if skill in new: if skill in new:
peers = [peer for peer in base_skills if category(peer) == category(skill)] peers = [peer for peer in base_skills if category(peer) == category(skill)]
assumed[skill] = category(skill) if peers else ALL_SKILLS assumed[skill] = category(skill) if peers else ALL_SKILLS
pool = [per_day.get(peer, 0.0) for peer in peers or base_skills] pool = peers or base_skills
rates[skill] = statistics.median(pool) if pool else 0.0 rates[skill] = statistics.median([per_day[peer] for peer in pool]) if pool else 0.0
kept[skill] = statistics.median([held[peer] for peer in pool]) if pool else 0.0
else: else:
rates[skill] = per_day.get(skill, 0.0) rates[skill] = per_day[skill]
kept[skill] = held[skill]
listing = listing_delta * TOKENS_PER_WORD * (requests / DAYS) * CACHE_FACTOR listing = listing_delta * TOKENS_PER_WORD * (requests / DAYS) * CACHE_FACTOR
return { return {
"cost": listing + sum(delta * rates[skill] for skill, delta in body.items()), "cost": listing + sum(delta * (rates[skill] + CACHE_FACTOR * kept[skill]) for skill, delta in body.items()),
"requests_per_day": requests / DAYS, "requests_per_day": requests / DAYS,
"invocations_per_day": rates, "invocations_per_day": rates,
"resident_turns_per_day": kept,
"median_for_new": assumed, "median_for_new": assumed,
} }
def value_line(weighed: dict, value: float | None, evidence: str | None) -> tuple[str, str]: def value_line(weighed: dict, value: float | None, evidence: str | None) -> tuple[str, str]:
notes = [ notes = [
f"{skill} new: {group} median {figure(weighed['invocations_per_day'][skill])} invocations/day" f"{skill} new: {group} median {figure(weighed['invocations_per_day'][skill])} invocations/day, "
f"{figure(weighed['resident_turns_per_day'][skill])} resident turns/day"
for skill, group in sorted(weighed["median_for_new"].items()) for skill, group in sorted(weighed["median_for_new"].items())
] ]
cost = weighed["cost"] cost = weighed["cost"]
@@ -331,6 +367,7 @@ def check(argv: list[str]) -> int:
"evidence": args.evidence, "evidence": args.evidence,
"requests_per_day": round(weighed["requests_per_day"], 2), "requests_per_day": round(weighed["requests_per_day"], 2),
"invocations_per_day": {s: round(r, 2) for s, r in weighed["invocations_per_day"].items()}, "invocations_per_day": {s: round(r, 2) for s, r in weighed["invocations_per_day"].items()},
"resident_turns_per_day": {s: round(r, 2) for s, r in weighed["resident_turns_per_day"].items()},
"median_for_new": weighed["median_for_new"], "median_for_new": weighed["median_for_new"],
}, },
})) }))
+2 -63
View File
@@ -17,70 +17,9 @@ request and stop, or, ordered here by the operator, first
`${CLAUDE_SKILL_DIR}/../kvb-org-radio/scripts/radio.py post --to <chair> `${CLAUDE_SKILL_DIR}/../kvb-org-radio/scripts/radio.py post --to <chair>
"<plan>"`. "<plan>"`.
## Step 1: inventory ## Steps 1 to 4: inventory, owners, classes, proposal
Read-only, parallel, sized, only in the agent write scope (Claude Code: Read `plan.md` here and follow it to its `Execute` pick.
`sandbox.filesystem.allowWrite`) and session scratch dirs, never another
user's files. Prefer project cleanup and teardown targets; obey raw-command
bans.
- **/tmp**: `pkgmgr gc --report --docker --root /tmp --root <write dir>`,
else `du -sh` per own entry; never system entries (`.*-unix`,
`systemd-private-*`, `ssh-*`, `tmux-*`, sockets).
- **Docker**, **worktrees**: read `docker.md` (its `⚠ Volumes` checklist
joins Step 4) and `worktrees.md` here when present.
- **Agent dirs**: pip, npm, pre-commit, act, gh, buildx caches; Ansible and
build temp dirs.
- **Council root** (`~/.local/state/agents-shared`): `archive/` only.
- **Register**: `council.py list --long`; `rasci.py artifacts`
(`kvb-org-artefacts`, `--ended` for candidates).
- **Queue**: `${CLAUDE_SKILL_DIR}/../kvb-org-queue-cleanup/scripts/cleanup.py
request`; go on meanwhile.
- **Live use**: `fuser` (exit 1 or 123: free), `lsof`, `ps -o
pid,etime,comm`; never full command lines or environments (credentials).
Sandboxed, an empty result proves nothing.
- **Archive duties**: memory or project rules requiring a copy before
deletion (logs, reports, generated maps).
## Step 2: ask the owners
Owner: register worker, path session id, worktree or compose project,
container label, open handle, else `unknown`. Once per local peer owning
unregistered candidates, `radio.py send call --to <peer>` the `ask.md` text;
go on meanwhile.
## Step 3: classify
First match wins: claimed by a peer, `keep`; in a register task not `done`,
`stopped` or `stale` (a branch merged into the default makes it
`stale`; an ended task's items are its worker's candidates), `keep (task <task>)`; a
running deploy, gate, test, swarm or build, `keep (running)`; a silent peer's,
`keep (no answer from <peer>)`, silence is not consent; sandboxed, touched
within 24 hours (`find -mmin -1440`; bfs fails on `-newermt`) and neither
owner-released nor operator-picked, `keep (recent, possibly in use)`; archive
duty, `archive first`, never a plain delete. Else a candidate:
- **low**, cheap to regenerate: stopped containers without volumes, dangling
images, unused networks, ended sessions' scratch and logs.
- **medium**, slow, rate-limited or networked to regenerate: unused tagged
images, build and package caches, clean merged worktrees.
- **high**, data loss or a broken run: volumes, stopped containers with
volumes, running unclaimed containers or stacks, dirty or unpushed
worktrees, unread reports, anything `unknown`.
## Step 4: propose
One table, biggest first: area, item, size, owner, risk, proposal, what
breaks if wrong. Below it reclaimable size per risk and every `keep` by
reason. Then `AskUserQuestion`:
1. `multiSelect: true`, up to four questions: `/tmp`, `Docker`, `Other
dirs`, `High risk` (every high-risk candidate); each option names size,
risk and worst case. Over four options, group by owner or risk or call
again; merge single items into one question: one-option questions fail.
Only ticks select, not an empty `Other` answer; nothing preselected.
2. `multiSelect: false`: `Execute: <n> items, <size> (Recommended)` naming
the ticked items' worst case, `Revise the selection` (repeats 1), `Abort`.
## Step 5: execute ## Step 5: execute
+66
View File
@@ -0,0 +1,66 @@
# Plan: inventory, owners, classes, proposal
## Step 1: inventory
Read-only, parallel, sized, only in the agent write scope (Claude Code:
`sandbox.filesystem.allowWrite`) and session scratch dirs, never another
user's files. Prefer project cleanup and teardown targets; obey raw-command
bans.
- **/tmp**: `pkgmgr gc --report --docker --root /tmp --root <write dir>`,
else `du -sh` per own entry; never system entries (`.*-unix`,
`systemd-private-*`, `ssh-*`, `tmux-*`, sockets).
- **Docker**, **worktrees**: read `docker.md` (its `⚠ Volumes` checklist
joins Step 4) and `worktrees.md` here when present.
- **Agent dirs**: pip, npm, pre-commit, act, gh, buildx caches; Ansible and
build temp dirs.
- **Council root** (`~/.local/state/agents-shared`): `archive/` only.
- **Register**: `council.py list --long`; `rasci.py artifacts`
(`kvb-org-artefacts`, `--ended` for candidates).
- **Queue**: `${CLAUDE_SKILL_DIR}/../kvb-org-queue-cleanup/scripts/cleanup.py
request`; go on meanwhile.
- **Live use**: `fuser` (exit 1 or 123: free), `lsof`, `ps -o
pid,etime,comm`; never full command lines or environments (credentials).
Sandboxed, an empty result proves nothing.
- **Archive duties**: memory or project rules requiring a copy before
deletion (logs, reports, generated maps).
## Step 2: ask the owners
Owner: register worker, path session id, worktree or compose project,
container label, open handle, else `unknown`. Once per local peer owning
unregistered candidates, `radio.py send call --to <peer>` the `ask.md` text;
go on meanwhile.
## Step 3: classify
First match wins: claimed by a peer, `keep`; in a register task not `done`,
`stopped` or `stale` (a branch merged into the default makes it
`stale`; an ended task's items are its worker's candidates), `keep (task <task>)`; a
running deploy, gate, test, swarm or build, `keep (running)`; a silent peer's,
`keep (no answer from <peer>)`, silence is not consent; sandboxed, touched
within 24 hours (`find -mmin -1440`; bfs fails on `-newermt`) and neither
owner-released nor operator-picked, `keep (recent, possibly in use)`; archive
duty, `archive first`, never a plain delete. Else a candidate:
- **low**, cheap to regenerate: stopped containers without volumes, dangling
images, unused networks, ended sessions' scratch and logs.
- **medium**, slow, rate-limited or networked to regenerate: unused tagged
images, build and package caches, clean merged worktrees.
- **high**, data loss or a broken run: volumes, stopped containers with
volumes, running unclaimed containers or stacks, dirty or unpushed
worktrees, unread reports, anything `unknown`.
## Step 4: propose
One table, biggest first: area, item, size, owner, risk, proposal, what
breaks if wrong. Below it reclaimable size per risk and every `keep` by
reason. Then `AskUserQuestion`:
1. `multiSelect: true`, up to four questions: `/tmp`, `Docker`, `Other
dirs`, `High risk` (every high-risk candidate); each option names size,
risk and worst case. Over four options, group by owner or risk or call
again; merge single items into one question: one-option questions fail.
Only ticks select, not an empty `Other` answer; nothing preselected.
2. `multiSelect: false`: `Execute: <n> items, <size> (Recommended)` naming
the ticked items' worst case, `Revise the selection` (repeats 1), `Abort`.
+4 -4
View File
@@ -21,10 +21,10 @@ coach.py --profile <same> show [--json]
Areas: `psyche`, `body`, `sleep`, `food`, `tasks`, `delegate`. Every coaching Areas: `psyche`, `body`, `sleep`, `food`, `tasks`, `delegate`. Every coaching
skill beyond this one is named `kvb-coach-<name>`. skill beyond this one is named `kvb-coach-<name>`.
`hooks/reminder.sh` triggers the short form at the first prompt of every full `hooks/reminder.sh` prints one fixed tip at the first prompt of every full
hour, once across all agents (stamped in `~/.claude/.coach-hours/`): at most hour, once across all agents (stamped in `~/.claude/.coach-hours/`), chosen
three lines, the most urgent area first, then the agent continues with the by the hour: sleep late, food at meal times, else moving. The agent passes
operator's request. it on in one line without loading this skill.
## Step 1: read the situation ## Step 1: read the situation
+7 -5
View File
@@ -9,8 +9,10 @@ mkdir -p "${hours}"
mkdir "${hours}/${hour}" 2>/dev/null || exit 0 mkdir "${hours}/${hour}" 2>/dev/null || exit 0
find "${hours}" -mindepth 1 -maxdepth 1 -type d ! -name "${hour}" -exec rmdir {} + find "${hours}" -mindepth 1 -maxdepth 1 -type d ! -name "${hour}" -exec rmdir {} +
cat <<'HINT' case "${hour##*T}" in
COACH HOUR: a new full hour began. Before answering the operator's request, 22 | 23 | 0[0-5]) tip="😴 Late: wind down, screens off soon, seven to nine hours of sleep." ;;
run the kvb-coach skill in its short form: at most three lines, the most 1[2-3] | 1[8-9]) tip="🥗 Meal time: a real meal with vegetables and protein, and a glass of water." ;;
urgent area first, then continue with the request. *) tip="🚶 Stand up, stretch neck, hips and back for two minutes, and drink a glass of water." ;;
HINT esac
printf 'COACH HOUR: open your answer with this one line for the operator, word for word, then continue with the request; load no skill for it:\n%s (More: /kvb-coach)\n' "${tip}"
+14 -2
View File
@@ -2,7 +2,8 @@
"""Report how much context agent sessions re-read per turn, from Claude Code's session transcripts. """Report how much context agent sessions re-read per turn, from Claude Code's session transcripts.
Args: Args:
--root: transcripts root, e.g. ~/.claude/projects (every */*.jsonl below). --root: transcripts root, e.g. ~/.claude/projects (every session transcript
*/*.jsonl and every subagent transcript */*/subagents/*.jsonl below).
--days: how many days back, one row per day, newest last. --days: how many days back, one row per day, newest last.
--threshold: a context size in tokens; per threshold the report adds the --threshold: a context size in tokens; per threshold the report adds the
share of turns above it and the share of context tokens above it. share of turns above it and the share of context tokens above it.
@@ -34,10 +35,21 @@ def fail(message: str) -> None:
sys.exit(2) sys.exit(2)
def transcripts(root: Path) -> list[Path]:
"""Args:
root: the transcripts root, e.g. ~/.claude/projects.
Returns:
Every session transcript <project>/<session>.jsonl and every subagent
transcript <project>/<session>/subagents/<agent>.jsonl below it.
"""
return [*root.glob("*/*.jsonl"), *root.glob("*/*/subagents/*.jsonl")]
def scan(root: Path, since: float) -> tuple[dict[str, tuple[str, int]], dict[str, int]]: def scan(root: Path, since: float) -> tuple[dict[str, tuple[str, int]], dict[str, int]]:
turns: dict[str, tuple[str, int]] = {} turns: dict[str, tuple[str, int]] = {}
compactions: dict[str, int] = {} compactions: dict[str, int] = {}
for path in root.glob("*/*.jsonl"): for path in transcripts(root):
if path.stat().st_mtime < since: if path.stat().st_mtime < since:
continue continue
with path.open(encoding="utf-8", errors="ignore") as handle: with path.open(encoding="utf-8", errors="ignore") as handle:
+6
View File
@@ -89,6 +89,12 @@ class TestCoachHour(unittest.TestCase):
self.assertIn("kvb-coach", self._run("2026-11-03T15")) self.assertIn("kvb-coach", self._run("2026-11-03T15"))
self.assertEqual(sorted(p.name for p in self.hours.iterdir()), ["2026-11-03T15"]) self.assertEqual(sorted(p.name for p in self.hours.iterdir()), ["2026-11-03T15"])
def test_the_hour_picks_one_fixed_tip_and_loads_no_skill(self):
tips = {hour: self._run(f"2026-11-03T{hour}").splitlines() for hour in ("23", "04", "12", "19", "09", "16")}
firsts = {hour: lines[1].split(" ", 1)[0] for hour, lines in tips.items()}
self.assertEqual(firsts, {"23": "😴", "04": "😴", "12": "🥗", "19": "🥗", "09": "🚶", "16": "🚶"})
self.assertTrue(all(len(lines) == 2 and "load no skill" in lines[0] for lines in tips.values()))
def test_a_binary_planted_on_the_inherited_path_never_runs(self): def test_a_binary_planted_on_the_inherited_path_never_runs(self):
planted = Path(self.tmp.name) / "planted" planted = Path(self.tmp.name) / "planted"
planted.mkdir() planted.mkdir()
+4 -1
View File
@@ -36,6 +36,9 @@ class TestContext(unittest.TestCase):
] ]
(self.root / "project").mkdir() (self.root / "project").mkdir()
(self.root / "project" / "session.jsonl").write_text("\n".join(lines) + "\n", encoding="utf-8") (self.root / "project" / "session.jsonl").write_text("\n".join(lines) + "\n", encoding="utf-8")
subagents = self.root / "project" / "session" / "subagents"
subagents.mkdir(parents=True)
(subagents / "agent-a1.jsonl").write_text(turn(self.today, "s1", 0) + "\n", encoding="utf-8")
def _run(self, *args: str) -> subprocess.CompletedProcess: def _run(self, *args: str) -> subprocess.CompletedProcess:
return subprocess.run( return subprocess.run(
@@ -52,7 +55,7 @@ class TestContext(unittest.TestCase):
) )
self.assertEqual( self.assertEqual(
(today["day"], today["turns"], today["tokens"], today["compactions"], today["over"]["300000"]), (today["day"], today["turns"], today["tokens"], today["compactions"], today["over"]["300000"]),
(self.today, 2, 450_100, 1, {"turns": 50, "tokens": 22}), (self.today, 3, 450_200, 1, {"turns": 33, "tokens": 22}),
) )
def test_usage_errors_exit_2(self): def test_usage_errors_exit_2(self):
+1 -1
View File
@@ -858,7 +858,7 @@ class TestGuard(unittest.TestCase):
self.assertEqual(hits, []) self.assertEqual(hits, [])
def test_the_agent_root_is_named_where_it_is_inventoried_or_mounted(self): def test_the_agent_root_is_named_where_it_is_inventoried_or_mounted(self):
self.assertIn("~/.local/state/agents-shared", (REPO_ROOT / "skills" / "kvb-cleanup" / "SKILL.md").read_text(encoding="utf-8")) self.assertIn("~/.local/state/agents-shared", (REPO_ROOT / "skills" / "kvb-cleanup" / "plan.md").read_text(encoding="utf-8"))
self.assertIn("~/.local/state/agents-shared.", (CLIENT / "offices.py").read_text(encoding="utf-8")) self.assertIn("~/.local/state/agents-shared.", (CLIENT / "offices.py").read_text(encoding="utf-8"))
mounts = (REPO_ROOT / "docs" / "requirements" / "003-operator-workbench.md").read_text(encoding="utf-8").split("- **Mounts**:", 1)[1].split("\n\n", 1)[0] mounts = (REPO_ROOT / "docs" / "requirements" / "003-operator-workbench.md").read_text(encoding="utf-8").split("- **Mounts**:", 1)[1].split("\n\n", 1)[0]
self.assertIn("`~/.local/state/agents-shared`", mounts) self.assertIn("`~/.local/state/agents-shared`", mounts)
+37 -4
View File
@@ -3,6 +3,7 @@
from __future__ import annotations from __future__ import annotations
import json import json
import re
import shutil import shutil
import subprocess import subprocess
import tempfile import tempfile
@@ -222,6 +223,35 @@ class TestSettingsRegistration(unittest.TestCase):
result = subprocess.run(["sh", "-c", gate["command"]], capture_output=True, check=False) result = subprocess.run(["sh", "-c", gate["command"]], capture_output=True, check=False)
self.assertEqual(result.returncode, 1) self.assertEqual(result.returncode, 1)
def test_a_hook_runs_its_script_as_main_from_cached_bytecode_and_keeps_its_exit_code(self):
(gate,) = self._hooks(self._patch(), "PreToolUse", "kvb-org-queue/scripts/queue.py")
script = Path(self.tmp.name) / "skills" / "kvb-org-queue" / "scripts" / "queue.py"
script.parent.mkdir(parents=True)
script.write_text("import sys\nprint(__name__, sys.argv[1:], sys.argv[0] == __file__)\nsys.exit(3)\n", encoding="utf-8")
runs = [subprocess.run(["sh", "-c", gate["command"]], capture_output=True, text=True, check=False) for _ in range(2)]
self.assertEqual([(run.returncode, run.stdout) for run in runs], [(3, "__main__ ['block'] True\n")] * 2)
self.assertEqual([path.name.split(".")[0] for path in (script.parent / "__pycache__").iterdir()], ["queue"])
def test_every_bash_gate_answers_under_the_cached_loader_as_it_does_started_directly(self):
data = self._patch()
(Path(self.tmp.name) / "skills").symlink_to(REPO_ROOT / "skills")
def answer(command: str, home: Path) -> tuple:
home.mkdir()
env = {"PATH": "/usr/bin:/bin", "HOME": str(home), "AGENTS_COUNCIL_ROOT": str(home / "council"), "XDG_STATE_HOME": str(home / "state")}
payload = json.dumps({"session_id": "s", "hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": "ls"}, "cwd": "/"})
done = subprocess.run(["sh", "-c", command], input=payload, cwd="/", env=env, capture_output=True, text=True, timeout=60, check=False)
return done.returncode, done.stdout.replace(str(home), "~"), done.stderr.replace(str(home), "~")
bash = [entry for entry in data["hooks"]["PreToolUse"] if "matcher" not in entry or "Bash" in entry["matcher"].split("|")]
gates = [re.search(r' ("[^"]+\.py") (\w+)$', hook["command"]) for entry in bash for hook in entry["hooks"] if "importlib" in hook["command"]]
self.assertEqual(len(gates), 4)
for n, gate in enumerate(gates):
with self.subTest(script=gate[1]):
cached = answer(gate.string, Path(self.tmp.name) / f"cached-{n}")
direct = answer(f"/usr/bin/python3 -I {gate[1]} {gate[2]}", Path(self.tmp.name) / f"direct-{n}")
self.assertEqual(cached, direct)
def test_news_hook_moves_to_radio(self): def test_news_hook_moves_to_radio(self):
base = Path(self.tmp.name) / "skills" base = Path(self.tmp.name) / "skills"
self.settings.write_text( self.settings.write_text(
@@ -243,14 +273,16 @@ class TestSettingsRegistration(unittest.TestCase):
encoding="utf-8", encoding="utf-8",
) )
data = self._patch() data = self._patch()
self.assertNotIn("codebase-memory@codebase-memory", data["enabledPlugins"]) self.assertIs(data["enabledPlugins"]["codebase-memory@codebase-memory"], False)
self.assertNotIn("codebase-memory", data["extraKnownMarketplaces"]) self.assertNotIn("codebase-memory", data["extraKnownMarketplaces"])
self.assertTrue(data["enabledPlugins"]["caveman@caveman"]) self.assertTrue(data["enabledPlugins"]["caveman@caveman"])
self.settings.write_text("{}", encoding="utf-8")
self.assertIs(self._patch()["enabledPlugins"]["codebase-memory@codebase-memory"], False)
def test_compact_window_is_set_once_and_never_overwritten(self): def test_compact_window_is_set_once_and_never_overwritten(self):
self.assertEqual(self._patch()["env"]["CLAUDE_CODE_AUTO_COMPACT_WINDOW"], "500000")
self.settings.write_text(json.dumps({"env": {"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "300000"}}), encoding="utf-8")
self.assertEqual(self._patch()["env"]["CLAUDE_CODE_AUTO_COMPACT_WINDOW"], "300000") self.assertEqual(self._patch()["env"]["CLAUDE_CODE_AUTO_COMPACT_WINDOW"], "300000")
self.settings.write_text(json.dumps({"env": {"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "500000"}}), encoding="utf-8")
self.assertEqual(self._patch()["env"]["CLAUDE_CODE_AUTO_COMPACT_WINDOW"], "500000")
def test_hooks_run_the_system_python_isolated_and_old_entries_move_to_it(self): def test_hooks_run_the_system_python_isolated_and_old_entries_move_to_it(self):
old = f'[ -f "{self.tmp.name}/skills/kvb-org-queue/scripts/queue.py" ] && python3 "{self.tmp.name}/skills/kvb-org-queue/scripts/queue.py" block' old = f'[ -f "{self.tmp.name}/skills/kvb-org-queue/scripts/queue.py" ] && python3 "{self.tmp.name}/skills/kvb-org-queue/scripts/queue.py" block'
@@ -266,7 +298,8 @@ class TestSettingsRegistration(unittest.TestCase):
with self.subTest(command=command): with self.subTest(command=command):
self.assertIn("/usr/bin/python3 -I ", command) self.assertIn("/usr/bin/python3 -I ", command)
self.assertNotRegex(command, r"(^|&& )python3 ") self.assertNotRegex(command, r"(^|&& )python3 ")
self.assertEqual(len(self._hooks(data, "PreToolUse", "kvb-org-queue/scripts/queue.py")), 1) (gate,) = self._hooks(data, "PreToolUse", "kvb-org-queue/scripts/queue.py")
self.assertIn("spec_from_file_location", gate["command"])
def test_reminders_run_the_system_bash_and_old_entries_move_to_it(self): def test_reminders_run_the_system_bash_and_old_entries_move_to_it(self):
old = f'bash "{self.tmp.name}/skills/kvb-dream/hooks/reminder.sh"' old = f'bash "{self.tmp.name}/skills/kvb-dream/hooks/reminder.sh"'
+22 -7
View File
@@ -29,7 +29,7 @@ BUDGET = REPO_ROOT / "scripts" / "budget.py"
SKILL_A = "---\nname: kvb-a\ndescription: >\n one two three\n---\n" SKILL_A = "---\nname: kvb-a\ndescription: >\n one two three\n---\n"
SKILL_B = "---\nname: kvb-b\ndescription: >\n four five\n---\n" SKILL_B = "---\nname: kvb-b\ndescription: >\n four five\n---\n"
NO_VALUE = "💰 value ?:? (cost 0/day; pass --value with evidence)" NO_VALUE = "💰 value ?:? (cost 0/day; pass --value with evidence)"
NEW_B = "💰 value ?:? (cost 0/day; pass --value with evidence; kvb-b new: all skills median 0 invocations/day)" NEW_B = "💰 value ?:? (cost 0/day; pass --value with evidence; kvb-b new: all skills median 0 invocations/day, 0 resident turns/day)"
CHEAP = "print('cheap')\n" CHEAP = "print('cheap')\n"
COSTLY = "data = list(range(2_000_000))\nprint(sum(data))\n" COSTLY = "data = list(range(2_000_000))\nprint(sum(data))\n"
LINE = re.compile( LINE = re.compile(
@@ -149,6 +149,7 @@ class TestTokens(GitRepo):
"evidence": None, "evidence": None,
"requests_per_day": 0, "requests_per_day": 0,
"invocations_per_day": {"kvb-b": 0}, "invocations_per_day": {"kvb-b": 0},
"resident_turns_per_day": {"kvb-b": 0},
"median_for_new": {"kvb-b": "all skills"}, "median_for_new": {"kvb-b": "all skills"},
}, },
}, },
@@ -194,13 +195,13 @@ class TestTokens(GitRepo):
result.stdout.splitlines(), result.stdout.splitlines(),
[ [
"💸 tokens 869 % (skills 13→113 tokens; listing 3→5 words)", "💸 tokens 869 % (skills 13→113 tokens; listing 3→5 words)",
"💰 value ?:? (cost 203/day; pass --value with evidence)", "💰 value ?:? (cost 333/day; pass --value with evidence)",
], ],
) )
self.assertEqual(result.returncode, 3) self.assertEqual(result.returncode, 3)
for value, line in ( for value, line in (
("4053", "💰 value 1:20 (cost 203/day, value 4053/day; 4053 tokens/day saved)"), ("4053", "💰 value 1:12 (cost 333/day, value 4053/day; 4053 tokens/day saved)"),
("50", "💰 value 4.1:1 (cost 203/day, value 50/day; 4053 tokens/day saved)"), ("50", "💰 value 6.7:1 (cost 333/day, value 50/day; 4053 tokens/day saved)"),
): ):
with self.subTest(value=value): with self.subTest(value=value):
result = self.tokens("--value", value, "--evidence", "4053 tokens/day saved") result = self.tokens("--value", value, "--evidence", "4053 tokens/day saved")
@@ -209,16 +210,30 @@ class TestTokens(GitRepo):
self.assertEqual( self.assertEqual(
found, found,
{ {
"quotient": "1:20", "quotient": "1:12",
"cost": 202.66, "cost": 332.66,
"value": 4053, "value": 4053,
"evidence": "e", "evidence": "e",
"requests_per_day": 10, "requests_per_day": 10,
"invocations_per_day": {"kvb-a": 2}, "invocations_per_day": {"kvb-a": 2},
"resident_turns_per_day": {"kvb-a": 13},
"median_for_new": {}, "median_for_new": {},
}, },
) )
def test_subagent_transcripts_count_and_an_invoked_skill_stays_resident(self):
subagent = self.base / "projects" / "project" / "session" / "subagents" / "agent-a1.jsonl"
subagent.parent.mkdir(parents=True)
lines = [assistant("s0", self.recent, ("u0", "kvb-a")), *(assistant(f"s{n}", self.recent) for n in range(1, 14))]
subagent.write_text("\n".join(lines) + "\n", encoding="utf-8")
self.write("skills/kvb-a/SKILL.md", SKILL_A.ljust(452, "y"))
found = json.loads(self.tokens("--json").stdout)["value"]
self.assertEqual(
(found["requests_per_day"], found["invocations_per_day"], found["resident_turns_per_day"]),
(2, {"kvb-a": round(1 / 7, 2)}, {"kvb-a": round(13 / 7, 2)}),
)
self.assertEqual(found["cost"], round(100 * (1 / 7 + 0.1 * 13 / 7), 2))
def test_new_skill_takes_its_category_median(self): def test_new_skill_takes_its_category_median(self):
self.write("skills/kvb-c-one/SKILL.md", skill_md("kvb-c-one", "one")) self.write("skills/kvb-c-one/SKILL.md", skill_md("kvb-c-one", "one"))
self.write("skills/kvb-c-two/SKILL.md", skill_md("kvb-c-two", "two")) self.write("skills/kvb-c-two/SKILL.md", skill_md("kvb-c-two", "two"))
@@ -231,7 +246,7 @@ class TestTokens(GitRepo):
result = self.tokens() result = self.tokens()
self.assertEqual( self.assertEqual(
result.stdout.splitlines()[1], result.stdout.splitlines()[1],
"💰 value ?:? (cost 202/day; pass --value with evidence; kvb-c-new new: kvb-c median 2 invocations/day)", "💰 value ?:? (cost 1872/day; pass --value with evidence; kvb-c-new new: kvb-c median 2 invocations/day, 167 resident turns/day)",
) )
self.assertEqual(result.returncode, 3) self.assertEqual(result.returncode, 3)