intercom avatar

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-2x

Run it inside Claude Code after adding the marketplace with /plugin marketplace add intercom/2x-skills.

Contents

Discovered from source

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

  1. Absence of evidence is never evidence of staleness. A claim you cannot check is NEEDS-<tool>, NOT-ATTEMPTED or NOT-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.
  2. 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.md pointer sync, and lastReviewed stamps alike. Removal does mean deleting the file; it is safe only because the verified snapshot precedes it.
  3. Preferences are not claims. type: feedback and type: user memories are standing instructions. Never argue they are false — the user is the only authority on whether a preference still applies.
  4. No writes outside the resolved roots. Only the memory root and archive root are ever written to.
  5. Name the root you actually audited, before showing findings, and never claim you honoured CLAUDE_MEMORY_ROOT unless 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:

  1. Snapshot the current file to $ARCHIVE_ROOT/<project-dir>/<filename> before touching it, with this command and not Write:

    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)
    PY
    

    Substitute both paths literally (single-quoted, '\''-escaped) — never a shell variable: they do not survive between Bash calls, and empty arguments fail the archive before any approved mutation.

    O_EXCL is why this is a command and not a Write: it creates or fails, with no window between the two, so a snapshot can never land on an existing one. A Glob-then-Write cannot: 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. Without Bash this atomicity is unavailable: Read the path first, Write only if absent, and say in the report that a concurrent audit could have raced it.

  2. Append to $ARCHIVE_ROOT/manifest.json: source path, project, intended action (file-archived or claim-removed), the removed text, the verdict, the evidence that justified it, and outcome: "pending". Set outcome to applied or refused once step 3 resolves. The entry precedes the mutation, so one left at pending records an intention, and a manifest read as a change log would report work that never happened.

  3. Apply — Edit to remove or correct an individual claim, covering every one of its occurrences. 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, then rm the file. That order is the whole safety property, so never rm before 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. Without Bash you cannot rm at all — follow references/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, preserving name and the whole metadata: block exactly — that is what the memory system parses. Rewrite description to 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.

  4. 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's occurrences. 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.

  5. 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_ROOT and $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 rm a 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 feedback or user memory.
  • Never edit CLAUDE.md, .claude/rules/, or any repo file — this skill audits saved memories only.
  • Never act on a STALE claim whose proposed_edit you 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.

DimensionQuestion AnsweredQuery Section
Model mixWhich models account for what cost?references/queries.md Section 1
Session economicsWhere in sessions does cost accumulate?Section 2
Token typesCache writes vs reads vs output share?Section 3
Tool result sizesWhich tools bloat the context?Section 4
CompactionAre sessions hitting context limits?Section 5
Per-user profilesWho are the heaviest users and why?Section 6
Instructions & skillsHow much do CLAUDE.md/rules/skills cost?Section 7
Command-level wasteWhich 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

DimensionTypical finding
Model dominanceThe most capable model tends to dominate cost far out of proportion to its share of calls
Session lengthA minority of long sessions (turns 100+) can account for the majority of that model's cost
Token type sharesCache write ~47%, cache read ~44%, output ~9% of weighted cost
Caching savingsPrompt caching typically cuts the bill ~80% vs fully uncached input
Instruction overheadCLAUDE.md, rules, and skills are collectively a small fraction (~1%) of total spend

Session turn phases

PhaseTurnsDriver
Cache creation0-3System prompt + instructions written to cache
Steady state4-50Caching working well — lowest per-call cost
Context growth50-99Cache reads climbing as context accumulates
Long-session tail100+Large accumulated context re-read every turn

Tool result sizes (typical ranges)

CategoryAvg/callExamples
Screenshots100-500 KBbrowser/screenshot tools
Search results10-30 KBsearch MCP tools
Database results5-10 KBSQL / log query tools
File reads3-7 KBRead 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 (or off, stop, mute) — silence the proactive suggestion nudge. Run touch ~/.claude/.disable-permissions-analyzer-suggestions, confirm the tips are off for all sessions, and mention /permissions-analyzer enable turns them back on. Do not run the vet-and-merge flow.
  • enable (or on) — re-enable the nudge. Check whether ~/.claude/.disable-permissions-analyzer-suggestions exists, run rm -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.

  1. 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 their permissions.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-prompts first, then vet what it returns.
  2. Audit what the built-in already wrote, and strip RED. The built-in scan writes to the project .claude/settings.json allowlist 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.
  3. Classify each candidate into GREEN / YELLOW / RED using references/safety-tiers.md. The RED override is the whole point of this skill — see below.
  4. Present grouped by tier in a table before asking for confirmation.
  5. Merge the safe ones into ~/.claude/settings.json on 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/start subcommands — is RED, even if the same tool is a "package manager" or "build tool". npm, npx, uv, bundle, pipx, bunx, deno, mise and 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 (eslint without --fix, rubocop without -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.json permissions.allow. Skip a command only if it is already allowed there; a command being present in the project .claude/settings.json allowlist is not a reason to skip promoting it to the global allowlist.
  • Never write to ~/.claude/settings.json without explicit user confirmation via AskUserQuestion. Show the diff first.
  • When merging accepted patterns into permissions.allow, preserve every other key in settings.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.md for rule format — don't improvise patterns.

Resources

  • references/safety-tiers.md — Classification rules, RED override, permission syntax
  • references/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, or silence → silence the hook:
    touch ~/.claude/.disable-tool-misses-hook
    
    Confirm suggestions are off until re-enabled with /tool-misses on, then STOP (do not run a scan).
  • on, enable, start, or unmute → re-enable the hook:
    rm -f ~/.claude/.disable-tool-misses-hook
    
    Confirm suggestions are back on, then STOP (do not run a scan).
  • status → report whether the hook is on or off:
    test -f ~/.claude/.disable-tool-misses-hook && echo "off" || echo "on"
    
    Report the result, then STOP.
  • 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 found errors
  • Wrong version / incompatibility: BSD vs GNU errors (e.g., grep -P failing, sed -i syntax differences, find -printf not 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.md for 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 mappings
  • references/claude-md-templates.md — Templates for CLAUDE.md entries
  • scripts/detect-tool-misses.py — Session scanner script

Sponsors

Details

Marketplace
intercom/2x-skills
Source
plugins/claude-code-tools
Category
Community

More from intercom/2x-skills

All 7