convez.ai
AgenteDevOps & InfraestruturaAvançado
justinstimatze

weir — Otimizador de Comandos Shell para Claude Code

justinstimatze/weir

Força Claude Code a usar grep rápido (rg), find eficiente (fd), e evitar UUOC

Ver no GitHub
InicialPluginScore · de 0 a 100

weir é um addon para Claude Code que corrige o gap entre a fluência do modelo em pipelines shell e seu uso de ferramentas desatualizadas (1995). Detecta e bloqueia antipadrões como `cat FILE | grep`, `which CMD`, e sugere alternativas modernas (`rg`, `fd`, `bat`, `sd`, `mlr`, `eza`) presentes no ambiente do usuário, injetando manifesto de capacidades e regras de linting antes de cada execução Bash.

Instalação

$npx convez-ai justinstimatze/weir

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
2
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 2 meses
Versão
v0.1.12
Issues abertas
0
Contribuidores
1

Casos de uso

  • Corrigir antipadrões de pipeline em bash repetitivos (grep | head, ls | grep, UUOC)
  • Descobrir e sugerir ferramentas shell modernas instaladas no host
  • Bloquear comandos mecanicamente inseguros (which vs command -v) e forçar reescrita

Veredito

Ferramenta hiperespecializada e engenhosa que resolve um problema real e mensurável (49,7% das invocações do Claude Code eram pipelines com tools obsoletas). Requer integração nativa com Claude Code e conhecimento profundo de shell; impacto alto para quem usa Code Agent em terminal, negligenciável fora desse contexto.

README

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

weir

A barrier across a stream that's also the standard instrument for measuring its flow rate.

weir is a Claude Code addon that closes a specific gap: the model writes shell pipelines fluently, but reaches for a 1995 toolbox.

The thesis

Mining one user's JSONL session transcripts across dozens of project directories (the sanitized aggregate is in internal/measure/baseline.json):

  • 25,216 Bash invocations
  • 49.7% contain a top-level pipe — the model writes pipelines constantly
  • 0 of those calls reached for rg, fd, bat, sd, mlr, eza, or any other modern alternative — not "underused", never reached for
  • A handful of antipatterns recur in volume — counts from the embedded baseline: grep | head (810), ls | grep (225), UUOC variants cat FILE | tool (~120 across head/grep/tail/jq/wc), grep | wc -l (99), awk | awk (38), find ... -exec ... \; (13). A separate pass-A discovery on the same corpus (data/mine_extra.py) added which CMD (~179), find | xargs without -print0 (~61), and ls | wc -l (~152).

The model's pipeline shapes are fine. What's broken is which binaries it reaches for inside each shape, and a small cluster of stereotyped antipatterns.

What weir does

Three layers, registered as Claude Code hooks. All fail-open; bypass with WEIR_SUGGEST_SKIP=1 / WEIR_SKIP=1.

Layer 1 — Capability manifest (SessionStart)

At the start of every session, weir probes $PATH for ~30 modern shell tools, emits a JSON manifest, and injects it into the model's context as additionalContext. The model now knows what's reachable on this host instead of defaulting to coreutils.

Sample output on a freshly-stocked Ubuntu 26.04:

[weir] Modern shell tools on this host:
- bat (prefer over cat) -> /usr/bin/batcat
- delta (prefer over diff) -> /usr/bin/delta
- fd (prefer over find) -> /usr/bin/fdfind
- jq (additive) -> /usr/bin/jq
- mlr (prefer over awk) -> /usr/bin/mlr
- rg (prefer over grep) -> /usr/bin/rg
- sd (prefer over sed) -> /usr/bin/sd
...

When tools are missing but apt-installable, weir surfaces a sudo apt install ... line at install time and in weir status.

Layer 2 — Antipattern suggester (PreToolUse:Bash)

Before each Bash invocation, weir lints the command against ~12 rules. Two modes:

  • Advisory (default): the suggestion is injected as context; the command still runs. Used for rules whose rewrites have edge cases.
  • Block: weir refuses to run the command and shows the suggested rewrite; the model retries with the better form. Used only for mechanically-safe rewrites where the rewrite is lossless and unambiguous.

Currently block: uuoc (cat FILE | tool → tool FILE) and which-vs-command-v (which X → command -v X). Everything else stays advisory.

$ which python3
[weir-suggest] blocking — antipattern with a mechanical-safe rewrite:
- [which-vs-command-v] `which CMD` -> `command -v CMD`. `which` is non-POSIX
  with inconsistent cross-distro behavior — can't see shell functions/aliases,
  exit codes vary. `command -v` is POSIX, sees functions/aliases, exits
  non-zero cleanly when missing. Rewrite the command and retry.
(To bypass this block for the rest of the session, set WEIR_SUGGEST_SKIP=1 in the env.)

