
claude-code-tools
Meta-tools for running Claude Code well: audit your permission allowlist, fix local toolchain gaps, analyze usage costs, and prune stale saved memories.
- GitHub stars
- 280
Install
/plugin install claude-code-tools@fin-2xRun it inside Claude Code after adding the marketplace with /plugin marketplace add intercom/2x-skills.
Contents
Discovered from sourceSkills 4
Audit Memory
Saved memories are point-in-time observations. Code moves, PRs merge, projects finish — and a memory that was true when written silently becomes a confidently wrong instruction to every future session. This skill verifies memories against reality and archives what no longer holds.
Never auto-fires — it archives user data, so it runs only when someone types /audit-memory.
Core guarantees
These are load-bearing. Violating any of them makes the skill untrustworthy:
- Absence of evidence is never evidence of staleness. A claim you cannot check is
NEEDS-<tool>,NOT-ATTEMPTEDorNOT-CHECKABLE— never stale, never offered for removal. A disconnected MCP must never turn valid memories into deletion candidates. Two mirrors of this also hold. Never report a check you skipped as a tool that was missing. And never over-apply it: a newer memory stating the old fact was removed is positive evidence, sufficient alone — an unreachable repo cannot demote it, because the evidence was never in the repo. - Archive before you touch anything, so nothing is unrecoverable. Memory files are not version-controlled and have no trash. Snapshot the original into the archive before any write or removal — claim removals, whole-file archiving,
MEMORY.mdpointer sync, andlastReviewedstamps alike. Removal does mean deleting the file; it is safe only because the verified snapshot precedes it. - Preferences are not claims.
type: feedbackandtype: usermemories are standing instructions. Never argue they are false — the user is the only authority on whether a preference still applies. - No writes outside the resolved roots. Only the memory root and archive root are ever written to.
- Name the root you actually audited, before showing findings, and never claim you honoured
CLAUDE_MEMORY_ROOTunless you read it. Auditing a different corpus than the caller meant is the worst failure here.
Step 1 — Resolve roots and discover projects
Run this exactly as written, as a single call. It resolves both roots and lists every project in one step.
The memory root resolves in this order: an explicit --root <path> argument, then CLAUDE_MEMORY_ROOT, then ~/.claude/projects. If the caller passed --root <path>, prefix the block with CLAUDE_MEMORY_ROOT='<path>' so both routes land in the same variable.
Single-quote it, and escape any single quote inside it by replacing each ' with '\''. Unquoted, a space or metacharacter splits the path; naively quoted, an apostrophe closes the quote early and the rest runs as shell. A path you cannot quote safely is one you refuse, not one you guess at.
Shell variables do not survive between Bash calls, so never split root resolution from the work that uses it, and never pass a root in as "$MEM_ROOT" from an earlier call — it will be empty, which is why this block reads the environment directly.
If this block runs and fails, stop and report the error — a nonexistent root, a permission error, a traceback. Never retry against $HOME/.claude/projects instead (guarantee 5).
Bash being unavailable is different — the block never runs, so CLAUDE_MEMORY_ROOT is unreadable and you cannot know whether the default root is the intended corpus. That run is read-only until the root is confirmed: report findings against ~/.claude/projects, say which root you used and that the environment was invisible, and make no write at all — no archive, no edit, no stamp — until the user confirms it. Findings can be discarded; an archive written against the wrong corpus cannot.
Never decode project directory names into filesystem paths. The encoding is lossy: -Users-me-src-claude-plugins could be src/claude-plugins or src/claude/plugins, because path separators and literal hyphens both become -. The authoritative cwd comes from the project's session transcripts, which is what this block reads.
If Bash is unavailable, do not stop — fall back to the tool-only path below. Sandboxes and eval harnesses routinely deny Bash, and a discovery step with no fallback turns that into a dead end.
python3 <<'PY'
import glob, json, os, re, subprocess, time
root = os.environ.get("CLAUDE_MEMORY_ROOT") or os.path.expanduser("~/.claude/projects")
# expanduser before resolving: --root is single-quoted, so a leading ~ reaches
# Python literally and would otherwise resolve against the cwd. realpath, not
# abspath, so a symlinked root cannot place the archive outside the resolved
# roots the no-external-writes guarantee is stated against.
root = os.path.realpath(os.path.expanduser(root))
archive = os.path.join(os.path.dirname(root), "memory-archive",
time.strftime("%Y-%m-%d"))
print("MEMORY_ROOT=" + root)
print("ARCHIVE_ROOT=" + archive)
print("SOURCE=" + ("CLAUDE_MEMORY_ROOT" if os.environ.get("CLAUDE_MEMORY_ROOT") else "default"))
if not os.path.isdir(root):
raise SystemExit("memory root does not exist: " + root)
for d in sorted(os.listdir(root)):
mem = os.path.join(root, d, "memory")
if not os.path.isdir(mem):
continue
# glob.escape the directory: a project dir holding [ ] * or ? would otherwise be
# read as a pattern and match the wrong memories, or none.
files = [f for f in glob.glob(glob.escape(mem) + "/*.md")
if os.path.basename(f) != "MEMORY.md"]
if not files and not os.path.exists(os.path.join(mem, "MEMORY.md")):
continue
cwd = None
for j in sorted(glob.glob(glob.escape(os.path.join(root, d)) + "/*.jsonl"),
key=os.path.getmtime, reverse=True)[:3]:
try:
for line in open(j):
o = json.loads(line)
if o.get("cwd"):
cwd = o["cwd"]
break
except Exception:
pass
if cwd:
break
# Skip harness debris only where it lives (a temp dir) and only on its actual
# shape: a name plus a "-" plus a generated suffix, e.g. skill-eval-4rscfuzs.
# Requiring that hyphen is what keeps a real repo named "skill-evaluator".
if cwd and re.match(r"(/private)?(/tmp|/var/folders/[^/]+/[^/]+/T)/", cwd) \
and re.search(r"/(trigger-eval|skill-eval|skill-eval-origin|pytest)-[A-Za-z0-9_]+/",
cwd + "/"):
continue
# Fall back to cwd itself: a readable working tree that is not a git repo (or a
# machine with no git) still lets file-path and grep claims be checked, and
# reporting repo: null there wrongly downgrades every one of them.
repo = None
if cwd and os.path.isdir(cwd):
try:
r = subprocess.run(["git", "-C", cwd, "rev-parse", "--show-toplevel"],
capture_output=True, text=True)
repo = r.stdout.strip() or cwd
except (OSError, subprocess.SubprocessError):
repo = cwd
# An index-only project is kept above on purpose, so files can be empty; a
# project with memories but no MEMORY.md is equally valid. Age off whatever
# exists rather than assuming either is present.
dated = list(files) + [f for f in [os.path.join(mem, "MEMORY.md")] if os.path.exists(f)]
newest = max((os.path.getmtime(f) for f in dated), default=None)
age = int((time.time() - newest) / 86400) if newest else None
print(json.dumps({"dir": d, "cwd": cwd, "repo": repo,
"files": len(files), "newest_age_days": age}))
PY
Fallback when Bash is denied
Read references/no-bash-fallback.md and follow it. It gives the tool-only equivalent of every discovery step, and the rule that a run which could not confirm its root stays read-only.
Then ask which projects to audit. List every project with its file count and newest-memory age; up to 16 fit in one AskUserQuestion call (4 questions × 4 options, multiSelect: true). Mark projects with repo: null as code claims not checkable so the choice is informed.
Skip the picker when there is nothing to choose — exactly one project discovered, or the user named one as an argument. Audit it and continue to Step 2.
It is also the only question asked before findings exist. Everything up to the first proposal is read-only, so never pause to ask whether to begin, to read the memories, or to proceed after discovery — that is how a run ends having audited nothing. Ask once you have something to decide on.
Step 2 — Fan out one subagent per selected project
Spawn one Agent per project, model: sonnet, concurrently, giving each the project's memory directory and its resolved repo path.
If a single project is selected and it holds fewer than ~10 memories, verify inline instead — at that size a subagent costs more than it saves. Read the brief and follow it yourself when you do. Its rules are about how to verify, not about being a subagent: skipping it is how an inline run reaches for NOT-CHECKABLE instead of naming the tool it needed.
Require this exact return shape:
{
"project": "<dir>",
"repo": "<path or null>",
"preferences": [
{"file": "feedback_x.md", "summary": "<one line, ≤90 chars>",
"age_days": 42, "mechanism": "ok" | "missing" | "unknown",
"mechanism_note": "<what is gone, if missing>"}
],
"claims": [
{"file": "project_y.md", "claim": "<the specific assertion>",
"verdict": "CONFIRMED" | "STALE" | "NEEDS-<tool>" | "NOT-ATTEMPTED" | "NOT-CHECKABLE",
"evidence": "<what was checked and found>",
"occurrences": ["<every exact line/substring in the file asserting this same fact>"],
"proposed_edit": "<exact text to remove — REQUIRED when verdict is STALE>"}
],
"archetype": {"project_y.md": "LIVING" | "JOURNAL" | "SNAPSHOT" | "NOTE"},
"index_issues": ["<MEMORY.md pointer with no file, or file with no pointer>"]
}
Instruct each subagent to:
Their brief lives in references/subagent-brief.md — read it and pass it to each subagent. It defines how to route by type, which checks are free, how to scope repo lookups, and when each verdict applies. Validate every report against it.
Validate every report before using it. Reject and re-ask any subagent that returns a STALE claim with a null or missing proposed_edit, or whose proposed_edit does not appear verbatim in the file. A stale claim with no removable text is a finding that will otherwise be silently dropped — the memory stays wrong and the summary implies it was handled. Also sanity-check age_days against the file's own mtime and prefer your own measurement; subagents have reported 0 for every file.
Where a needed MCP is not connected, offer once to connect it and re-run the affected subagents, rather than re-running the whole audit. Where verdicts are NOT-ATTEMPTED, offer to re-run those specific checks — the tool was there.
Step 3 — Preference pass
Merge preferences across projects and dedupe near-identical ones (the same rule often lives in several project directories) — show it once, apply the decision to every copy.
Skip anything already stamped metadata.lastReviewed unless its file changed since that date or its mechanism is now missing.
Present 10 per round as check-to-drop, using 3 multiSelect groups in a single AskUserQuestion call (4 + 3 + 3):
- Frame it as "check the ones to DROP". Options always start unselected, so an untouched round removes nothing — deletion must be a deliberate act.
- One line each: name, the ≤90-char summary, age, and
⚠ mechanism gone: <note>when applicable. - Never sort by age. Age does not predict staleness for preferences — the oldest rules are typically the most durable.
After each round, ask whether to continue.
On stopping, offer to stamp metadata.lastReviewed: <today> on every preference the user kept and saw, so the next run resumes instead of restarting. Ask first — once, naming the count and files. Stamping writes to files the user just chose to keep, and a file whose only instruction was "leave this alone" is the last place to spring a surprise write. Declining is fine; the next run simply re-asks. Snapshot stamped files like any other write.
Step 4 — Stale-claim pass
Report CONFIRMED and NOT-CHECKABLE counts as a summary only. Report the two tool buckets separately and never merged — they mean opposite things:
9 claims need an issue-tracker MCP (absent) — run
/mcp, then re-run. 4 claims went unchecked though the telemetry MCP was available — re-run those?
Offer only STALE claims for removal, 10 per round, same check-to-drop batching. One decision covers all of a claim's occurrences — never present the same fact twice, and never apply to one occurrence while leaving another. This holds even when the occurrences need different actions: correcting the body figure while removing a sentence elsewhere is still one approval that spells out what happens to each occurrence, never one approval per occurrence. Splitting it lets the user accept half and leave the file contradicting itself.
For a claim whose text is only partly wrong — a drifted count, a moved line number, a renamed file — offer correct alongside remove, and default to correct. Deleting a whole sentence because one number inside it aged throws away a still-valid pointer, and it is exactly these claims whose text is interleaved with verified content, making removal the most destructive option available.
Then, before writing anything, show the actual diffs for every checked claim and confirm once. If the caller already authorised the changes in the invocation ("archive anything stale, don't ask me"), that is the confirmation — still print the diffs, since they are the only record of what you changed, but do not stop for a second approval. Asking again after being told not to is how a pre-authorised run ends having done nothing. These are surgical edits inside files that run to thousands of words: removing a sentence can orphan a "see above", break a list, or strip the only context a neighbouring claim depended on. A checkbox cannot show that; a diff can. If a proposed removal would take verified content with it, say so and offer a narrower correction instead of the deletion.
Step 4b — Usefulness pass
Truth and usefulness are independent: a memory can be perfectly accurate and still be pure context tax. Read references/usefulness-pass.md before this pass — it holds the per-archetype offer for SNAPSHOT and JOURNAL, and the one condition on archiving a file whole. Then present the JOURNAL and SNAPSHOT files, 10 per round, check-to-act.
Open this pass with the corpus cost as a literal measured line, in this exact shape and even when the corpus is tiny:
Corpus: 125 memories, 41,800 words, ~60K tokens loaded every session.
A file count is not a size — words and an approximate token count are both required, and "2 memory files" answers a different question. Measure it; do not estimate from the file count alone. Every other number here is about one file; this is the only one that says what the whole corpus charges each session, and it is the reason the pass exists. Never act on a LIVING file here — open work is the one thing worth its context.
Leave RULE files to Step 3; usefulness of a preference is the user's call, not an archetype's.
Step 5 — Apply
Snapshot before every write, without exception — not just removals; a lastReviewed stamp counts too.
First, if MEMORY.md exists, snapshot it into the archive before the loop below, with step 1's command (it suffixes .<n> rather than overwriting, so a second same-day audit cannot destroy the true baseline). Do it even if you are not sure yet that you will edit it: the loop is per-memory-file, so it never covers the index, and that gap is the one snapshot runs actually miss. Check it exists — a project with memory files and no index is valid and step 1 admits it, so an unconditional snapshot aborts the apply phase on a missing source, after approval and before any real snapshot. With no index, say so and skip both this snapshot and step 4's sync; never create one, since this skill audits memories rather than authoring them.
Then, for every approved change, in this order:
-
Snapshot the current file to
$ARCHIVE_ROOT/<project-dir>/<filename>before touching it, with this command and notWrite:python3 - '<source file>' '<archive path>' <<'PY' import os, shutil, sys src, dst = sys.argv[1], sys.argv[2] os.makedirs(os.path.dirname(dst), exist_ok=True) for n in range(100): cand = dst if n == 0 else "%s.%d" % (dst, n) try: fd = os.open(cand, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600) except FileExistsError: continue with os.fdopen(fd, "wb") as out, open(src, "rb") as f: shutil.copyfileobj(f, out) print("SNAPSHOT=" + cand) break else: raise SystemExit("no free archive path for " + dst) PYSubstitute both paths literally (single-quoted,
'\''-escaped) — never a shell variable: they do not survive betweenBashcalls, and empty arguments fail the archive before any approved mutation.O_EXCLis why this is a command and not aWrite: it creates or fails, with no window between the two, so a snapshot can never land on an existing one. AGlob-then-Writecannot: two same-day audits can both see the path free, and the second overwrites the first's original with an already-edited copy. Use the path it prints; that copy is the snapshot, the only thing counted as one in the closing count. WithoutBashthis atomicity is unavailable:Readthe path first,Writeonly if absent, and say in the report that a concurrent audit could have raced it. -
Append to
$ARCHIVE_ROOT/manifest.json: source path, project, intended action (file-archivedorclaim-removed), the removed text, the verdict, the evidence that justified it, andoutcome: "pending". Setoutcometoappliedorrefusedonce step 3 resolves. The entry precedes the mutation, so one left atpendingrecords an intention, and a manifest read as a change log would report work that never happened. -
Apply —
Editto remove or correct an individual claim, covering every one of itsoccurrences. Remove the file from the corpus in exactly three cases, by this procedure and no other: confirm the step 1 snapshot exists and its contents match the file, thenrmthe file. That order is the whole safety property, so neverrmbefore confirming, and never re-write the file to the base archive name to "make sure" — that is the overwrite step 1 avoided, landing on an earlier run's original. Verify the snapshot step 1 wrote, at the suffixed path if it resolved a collision. WithoutBashyou cannotrmat all — followreferences/no-bash-fallback.md, which stubs the file and reports what remains. The three cases: every claim in it is stale, the user dropped the whole preference, or the user approved archive whole in the usefulness pass. For an approved compress to outcome, overwrite the body and keep the file, preservingnameand the wholemetadata:block exactly — that is what the memory system parses. Rewritedescriptionto match the new body and show it in the diff: it is the line recall surfaces, so carrying the old one forward leaves the file describing content it no longer holds — the rot the compression was meant to end. Where a compression supersedes queued edits on the same file, fold those corrected facts in so nothing regresses. -
Sync
MEMORY.md(already snapshotted above) — remove the pointer line for any archived file, and correct the hook line for any file whose claim you changed, whenever that hook was among the claim'soccurrences. Archiving is not the only edit that dates the index: correcting a figure in the body while its hook still asserts the old one leaves the index contradicting the file it points at, and the hook is what recall surfaces first. A pointer to a missing file is worse still than the stale memory was. -
Re-scan each edited file for the fact you just removed — whole file, frontmatter included. A surviving copy means the file now contradicts itself, which is worse than the original staleness. Fix it in the same pass, or report it explicitly as unresolved; never leave it silent.
Leave dangling [[wiki-links]] alone — an unmatched link is valid, marking something worth writing later. Report them; do not repair them.
Count what happened, not what you attempted. Check the result of every write, and never skip one because you expect it to be refused — a predicted refusal is not a result, and an environment that blocked the last write may allow this one. Attempt it, then report what actually happened. One refusal does not mean the next was refused too — a later Write can succeed after an Edit was blocked, and treating the first denial as final reports the corpus untouched when it is not. List exactly which writes landed and which were refused. Reporting Files touched: 0 after a write succeeded is worse than the staleness you set out to fix: the user will trust the corpus is unchanged and never look again.
Finally, verify the archive is a complete restore source: every file this run modified or removed must have a snapshot. Count step 1's memory-file copies and nothing else. manifest.json is not a snapshot — counting it lets a run that changed two files report "2 snapshots" and look 1:1 covered while one has no restore point, exactly the failure this check exists to catch. Print both numbers on one line — Corpus files changed: 3 / Snapshots written: 3 — never as narrative prose, and name the first one corpus so it is unambiguous whether archive writes count. When they differ, give the reason on the same line — Corpus files changed: 0 / Snapshots written: 2 (both source edits refused). A mismatch is not automatically a fault — snapshotting then failing to edit leaves exactly this shape — but say so loudly: a partial archive invites a restore that silently leaves edits in place.
Close with counts: verified, archived, claims removed, claims corrected, files compressed, the two tool buckets kept apart (absent vs unchecked), the archive path, and the one-line restore command. State plainly anything you could not complete — a dropped finding is worse than one never made, because the summary implies it was handled.
Response Style
Narration compounds in a workflow this long. Present the picker, batches, diffs and counts directly — skip "Now I will…", "Let me…", and restating a step before doing it. While subagents run, say nothing until something is actionable or a report contradicts itself.
Guardrails
- Never write outside
$MEM_ROOTand$ARCHIVE_ROOT, and never write through a symlink: resolve each target to its real path first, and if that lands outside either root, skip the file and report the skip. Resolving the roots does not resolve a symlinked file inside them. - Never
rma memory file until its archive snapshot exists and its contents match — the snapshot is what makes the removal reversible, so no snapshot means no removal. - Never mark a claim stale on absent evidence.
- Never truth-check a
feedbackorusermemory. - Never edit
CLAUDE.md,.claude/rules/, or any repo file — this skill audits saved memories only. - Never act on a
STALEclaim whoseproposed_edityou could not match verbatim in the file. - Never remove one occurrence of a fact while leaving another standing.
- Never report an unattempted check as a missing tool.
- If zero projects have memories, say so and stop.
Claude Code Cost Analysis
A framework and ready-to-use query shapes for analyzing Claude Code usage costs across a team or org.
Prerequisites: you need Claude Code telemetry
Claude Code can export usage as OpenTelemetry metrics and events (CLAUDE_CODE_ENABLE_TELEMETRY=1 plus an OTLP endpoint — see the Claude Code monitoring docs). Point that export at an observability backend (Honeycomb, Datadog, an OTLP collector into a warehouse, etc.). This skill analyzes that data.
The example queries in references/queries.md are written for Honeycomb (environment/dataset names are placeholders — substitute wherever you send telemetry). The analysis dimensions and cost formulas are backend-agnostic — the same shapes translate to any store that has per-api_request rows with token counts, cost_usd, model, and session.id.
A few attribute names in the examples (user.email, speed, skill.name, normalized_file_path) are enrichments that depend on your telemetry pipeline and Claude Code version — verify column names against your own data (get_dataset_columns or the equivalent) before relying on them. Numeric fields are sometimes stored as strings; cast with FLOAT(...) before aggregating (see the query examples).
Analysis Dimensions
Each dimension answers a different question. Run whichever are relevant — there is no required order, though broader dimensions provide context for narrower ones.
| Dimension | Question Answered | Query Section |
|---|---|---|
| Model mix | Which models account for what cost? | references/queries.md Section 1 |
| Session economics | Where in sessions does cost accumulate? | Section 2 |
| Token types | Cache writes vs reads vs output share? | Section 3 |
| Tool result sizes | Which tools bloat the context? | Section 4 |
| Compaction | Are sessions hitting context limits? | Section 5 |
| Per-user profiles | Who are the heaviest users and why? | Section 6 |
| Instructions & skills | How much do CLAUDE.md/rules/skills cost? | Section 7 |
| Command-level waste | Which specific commands are wasteful vs bundled with real work? | references/command-attribution.md |
Apply cost formulas from references/cost-model.md when computing dollar estimates from token counts.
Illustrative Findings
These are shape-of-the-problem findings from one large deployment — useful to calibrate expectations, not ground truth for your org. Always verify against fresh queries against your own data.
Cost distribution
| Dimension | Typical finding |
|---|---|
| Model dominance | The most capable model tends to dominate cost far out of proportion to its share of calls |
| Session length | A minority of long sessions (turns 100+) can account for the majority of that model's cost |
| Token type shares | Cache write ~47%, cache read ~44%, output ~9% of weighted cost |
| Caching savings | Prompt caching typically cuts the bill ~80% vs fully uncached input |
| Instruction overhead | CLAUDE.md, rules, and skills are collectively a small fraction (~1%) of total spend |
Session turn phases
| Phase | Turns | Driver |
|---|---|---|
| Cache creation | 0-3 | System prompt + instructions written to cache |
| Steady state | 4-50 | Caching working well — lowest per-call cost |
| Context growth | 50-99 | Cache reads climbing as context accumulates |
| Long-session tail | 100+ | Large accumulated context re-read every turn |
Tool result sizes (typical ranges)
| Category | Avg/call | Examples |
|---|---|---|
| Screenshots | 100-500 KB | browser/screenshot tools |
| Search results | 10-30 KB | search MCP tools |
| Database results | 5-10 KB | SQL / log query tools |
| File reads | 3-7 KB | Read tool (very high volume) |
Context window behavior
- A small fraction of sessions trigger auto compaction.
- The most expensive sessions rarely compact — they grow to a large context and stay just below the window limit.
- Sessions on smaller context windows compact more often and cost far less per call than sessions on the largest window with equivalent workloads.
Key Analysis Patterns
Matched session comparison
The most compelling way to demonstrate context-size impact on cost is finding two sessions with similar API-call counts but different context behaviors — one with high average cache_read (bloated, likely on the largest window) and one low (lean, compacting or on a smaller window). The per-session query (Section 6a adapted to break down by session.id) surfaces these pairs.
User segmentation by context usage
Classify users by what % of their calls exceed a large cache_read threshold (Section 6a, calls_over_200k field):
- 0% over threshold — never needs the largest context, would work on a smaller window
- 1-10% — rarely needs it, benefits most from proactive compaction
- 60%+ — genuinely needs the largest context (investigate what tools drive it via Section 6b)
Important Caveats
Quality vs cost tradeoff: Cost optimizations (model downshift, aggressive compaction, smaller context windows) may degrade output quality. Measure quality objectively before changing configuration. Cost savings mean nothing if the tool becomes less useful.
Caching IS helping: Prompt caching reduces the bill substantially vs uncached input. The remaining cost is driven by the volume of cached tokens, not by caching being inefficient.
Instructions are a small share: CLAUDE.md files, rules, and skills are a small fraction of total spend. The real cost drivers are session length and context accumulation from tool results.
Turn-counts overcount command-level waste: a wasteful command (polling, re-auth, a bare sleep, a no-op) bundled into a turn that also does real work bills cache-read for that turn regardless — the marginal waste is close to zero. Classifying "turns containing pattern X" as waste massively overcounts. Separate standalone waste from bundled work by inspecting the actual command strings, and always back a dollar figure with atoms → examples → a reproducible query → an independent cross-check. See references/command-attribution.md.
Automated eval/test traffic pollutes usage totals: if you (or your telemetry pipeline) run automated eval or regression suites through Claude Code, that traffic is not real engineer usage. Tag or otherwise identify it in your export and exclude it from normal cost/context/compaction analysis; run a separate, intentionally-scoped query when you want to measure what the eval suite itself costs.
Generating Reports
Capture findings in markdown reports. See references/report-templates.md for standard structures. Name files {report-type}-{YYYY-MM-DD}.md.
Reference Files
references/queries.md— Example Honeycomb queries organized by analysis dimension. Load when composing a query for a specific analysis dimension.references/cost-model.md— Token pricing ratios, per-call/per-session cost formulas, caching economics. Load when a finding needs a dollar estimate, not just a raw count.references/report-templates.md— Standard report structures for each analysis type. Load before writing up findings.references/column-gotchas.md— Data-quality gotchas specific to cost analysis. Load before trusting a cost or sequence column you haven't queried before.references/command-attribution.md— Attributing cost to specific command patterns (waste vs bundled with real work). Load when classifying whether a costly command is standalone waste or bundled with real work.
Scripts
scripts/compute_percentiles.py— Compute p10/p25/p50/p75/p90/p99 from per-user query result sets
Permissions Analyzer
The mechanical scan of session history for frequently-approved commands is a job for Claude Code's
built-in /fewer-permission-prompts skill and permission auto mode (https://code.claude.com/docs/en/permissions).
This skill adds the layer neither provides: an opinionated safety filter plus a guarded
write into the user's global ~/.claude/settings.json. The built-in scan does not apply the RED
override below, so it can auto-allow commands this skill would reject — this skill applies the filter.
Modes
Pick the mode from the argument after /permissions-analyzer:
disable(oroff,stop,mute) — silence the proactive suggestion nudge. Runtouch ~/.claude/.disable-permissions-analyzer-suggestions, confirm the tips are off for all sessions, and mention/permissions-analyzer enableturns them back on. Do not run the vet-and-merge flow.enable(oron) — re-enable the nudge. Check whether~/.claude/.disable-permissions-analyzer-suggestionsexists, runrm -f ~/.claude/.disable-permissions-analyzer-suggestions, then confirm — say the suggestions are back on if the marker existed, or that they were never disabled if it did not. Do not run the vet-and-merge flow.- No argument (default) — run the vet-and-merge flow below.
The marker only governs the proactive suggestions; the flow is always available by running /permissions-analyzer with no argument.
Vet-and-merge flow
The goal: get safe, high-frequency commands onto the auto-allow list without letting anything that can execute arbitrary code slip through.
- Get candidate commands. Prefer the built-in scan — point the user at
/fewer-permission-prompts, which mines their session history and proposes an allowlist. Also accept a list the user pastes or the entries already in theirpermissions.allow. For users who want prompts gone entirely rather than command-by-command, mention permission auto mode as the broader option. With no candidates supplied and nothing to review, do not fabricate a classified list — route the user to/fewer-permission-promptsfirst, then vet what it returns. - Audit what the built-in already wrote, and strip RED. The built-in scan writes to the project
.claude/settings.jsonallowlist without applying the RED override. When the user has already run it, read that allowlist (and the user's~/.claude/settings.json), identify any RED entries, and — on the same explicit confirmation the write path requires — remove them from the allowlist. Flagging alone is not enough: a RED rule the built-in auto-allowed stays active until it is removed. - Classify each candidate into GREEN / YELLOW / RED using
references/safety-tiers.md. The RED override is the whole point of this skill — see below. - Present grouped by tier in a table before asking for confirmation.
- Merge the safe ones into
~/.claude/settings.jsonon explicit confirmation.
Read references/safety-tiers.md first
Classification rules and the permission syntax table live there. Two things matter most:
- The RED override. Anything that can execute arbitrary code — directly or via
run/exec/startsubcommands — is RED, even if the same tool is a "package manager" or "build tool".npm,npx,uv,bundle,pipx,bunx,deno,miseand bare interpreters (bash,python,node,ruby) are never auto-allow candidates. - Read-only is not "looks read-only". A linter is GREEN only when it cannot mutate files (
eslintwithout--fix,rubocopwithout-A/-a).
references/security-rationale.md covers the threat model (prompt injection, supply chain, side effects) — cite it when a user pushes back on a RED.
Constraints:
- Present the classified commands grouped by safety tier in a table before asking for confirmation.
- Dedup against the target file — the user's global
~/.claude/settings.jsonpermissions.allow. Skip a command only if it is already allowed there; a command being present in the project.claude/settings.jsonallowlist is not a reason to skip promoting it to the global allowlist. - Never write to
~/.claude/settings.jsonwithout explicit user confirmation viaAskUserQuestion. Show the diff first. - When merging accepted patterns into
permissions.allow, preserve every other key insettings.json— surgical merge, never a full-file overwrite. - Back up the file before attempting to repair a malformed
settings.json. - Use the Permission Syntax table in
safety-tiers.mdfor rule format — don't improvise patterns.
Resources
references/safety-tiers.md— Classification rules, RED override, permission syntaxreferences/security-rationale.md— Threat model and defense layers
Tool Misses
Scan recent Claude Code sessions for tool failures — missing commands and BSD/GNU incompatibilities — then fix them with Homebrew and record availability in CLAUDE.md.
Response Style
Skip narration and transitional commentary. Run each step, then present the findings or ask the user directly. Do not preface tool calls with sentences like "Now I'll run the scanner" or "Let me check whether Homebrew is installed", and do not paraphrase script output the user can already see — show the tables and the questions, nothing else.
Workflow
Step 0: Handle enable/disable arguments
This skill accepts an optional argument that controls its companion PostToolUse
hook (suggest-tool-misses.sh), which nudges the user toward this skill when a
tool failure is detected in Bash output. The hook reads a persistent marker file
at ~/.claude/.disable-tool-misses-hook and stays silent whenever it exists.
Dispatch on the argument before doing anything else:
off,disable,stop,mute, orsilence→ silence the hook:
Confirm suggestions are off until re-enabled withtouch ~/.claude/.disable-tool-misses-hook/tool-misses on, then STOP (do not run a scan).on,enable,start, orunmute→ re-enable the hook:
Confirm suggestions are back on, then STOP (do not run a scan).rm -f ~/.claude/.disable-tool-misses-hookstatus→ report whether the hook is on or off:
Report the result, then STOP.test -f ~/.claude/.disable-tool-misses-hook && echo "off" || echo "on"- No argument,
scan, or anything else → proceed to Step 1.
Step 1: Detect tool misses
Run the scanner script against recent session transcripts:
python3 ${CLAUDE_PLUGIN_ROOT}/skills/tool-misses/scripts/detect-tool-misses.py
This scans ~/.claude/projects/*/*.jsonl files from the last 14 days. It looks at
Bash tool_use + tool_result pairs and matches error output against two pattern sets:
- Missing tools:
command not founderrors - Wrong version / incompatibility: BSD vs GNU errors (e.g.,
grep -Pfailing,sed -isyntax differences,find -printfnot supported)
Output is JSON with missing_tools[], wrong_version_tools[], and scan_summary{}.
If the script finds no misses, report that and stop.
Step 2: Check current state
For each detected tool, check whether it has already been resolved:
command -v <tool> # Is it installed now?
command -v g<tool> # Is the GNU version available?
brew --prefix 2>/dev/null # Is Homebrew installed?
Categorize each tool as: still missing, now installed but not in CLAUDE.md, or fully resolved.
Step 3: Look up fixes
Consult references/tool-database.md for each detected tool to find:
- The correct Homebrew formula
- The g-prefix command name (for GNU tools)
- Guidance text for CLAUDE.md
For tools not in the database, note them as "unknown — manual resolution needed".
Step 4: Present report
Show the findings in tables grouped by status:
## Missing Tools (not currently installed)
| Tool | Error | Homebrew Formula | Occurrences |
|------|-------|------------------|-------------|
| filterdiff | command not found | patchutils | 3 |
## BSD/GNU Incompatibilities
| Tool | Error Pattern | Fix | g-prefix |
|------|---------------|-----|----------|
| grep | invalid option -- P | brew install grep | ggrep |
## Already Resolved (installed since the error)
| Tool | Status |
|------|--------|
| jq | Now installed |
## GNU Tools Available but Not in CLAUDE.md
| Tool | g-prefix | Formula |
|------|----------|---------|
| gsed | gsed | gnu-sed |
Only show sections that have entries. If everything is resolved, say so and skip to Step 8.
If the scanner output includes ignored_tools, mention how many were skipped:
(3 previously dismissed tools hidden — edit ~/.claude/tool-misses-ignored.json to reset)
Step 5: Prompt for action — per tool
Present each detected tool individually for the user to decide. For each tool, use AskUserQuestion with these options:
- Install + add to CLAUDE.md (Recommended) — Install via Homebrew and record in CLAUDE.md
- Install only — Install but don't modify CLAUDE.md
- CLAUDE.md only — Already installed, just add the CLAUDE.md entry
- Dismiss permanently — Not needed; hide from future scans
If a tool has no known Homebrew formula, adjust options to only show "Dismiss permanently" and "Skip for now".
Dismiss behavior: When the user dismisses a tool, add it to ~/.claude/tool-misses-ignored.json:
{
"ignored": ["qmd", "init_common"],
"notes": {
"qmd": "Dismissed 2026-02-08 — short-term experiment",
"init_common": "Dismissed 2026-02-08 — shell function, not a tool"
}
}
Read the file first (or start with empty {"ignored":[], "notes":{}}) and merge.
The scanner automatically filters out tools in this list on future runs.
Step 6: Install tools
For each tool the user approved for installation:
brew install <formula>
After each install, verify it worked:
command -v <tool> && echo "OK" || echo "FAILED"
If a GNU tool was installed, also verify the g-prefix command:
command -v g<tool> && echo "OK" || echo "FAILED"
Report any install failures and continue with the rest.
Step 7: Update CLAUDE.md
Add a ## Tool Availability (macOS) section to ~/.claude/CLAUDE.md (global config,
since these are system-wide tools). Follow these rules:
- Consult
references/claude-md-templates.mdfor entry format - Show proposed additions before writing — never write without confirmation
- Don't duplicate entries that already exist in CLAUDE.md
- If the section already exists, append new entries to it
- If the file doesn't exist, create it with just the tool availability section
Read the current file first:
cat ~/.claude/CLAUDE.md 2>/dev/null || echo ""
Show the proposed changes as a diff-style preview before applying.
Step 8: Summarize
Show a final summary:
## Summary
Installed: filterdiff (patchutils), rg (ripgrep)
CLAUDE.md: Added 3 entries to ~/.claude/CLAUDE.md
- GNU grep available as ggrep
- GNU sed available as gsed
- filterdiff available (patchutils)
Dismissed: qmd, init_common (won't appear in future scans)
No action needed: jq (already installed and in CLAUDE.md)
Error Handling
No session files found:
- Check if
~/.claude/projects/exists - Suggest the user has a new install or cleared history
- Offer to scan a custom path
Homebrew not installed:
- Warn that brew is required for installation
- Still offer to update CLAUDE.md with manual install instructions
- Provide the Homebrew install command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Script errors:
- If the Python script fails, show the error and suggest running it manually
- Fall back to a simpler scan if needed
Additional Resources
references/tool-database.md— Complete error pattern → Homebrew formula mappingsreferences/claude-md-templates.md— Templates for CLAUDE.md entriesscripts/detect-tool-misses.py— Session scanner script
Hooks 2
Sponsors
Details
- Marketplace
- intercom/2x-skills
- Source
- plugins/claude-code-tools
- Category
- Community