convez.ai
PluginProdutividadeAvançado
justinstimatze

Basanite — Detector de Tiques Vocabulares em Claude Code

justinstimatze/basanite

Detecta e corrige tiques vocabulares obsessivos em saídas de código

Ver no GitHub
InicialPluginScore · de 0 a 100

Ferramenta determinística local que detecta repetições lexicais (vocabulary tics) em sessões do Claude Code, medindo desvio de frequência em transcritos JSONL e injetando alternativas ranqueadas por especificidade. Sem LLM no caminho padrão, com suporte opcional a julgamento semântico para distinguir termos de arte de diluidores de linguagem.

Instalação

$npx convez-ai justinstimatze/basanite

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
—
Issues abertas
2
Contribuidores
1

Casos de uso

  • Melhorar qualidade e diversidade lexical de prompts iterativos em Claude Code
  • Identificar termos sobreutilizados que perdem impacto semântico ao longo de sessões
  • Ranquear alternativas mais específicas via escadas de WordNet sem custo de LLM

Veredito

Ferramenta altamente especializada e bem arquitetada para quem usa Claude Code intensivamente e busca melhorar a qualidade estilística de prompts iterativos. Exige familiaridade com CLI e integração de hooks, mas compensa com análise determinística eficiente e sem dependência de LLM no fluxo principal.

README

A tradução para o português deste README ainda está na fila.

basanite

ci

A deterministic, local tool — no LLM in the default path — that detects vocabulary tics in your Claude Code sessions' output — words the model reaches for reflexively (load-bearing, spine, …) until overuse debases them. It measures frequency drift over the JSONL transcripts, then injects awareness of each tic, plus a ranked ladder of alternatives, at turn start. A fenced LLM judge handles the one judgment the deterministic stack can't — telling a term of art from a dilutable tic — and runs by default when an API key is configured (it falls back to deterministic without one).

Basanite is the dark stone an assayer streaks a sample against to judge it — a touchstone. Design rationale, including what was deliberately left out, lives in DESIGN.md.

Commands

basanite scan            # rank rising lemmas: recent window vs trailing baseline
basanite trend <lemma>…  # weekly rate per lemma — the effectiveness check
basanite ladder <word>…  # specificity ladder per sense, weakest → strongest
basanite vet <word>…     # judge candidates against your own past sentences
basanite report          # full pipeline (scan→vet→ladder) → state file, ~1 min
                         #   judges out terms of art by default; --judge=false for deterministic-only
basanite refresh         # regenerate the state file if stale (SessionStart entry)
basanite hook            # UserPromptSubmit entry: inject the report, ~4 ms
basanite version

scan flags: -recent 7 / -baseline 14 (window sizes in days), -top 25, -min 5 (minimum recent count), -ratio 2.0 (minimum rate ratio), -dir ~/.claude/projects.

Setup

make install                                      # version comes from git describe
scripts/fetch-data.sh ~/.local/share/basanite     # data assets (see Data below)
basanite report                                   # build the first state file

Pass the fetch script a real path (as above) rather than letting it default to ./data — the default only works when you run basanite from the checkout, since ./data is resolved against the current directory.

Then register the hook in ~/.claude/settings.json, using the absolute binary path — hooks run in whatever environment Claude Code was launched from, which may not have your Go bin directory on PATH:

{"hooks": {"UserPromptSubmit": [{"hooks": [{"type": "command", "command": "/home/you/go/bin/basanite hook"}]}]}}

The report goes stale after 7 days (the hook then silently stops injecting rather than nagging from old data). Either re-run basanite report manually now and then, or add the self-refresher to SessionStart — it exits instantly when the report is fresh, regenerates in the background when not (async keeps it from delaying the session), single-flights via a lock file, and logs each attempt to refresh.log in the state dir:

{"hooks": {"SessionStart": [{"hooks": [{"type": "command", "command": "/home/you/go/bin/basanite refresh", "async": true}]}]}}

How it works

Separating tics from topics (scan)

Score = outside-loudest-project count × ln(smoothed rate ratio):

  • log-ratio weights concentration — 5× this week vs ~0 baseline beats a flat common word (a Poisson G-statistic shape, add-half smoothed);
  • leave-loudest-out kills topic words — a diction tic rises across projects, a topic word (project names, the week's domain nouns) rises in one, so each word's loudest single project is excluded from its count;
  • ratio floor (default 2×) cuts ordinary vocabulary drifting at 1.2–1.6× with the week's topic mix.

The ladder (specificity ordering)

ladder orders each sense's candidates by specificity, weakest → strongest — Resnik information content from the SemCor IC table for nouns and verbs, word-frequency IC as the fallback (adjectives and adverbs have no hypernym tree). Rungs come from same-synset synonyms, one and two hypernym levels up (the demote direction: toward the weaker, more general word that's often the truer one), and similar-to clusters for adjectives; ties within a synset break toward the more common word. The * marks where the flagged word itself sits:

load-bearing (a) capable of bearing a structural load
supporting(11.2) < bearing(11.2) < *load-bearing(13.1)

The cloze pass (substitutability in your sentences)

vet can't context-fit at turn start (no target sentence exists yet), so your past sentences are the context: for each WordNet candidate, mask the target in up to 50 real uses (evenly sampled over the window, deduped), substitute the candidate, and compare GloVe mean-pooled sentence vectors. A candidate that preserves the vector across most uses is a true replacement in your idiolect; wrong-sense artifacts wobble and self-eliminate. Out-of-vocabulary candidates are skipped, not scored — an OOV substitution would earn a free near-1 cosine.