Layer 3 — Idiom library (SessionStart, additive)

After the manifest, weir injects two more blocks:

  1. Per-tool idioms from a parsed tldr-pages corpus — the first 2 examples per installed modern tool.
  2. Composition idioms — 30 hand-curated goal-shaped pipelines (find files modified today and grep them; pretty-print every JSON in a tree; benchmark two command variants). Filtered to entries whose required tools are all present on the host; capped at 10 surfaced per session.

Layer 3 teaches "how to compose"; layer 1 teaches "what's installed."

Install

Requires Go 1.26 or later.

go install github.com/justinstimatze/weir@latest
weir install

weir install does a non-destructive merge into ~/.claude/settings.json — it backs up first, only adds its two hook entries (SessionStart + PreToolUse:Bash), and never touches other hooks. Re-running is idempotent; weir uninstall is clean.

If you want it scoped to one project instead of globally, point at a project settings file:

CLAUDE_SETTINGS=/path/to/project/.claude/settings.json weir install

Subcommands

commandwhat it does
weir suggestPreToolUse hook entry point — reads JSON on stdin, emits suggestion JSON
weir injectSessionStart hook entry point — renders manifest + idioms
weir probeemit the capability manifest JSON for the current host
weir installregister weir's hooks; idempotent; backs up settings first
weir uninstallremove weir's hooks; leaves unrelated hooks untouched
weir statusreport which weir hooks are registered + suggest missing-apt tools
weir measurere-mine ~/.claude/projects/**/*.jsonl and diff against the embedded baseline (modern-vs-classic tool counts, per-rule hit counts)
weir review CMDinteractive spot-check — given a bash command, print whether weir would block, advise, or stay silent (use for rule tuning)
weir build-idiomsmaintainer-only: parse a tldr-pages clone into internal/idioms/idioms.json (then rebuild the binary to re-embed)

How weir avoids being annoying

  • Fail-open everywhere. Any error in the hook → silent exit 0, command runs. weir cannot break your session.
  • Block mode is conservative. Only on rewrites where the substitution is mechanically lossless. Edge-case rules stay advisory.
  • Bypass is one env var. WEIR_SUGGEST_SKIP=1 disables suggest output for the session; WEIR_SKIP=1 disables the SessionStart inject.
  • Suggestions are concise. Rule fix-text is one paragraph max. SessionStart injection is bounded: the per-tool tldr idiom section caps at 2000 chars (~500 tokens), the cross-tool composition section caps at 1500 chars (~375 tokens), and the manifest itself scales with installed-tool count. Worst-case total on a richly-stocked host is ~1000 tokens.
  • Settings.json edits are non-destructive + reversible. Every write backs up first to <path>.weir-bak-<timestamp>; uninstall removes only weir-owned entries.

Architecture

Single self-contained binary (~2.6 MB, stripped). All runtime data (idiom corpus, baseline snapshot for weir measure) is embedded via //go:embed — no source-tree dependency at runtime.

main.go                        # subcommand dispatch + --version
internal/
  probe/                       # PATH discovery + apt-pkg mapping (+ symlink dedup)
  suggest/                     # rule table + match engine + selftest + review
  inject/                      # SessionStart prose renderer (manifest + idioms + composition)
  idioms/                      # per-tool (tldr) + composition idioms; build-idioms parser
  install/                     # non-destructive settings.json merge + status + uninstall
  measure/                     # corpus streamer + baseline diff (embedded baseline.json)
  guard/                       # panic-recover wrapper for all hook entry points
data/
  baseline_2026-05-20.json     # sanitized aggregate baseline (the empirical evidence)
  mine_pipes.py                # the original baseline-extraction script (Python, run rarely)
  mine_extra.py                # pass-A: hunt named antipatterns
  mine_discover.py             # pass-B: frequency-rank for unknowns
  eval/                        # synthetic eval harness (uv venv, prompts.jsonl, run/grade/report)
scripts/
  smoke.sh                     # install/uninstall cycle test (CI runs on every push)
  sanitize-baseline.py         # PII-strip raw mining output for the public artifact

Prior art

The compiler/dataflow lineage (PaSh, PaSh-JIT, Koala, Smoosh, POSH), surface-tooling lineage (ShellCheck, Ultimate Plumber), agent-side lineage (Warp, Butterfish, NL2SH, Terminal-Bench), and documentation lineage (tldr-pages, explainshell). Full citations + how each relates to weir in INFLUENCES.md.

Roadmap

Layer 4 (streaming/blocking classifier), eval extensions (block-and-retry simulation, cross-host probe), rule-table extensions, and distribution work. See ROADMAP.md. Historical dead ends in WHAT_DIDNT_WORK.md.

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados