hatch3r 1.7.0 → 1.7.5

package/skills/hatch3r-cli-llm/SKILL.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-llm
+description: "simonw/llm — invoke LLMs from the command line with prompt templates. Use when model-agnostic shell prompting with template files and conversation memory; invoke `llm`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
+tags: ["cli-tools", "ai"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: llm
+  bin: llm
+  tier: 2
+  category: ai
+  homepage: https://llm.datasette.io/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# llm
+
+simonw/llm — invoke LLMs from the command line with prompt templates
+
+## When to Use
+
+Reach for `llm` when the task is in the **ai** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+llm 'summarize this' < file.txt
+```
+Pipe a file into the default model; output is plain text on stdout.
+
+```bash
+llm -m claude-3-5-sonnet 'rewrite as bullet points' < draft.md > bullets.md
+```
+Pick a model explicitly and redirect output — useful in batch scripts.
+
+```bash
+llm -t code-review -m claude-3-5-sonnet < patch.diff
+```
+Use a saved prompt template (`-t code-review`); template files live under `~/.config/io.datasette.llm/templates/`.
+
+```bash
+llm logs --last 5 --json | jq '.[] | {model, prompt, response}'
+```
+Inspect recent prompt/response pairs; the local SQLite log is queryable with standard SQL via `llm logs sql`.
+
+```bash
+llm templates list
+```
+List installed templates so the agent picks an existing one instead of writing a new prompt from scratch.
+
+## Wrong Choice When
+
+- You are already running inside an agent driven by an LLM (this assistant) — nesting another LLM call adds latency and cost without new capability.
+- The task is deterministic text transformation (e.g., rename a variable across files) — use `sd`/`comby`/`ast-grep`, not an LLM.
+- Working offline without a configured local backend — set up Ollama or `llm-local` first; `llm` with no provider errors out.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `aichat` | Want a richer multi-turn TTY chat experience. |
+| `mods` | Bias toward shell-friendly piping, prompt-as-flag UX. |
+| `curl` to provider API | Need explicit request shape, streaming, or headers `llm` does not expose. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v llm
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install llm
+```
+
+Homepage: https://llm.datasette.io/

package/skills/hatch3r-cli-miller/SKILL.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-miller
+description: "awk/sed/cut/join for CSV/TSV/JSON/Parquet streams. Use when awk-like record processing across CSV, TSV, JSON line streams; invoke `mlr`. Streams records lazily; works on datasets that exceed available RAM."
+tags: ["cli-tools", "data", "opt-in"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: miller
+  bin: mlr
+  tier: 3
+  category: data
+  homepage: https://miller.readthedocs.io/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# miller
+
+awk/sed/cut/join for CSV/TSV/JSON/Parquet streams
+
+## When to Use
+
+Reach for `mlr` when the task is in the **data** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+mlr --c2t cat data.csv
+```
+Convert CSV to TSV on stdout — handy for piping into shell tools that prefer tab delimiters.
+
+```bash
+mlr --csv stats1 -a mean,stddev -f price products.csv
+```
+Compute mean and stddev of the `price` column.
+
+```bash
+mlr --icsv --ojson put '$tax = $amount * 0.07' transactions.csv
+```
+Read CSV, add a computed column, emit JSON — chained format conversion plus DSL transform.
+
+```bash
+mlr --csv filter '$status == "active"' users.csv
+```
+Row filter using the put/filter DSL — operates on streams of arbitrary size.
+
+```bash
+mlr --csv join -j id -f orders.csv customers.csv
+```
+SQL-style join on `id` between two CSVs, streamed.
+
+## Wrong Choice When
+
+- **Multi-gigabyte analytical queries with joins:** `hatch3r-cli-duckdb` (tier 2) has a query planner and parallel scan; mlr is streaming-single-thread.
+- **One-column slice or count:** `hatch3r-cli-xsv` (tier 2) is faster for trivial slicing.
+- **Production ETL with schema enforcement:** use a real database or dbt — mlr is a CLI-scratchpad tool.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-duckdb` (tier 2) | Multi-GB data, joins, analytical SQL, Parquet |
+| `hatch3r-cli-xsv` (tier 2) | Single-column slice, count, sample on plain CSV |
+| `hatch3r-cli-csvkit` (tier 3) | SQL-over-CSV with `csvsql`, Python integration |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v mlr
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install miller
+```
+
+Homepage: https://miller.readthedocs.io/

package/skills/hatch3r-cli-mods/SKILL.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-mods
+description: "Charm mods — Unix-friendly LLM pipeline tool. Use when Unix-pipeline LLM inference reading Markdown stdin and writing Markdown stdout; invoke `mods`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
+tags: ["cli-tools", "ai", "opt-in"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: mods
+  bin: mods
+  tier: 3
+  category: ai
+  homepage: https://github.com/charmbracelet/mods
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# mods
+
+Charm mods — Unix-friendly LLM pipeline tool
+
+## When to Use
+
+Reach for `mods` when the task is in the **ai** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+cat README.md | mods 'summarize in 3 bullets'
+```
+Pipe a file into mods with an inline instruction; output prints to stdout.
+
+```bash
+git diff | mods 'write a conventional-commits message for this diff'
+```
+Generate a commit message from staged changes — pairs well with `git commit -F -`.
+
+```bash
+mods -m gpt-4o 'rewrite for clarity' < draft.md
+```
+Override the default model per invocation.
+
+```bash
+mods --no-cache 'fresh response please' < input.txt
+```
+Bypass the on-disk response cache when you need a non-deterministic re-roll.
+
+```bash
+mods -f json 'extract action items as a JSON array' < meeting-notes.md
+```
+Force a structured-output format — pipes cleanly into `hatch3r-cli-jq`.
+
+## Wrong Choice When
+
+- **Plugin ecosystem needed (templates, embeddings, multi-step chains):** `hatch3r-cli-llm` (tier 2) covers these; mods is intentionally minimal.
+- **Multi-turn conversational sessions:** mods is single-shot; use `hatch3r-cli-aichat` for persisted history.
+- **Interactive prompt iteration with feedback:** mods has no TUI — `aichat` has REPL mode.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-llm` (tier 2) | Plugin ecosystem, templates, embeddings, CI workflows |
+| `hatch3r-cli-aichat` (tier 3) | Multi-turn sessions, RAG mode, role library |
+| Raw `curl` against provider API | Custom request shape, streaming, no client process |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v mods
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install charmbracelet/tap/mods
+```
+
+Homepage: https://github.com/charmbracelet/mods

package/skills/hatch3r-cli-overview/SKILL.md

@@ -0,0 +1,60 @@
+---
+id: hatch3r-cli-overview
+description: "Catalog of all hatch3r-recommended CLI tools — discovery entry with tier tables and decision tree."
+tags: ["cli-tools", "core", "reference"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# CLI Tool Catalog
+
+hatch3r recommends a small set of terminal-native CLI tools agents can call instead of MCP servers or wrapped APIs. Each tool listed below has its own skill file with recipes, anti-patterns, and per-OS install instructions. Run `npx hatch3r cli-tools` to (de)select tools, or `npx hatch3r cli-tools detect` for a read-only install report.
+
+## Tier 1 — default-on
+
+| Tool | Skill ID | Use for |
+|------|----------|---------|
+| `ast-grep` | `hatch3r-cli-ast-grep` | Structural search and rewrite for code via AST patterns |
+| `bat` | `hatch3r-cli-bat` | cat clone with syntax highlighting and git integration |
+| `delta` | `hatch3r-cli-delta` | Syntax-highlighting git diff pager |
+| `fd` | `hatch3r-cli-fd` | User-friendly find replacement, gitignore-aware |
+| `gh` | `hatch3r-cli-gh` | GitHub CLI — repos, issues, PRs, releases, gists |
+| `jq` | `hatch3r-cli-jq` | JSON processor and query language |
+| `ripgrep` | `hatch3r-cli-ripgrep` | Fast recursive grep with sane defaults and gitignore awareness |
+| `sd` | `hatch3r-cli-sd` | Intuitive sed replacement with literal string patterns |
+| `yq` | `hatch3r-cli-yq` | YAML processor (mikefarah Go implementation) |
+| `zstd` | `hatch3r-cli-zstd` | Fast lossless compression with high ratio |
+
+## Tier 2 — conditional (offered on project signal)
+
+| Tool | Skill ID | Use for |
+|------|----------|---------|
+| `az-devops` | `hatch3r-cli-az-devops` | Azure DevOps work items, repos, pipelines via az CLI extension |
+| `difftastic` | `hatch3r-cli-difftastic` | Structural diff that understands syntax |
+| `docker` | `hatch3r-cli-docker` | Container runtime and CLI |
+| `duckdb` | `hatch3r-cli-duckdb` | Embedded analytical database with first-class CSV/Parquet support |
+| `fzf` | `hatch3r-cli-fzf` | Interactive fuzzy finder for TTY pickers |
+| `glab` | `hatch3r-cli-glab` | GitLab CLI — merge requests, issues, pipelines |
+| `lazygit` | `hatch3r-cli-lazygit` | Terminal UI for git with keyboard-driven workflows |
+| `llm` | `hatch3r-cli-llm` | simonw/llm — invoke LLMs from the command line with prompt templates |
+| `playwright` | `hatch3r-cli-playwright` | Browser automation, web testing, and UI interaction |
+| `taplo` | `hatch3r-cli-taplo` | TOML toolkit (format, lint, query) for pyproject.toml / Cargo.toml |
+| `xsv` | `hatch3r-cli-xsv` | Fast CSV toolkit (slice, search, join, stats) |
+
+## Tier 3 — opt-in advanced
+
+| Tool | Skill ID | Use for |
+|------|----------|---------|
+| `aichat` | `hatch3r-cli-aichat` | Multi-provider LLM chat CLI with RAG and session memory |
+| `comby` | `hatch3r-cli-comby` | Structural search and replace across languages with declarative patterns |
+| `csvkit` | `hatch3r-cli-csvkit` | csvkit — Python CSV toolkit (csvlook, csvsql, csvjoin, csvstat) |
+| `miller` | `hatch3r-cli-miller` | awk/sed/cut/join for CSV/TSV/JSON/Parquet streams |
+| `mods` | `hatch3r-cli-mods` | Charm mods — Unix-friendly LLM pipeline tool |
+| `podman` | `hatch3r-cli-podman` | Daemonless container engine, rootless by default (Docker alternative) |
+| `rtk` | `hatch3r-cli-rtk` | CLI output-compression proxy (see ⚠ caveat) |
+| `stagehand` | `hatch3r-cli-stagehand` | Browserbase Stagehand — AI-driven browser automation |
+
+## Decision Tree
+
+Need text search → `rg`. Structural → `ast-grep`. Files → `fd`. JSON → `jq`. YAML → `yq`. Replace → `sd`. Git/forge → `gh` / `glab` / `az-devops`. Browser → `playwright`. View → `bat`. Diff → `delta`. Archive → `zstd`.

package/skills/hatch3r-cli-playwright/SKILL.md

@@ -0,0 +1,89 @@
+---
+id: hatch3r-cli-playwright
+description: "Browser automation, web testing, and UI interaction. Use when end-to-end browser test execution capturing screenshots and traces; invoke `playwright`. Built around test runners (`@playwright/test`) with deterministic locators and waits."
+tags: ["cli-tools", "browser"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: playwright
+  bin: playwright
+  tier: 2
+  category: browser
+  homepage: https://playwright.dev/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# playwright
+
+Browser automation, web testing, and UI interaction
+
+## When to Use
+
+Reach for `playwright` when the task is in the **browser** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+npx playwright test
+```
+Run the full suite; non-zero exit on first failing spec.
+
+```bash
+npx playwright test --grep '@smoke' --workers=1
+```
+Filter by tag and serialize workers — stable output for agent log scraping.
+
+```bash
+npx playwright test tests/login.spec.ts --reporter=line
+```
+Single-file run with one-line-per-test reporter — fits in <1KB stdout.
+
+```bash
+npx playwright codegen https://example.com
+```
+Record interactions into a generated spec — human-in-the-loop authoring; not for autonomous runs.
+
+```bash
+npx playwright test --update-snapshots
+```
+Refresh visual/text snapshots after intentional UI changes; review the diff before committing.
+
+```bash
+npx playwright show-report
+```
+Open the HTML report locally — human triage step; agents should parse `test-results/results.json` instead.
+
+## Wrong Choice When
+
+- The system under test exposes only an HTTP API and no rendered UI — use `curl` + `jq` (Tier 1) for ~50x faster runs.
+- The task is autonomous natural-language browsing (navigate, read, decide) rather than scripted assertions — Stagehand is built for that loop.
+- You only need a one-off page snapshot or screenshot from a script — a headless `curl` plus a server-side renderer is cheaper than the full Playwright install.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `curl` + `jq` | API-only tests; no DOM involved. |
+| Stagehand | Agent drives the browser with natural language rather than fixed scripts. |
+| Cypress | Existing Cypress suite or component-test workflow; otherwise prefer Playwright for multi-browser support. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v playwright
+```
+
+Install (mac):
+
+```bash
+# npm
+npm install -D @playwright/test && npx playwright install
+```
+
+Homepage: https://playwright.dev/

package/skills/hatch3r-cli-podman/SKILL.md

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-podman
+description: "Daemonless container engine, rootless by default (Docker alternative). Use when rootless OCI-image execution without a privileged daemon; invoke `podman`. Forks per-pod processes directly under the invoking user; ideal for hardened CI workers."
+tags: ["cli-tools", "container", "opt-in"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: podman
+  bin: podman
+  tier: 3
+  category: container
+  homepage: https://podman.io/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# podman
+
+Daemonless container engine, rootless by default (Docker alternative)
+
+## When to Use
+
+Reach for `podman` when the task is in the **container** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+podman build -t myapp:dev .
+```
+Build an image from the local Dockerfile — same CLI surface as docker build.
+
+```bash
+podman run --rm -v "$PWD:/app:Z" -w /app node:22 npm test
+```
+Run a one-shot container with the working directory bind-mounted; the `:Z` suffix triggers SELinux relabel on Fedora/RHEL hosts.
+
+```bash
+podman compose up
+```
+Run a `compose.yaml` workflow under podman — uses the podman-compose plugin or docker-compose adapter.
+
+```bash
+podman run --userns=keep-id -v "$PWD:/work" myapp
+```
+Preserve the host UID inside the rootless container so written files do not end up owned by a high-mapped UID.
+
+```bash
+podman system service --time=0 &
+```
+Expose a docker-API-compatible socket so docker-only tooling (e.g. testcontainers) can talk to podman unchanged.
+
+## Wrong Choice When
+
+- **Enterprise compose / swarm orchestration:** `hatch3r-cli-docker` (tier 2) is the established path for Swarm and Docker Desktop integration; podman's swarm support is minimal.
+- **macOS developer experience parity:** docker desktop has native macOS VM tuning; podman runs in a QEMU machine with extra overhead and bind-mount caveats.
+- **Tooling that hard-codes `/var/run/docker.sock`:** unless you start `podman system service`, those tools fail.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `hatch3r-cli-docker` (tier 2) | Mainstream CI, Docker Desktop, Swarm, broad ecosystem assumptions |
+| nerdctl + containerd | Kubernetes-aligned runtime, OCI-faithful CLI |
+| buildah | Image builds without a full container runtime (rootless, scriptable) |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v podman
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install podman
+```
+
+Homepage: https://podman.io/

package/skills/hatch3r-cli-ripgrep/SKILL.md

@@ -0,0 +1,85 @@
+---
+id: hatch3r-cli-ripgrep
+description: "Fast recursive grep with sane defaults and gitignore awareness. Use when regex content searches across large source trees with gitignore filtering; invoke `rg`. Outputs newline-separated hit records; bound results with `-c` or `--max-count`."
+tags: ["cli-tools", "search", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: ripgrep
+  bin: rg
+  tier: 1
+  category: search
+  homepage: https://github.com/BurntSushi/ripgrep
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# ripgrep
+
+Fast recursive grep with sane defaults and gitignore awareness
+
+## When to Use
+
+Reach for `rg` when the task is in the **search** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+rg --json -tts 'createServer\(' src/
+```
+Structured JSON output scoped to TypeScript — parse hits with `jq` instead of re-reading files.
+
+```bash
+rg -c 'TODO' --type ts
+```
+Per-file match counts for `.ts` files; cheap stand-in for issue-debt triage.
+
+```bash
+rg -B 2 -A 4 'BREAKING' --max-count 50 CHANGELOG.md
+```
+Context windows around BREAKING entries, capped at 50 hits to bound output size.
+
+```bash
+rg --hidden --no-ignore 'API_KEY' .
+```
+Pierces both dotfiles and `.gitignore` rules — use when scanning for accidentally-committed secrets.
+
+```bash
+rg --files-with-matches 'deprecated' src/ | xargs -I{} rg -n 'deprecated' {}
+```
+Two-phase: file list first, then ranged scan — keeps stdout small when match density is uneven.
+
+## Wrong Choice When
+
+- Don't use `rg` to match by code structure (function calls, type signatures, JSX shape); literal regex misses renames and whitespace variants. Reach for `ast-grep` (`hatch3r-cli-ast-grep`).
+- Don't run `rg` against binary blobs (`.zst`, `.png`, lockfile snapshots); it skips them silently by default but explicit `-a` mode wastes CPU. Reach for category-specific tools (`zstd -d` then `rg`, or `xxd | rg` for hex).
+- Don't use `rg` to search a specific git revision or stash — it only sees the working tree. Reach for `git grep <rev>`.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `ast-grep` (`hatch3r-cli-ast-grep`) | Structural code patterns: matchers like `console.log($MSG)` that survive whitespace and identifier renames. |
+| `git grep` | Search at a specific revision, tag, or stash — `rg` only reads the working tree. |
+| `fd` (`hatch3r-cli-fd`) piped into `rg` | Filename pre-filter when scoping by extension/age is faster than `rg --type`. |
+| `grep -RIn` | POSIX-only environment where ripgrep is not on PATH and install is blocked. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v rg
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install ripgrep
+```
+
+Homepage: https://github.com/BurntSushi/ripgrep

package/skills/hatch3r-cli-rtk/SKILL.md

@@ -0,0 +1,91 @@
+---
+id: hatch3r-cli-rtk
+description: "CLI output-compression proxy (see ⚠ caveat). Use when compressing oversize tool output payloads before they enter an LLM prompt; invoke `rtk`. Streams tokens to stdout so downstream `grep`/`tee` consumers see partial results."
+tags: ["cli-tools", "ai", "opt-in", "caveat"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: rtk
+  bin: rtk
+  tier: 3
+  category: ai
+  homepage: https://github.com/rtk-ai/rtk
+  caveat: pipe-output-corruption
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# rtk
+
+CLI output-compression proxy (see ⚠ caveat)
+
+## ⚠ Critical: pipe-output corruption (issue #1282)
+
+rtk silently rewrites piped stdout which breaks downstream tooling.
+Mitigation: `export RTK_DISABLE_PIPE_REWRITE=1` or invoke with `rtk --raw-output`.
+Track upstream: https://github.com/rtk-ai/rtk/issues/1282
+
+## When to Use
+
+Reach for `rtk` when the task is in the **ai** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+export RTK_DISABLE_PIPE_REWRITE=1
+```
+Disable pipe-output rewriting before any pipeline use. Required for safe interop with jq/grep/awk.
+
+```bash
+rtk run npm test
+```
+Run the package's test suite under rtk to compress vitest/jest output before it reaches the agent's context.
+
+```bash
+rtk run pytest -x
+```
+Compress pytest output and stop on first failure — fits a multi-thousand-line traceback into a few KB.
+
+```bash
+rtk eval 'function foo() { return 42 }'
+```
+Sandboxed JavaScript eval — returns just the value, no surrounding noise.
+
+```bash
+rtk --raw-output run go test ./...
+```
+Per-invocation override of the pipe rewrite when piping output into a downstream parser (`| jq`, `| grep`).
+
+## Wrong Choice When
+
+- **Piping to `jq` / `grep` / `awk` without `RTK_DISABLE_PIPE_REWRITE=1` set:** the rewrite mangles JSON byte boundaries (issue #1282) — corruption is silent. Reach for plain shell + `tee` or `hatch3r-cli-jq` directly on raw command output.
+- **Safety-critical CI where masked failures matter:** rtk's compression can elide stack frames a downstream check needs. Run the underlying test command directly and capture full output to a file.
+- **One-shot small commands under ~100 lines:** the compression overhead exceeds the saved context — invoke the underlying tool directly.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| Plain shell + `tee output.log` | When you need a verbatim log file for forensics or CI artifacts |
+| `hatch3r-cli-jq` (tier 1) on raw output | When the upstream command already emits JSON and you want a deterministic projection |
+| Direct `npm test` / `pytest -x` with `--reporter` flags | When the test runner has a built-in compact reporter (jest `--silent`, pytest `-q`) |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v rtk
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install rtk-ai/tap/rtk
+```
+
+Homepage: https://github.com/rtk-ai/rtk