The same pass classifies signature vs tic for free: the mean pairwise cosine of a word's use-vectors (sentences minus the word), reported as a delta against the corpus baseline — in a one-author corpus everything is topically similar, so only the delta means anything. Above baseline = clustered contexts = tic-like; below = diverse = signature, leave it alone.

Chronic tics (the frame and rarity routes)

A chronic tic is invisible to scan — a word used at a steady ~1/1k for months is its own baseline. The report adds up to four chronic entries: steady high-rate words, used across several projects, admitted by one of two deterministic evidence routes:

  • frame: the genitive metaphor frame <det> <word> of ("the spine of the design") repeats across ≥25% of uses. A word can be topically diverse while the frame is the tic — this is computed over raw sentence text, since the evidence is exactly the stopwords tokenization drops.
  • rarity: the word is rare in general English (SemCor word frequency) while frequent in your corpus. load-bearing and substrate score 11–13 where ordinary domain words (test, session, file) sit at 7–10; the floor is 10.5. Three-letter "rare words" are excluded — they are almost always abbreviations whose WordNet senses mislead.

Context clustering is deliberately not an admission route: measured on real data, domain vocabulary legitimately clusters at the same delta as genuine tics, so it can't separate them.

The term-of-art judge (optional)

Everything above is deterministic and offline. But the deterministic stack has one boundary it provably can't cross: telling a dilutable tic (substrate — reach for it loosely, a weaker word is often truer) from a precise term of art (hook — the Claude Code concept; → snare would be actively wrong). That's word-sense disambiguation, and static embeddings are sense-blind (measured: the deterministic discriminator inverted, scoring hook more substitutable than substrate). So report --judge adds one fenced LLM judgment — and only that one.

The deterministic detector hands each riser its vetted demote ladder and real sample sentences; the judge classifies tic / term_of_art / mixed and, for a tic, selects the truer rung from that ladder only — a strict tool schema confines it to the vetted set, so it can never invent a word, and a malformed or incoherent verdict fails safe to the un-gated entry. term_of_art words are dropped (no valid substitute); mixed words are kept with a per-sense note. The fence is stull's spec.Cell used as a standalone fenced-oracle library.

It runs by default when a key is configured — the deterministic-only report is the one that confidently mis-suggests synonyms for terms of art (hook → snare), so the judge is the default experience, not an add-on. It needs ANTHROPIC_API_KEY (in the environment or a .env — see .env.example), runs at report time (not per turn), and uses a cheap model with prompt caching. Without a key it falls back to deterministic rather than fail. A proper-nouns.txt (data dir or ~/.config/basanite) of your project/tool names is suppressed deterministically before the judge — a frequency+sense pass otherwise mistakes a project literally named calque for the common word.

basanite report                  # judge runs when a key is configured
basanite report --judge=false    # deterministic-only, no API calls

The hook

report composes the pipeline offline (one corpus read; risers with no WordNet entry drop out — which conveniently kills project-name noise; rungs survive only if they were clean substitutions in ≥40% of real uses — ≥50% for chronic entries, whose multi-sense candidate sets leak more — and don't contain the tic word itself). hook reads the resulting JSON, injects once per session, and treats every abnormal case — missing report, stale report, no session id — as silent success. It never touches the corpus, WordNet, or vectors, and never blocks a prompt.

The injection is awareness, not prohibition — never "don't say X": naming a word in order to suppress it tends to prime it instead (ironic process theory). The ladder reads weakest → strongest so the move can be demote, not just swap.

Knowing whether it works

The transcripts are the longitudinal record; no state accumulates. basanite trend <lemma> shows weekly rates straight from them, so the intervention is measurable: after the hook goes live, a flagged word's rate should fall and its alternatives' rates rise. It also exposes the two tic shapes: forming (rate rising from zero — what scan catches) and chronic (rate high and flat, invisible to delta-over-baseline because the baseline is already saturated — trend is the view for those).

Data

scripts/fetch-data.sh (needs curl, tar, unzip; ~1.2 GB transient disk) downloads the assets and verifies each against a pinned sha256:

  • WordNet 3.0 database files (~35 MB unpacked) — from Princeton, under the WordNet license.
  • WordNet-InfoContent tables (SemCor Resnik IC) — via the nltk_data mirror.
  • GloVe 6B vectors (822 MB download, the 100d table — 347 MB — is kept) — Stanford NLP's release (Open Data Commons PDDL), fetched from the stanfordnlp/glove Hugging Face mirror.

Nothing is redistributed in this repository. The binary looks for assets in $BASANITE_DATA, ./data, then ~/.local/share/basanite.

Known limitations

  • Without --judge, wrong-sense rungs leak through the cloze filter (100d mean-pooled vectors only discriminate senses so far) — most visibly for dev jargon, where hook's WordNet senses are fishing and boxing. The demote-only render hides most of it; the judge suppresses the rest by recognizing the term of art.
  • The judge is an LLM and is not deterministic across prompt wording — tuning it to fix one word can perturb another (observed: a prompt edit to catch project-name proper nouns regressed local). temperature: 0 makes a cached verdict stable, but the judgment remains a model call, not a proof. Project-name proper nouns are handled deterministically by proper-nouns.txt, not by the model.
  • The chronic stage needs frame or rarity evidence; a chronic tic that is a common English word used without a repeating frame won't be flagged.
  • Entries are capped (8 risers + 4 chronic per report) so the injection stays digestible; a tic below those cuts waits its turn.

License

MIT (code). Data assets are fetched from their origins under their own licenses — see Data above.

Ver o original no GitHub

Bom para

Relacionados