hatch3r 1.7.1 → 1.8.0

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

@@ -0,0 +1,84 @@
+---
+id: hatch3r-cli-fzf
+description: "Interactive fuzzy finder for TTY pickers. Use when ad-hoc interactive picker over piped stdin streams from another command; invoke `fzf`. Requires a TTY; degrade gracefully to non-interactive batch in CI."
+tags: ["cli-tools", "interactive"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: fzf
+  bin: fzf
+  tier: 2
+  category: interactive
+  homepage: https://github.com/junegunn/fzf
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# fzf
+
+Interactive fuzzy finder for TTY pickers
+
+## When to Use
+
+Reach for `fzf` when the task is in the **interactive** 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
+fzf --filter 'auth' < paths.txt
+```
+Headless mode — ranks lines by fuzzy match score and prints them in order; no TTY needed. This is the agent-safe entrypoint.
+
+```bash
+git branch --format='%(refname:short)' | fzf --filter main
+```
+Score branch names against `main`; pipe to `head -1` to pick the best match deterministically.
+
+```bash
+rg -l 'TODO' . | fzf --filter 'src/cli'
+```
+Re-rank a `ripgrep` file list by proximity to a fuzzy hint; combine with `head` for a deterministic top pick.
+
+```bash
+fzf --filter 'auth' --print0 < paths.txt | xargs -0 wc -l
+```
+Stream NUL-delimited matches to a downstream pipeline — safe across filenames with spaces.
+
+```bash
+fzf < paths.txt
+```
+Interactive picker — only useful in a human TTY; do not call this form from an autonomous agent.
+
+## Wrong Choice When
+
+- Running in a non-TTY context (CI, agent loop) — interactive `fzf` will hang on stdin; always use `--filter` headless mode.
+- The ranking needs semantic understanding (synonyms, embeddings) — `fzf` is character-level fuzzy; reach for an embedding-based tool.
+- A simple `grep -F` or `rg --files | head` would already return the right answer — no need to layer scoring on top.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `skim` (`sk`) | Need a Rust binary with similar fuzzy scoring and the same `--filter` headless mode. |
+| `rg --files \| head` | Already filtered; want stable lexicographic order rather than fuzzy ranking. |
+| `grep -F` | Exact substring match; no scoring needed. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v fzf
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install fzf
+```
+
+Homepage: https://github.com/junegunn/fzf

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

@@ -0,0 +1,90 @@
+---
+id: hatch3r-cli-gh
+description: "GitHub CLI — repos, issues, PRs, releases, gists. Use when drafting GitHub pull requests, issues, releases, gists, or workflow dispatches; invoke `gh`. Authenticates via the platform's native token mechanism (OAuth / PAT)."
+tags: ["cli-tools", "forge", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: gh
+  bin: gh
+  tier: 1
+  category: forge
+  homepage: https://cli.github.com/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# gh
+
+GitHub CLI — repos, issues, PRs, releases, gists
+
+## When to Use
+
+Reach for `gh` when the task is in the **forge** 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
+gh pr view 123 --json title,state,body,reviewDecision
+```
+Targeted JSON projection — pulls just the fields the agent needs, not the whole PR payload.
+
+```bash
+gh issue list --label bug --json number,title,author --limit 50
+```
+Label-filtered list with capped page size — avoids paginating the entire issue corpus into context.
+
+```bash
+gh api repos/:owner/:repo/contents/path/to/file.ts --jq '.sha'
+```
+Direct REST passthrough with built-in `--jq` filter — single round-trip, no jq install required at call site.
+
+```bash
+gh run watch
+```
+Blocks until the most recent CI run finishes — pairs with PR creation flows so the agent doesn't poll.
+
+```bash
+gh release create v1.7.5 --notes-from-tag --target release/1.7.5
+```
+Cuts a release using annotated-tag notes; deterministic input avoids hand-edited release bodies.
+
+```bash
+gh pr checks 78 --watch
+```
+Live-tail status checks for a PR — return value reflects the worst check state, scripts can branch on it.
+
+## Wrong Choice When
+
+- Don't reach for `gh` against a GitLab or Azure DevOps remote. Reach for `glab` (`hatch3r-cli-glab`) or `az repos`/`az devops` (`hatch3r-cli-az-devops`).
+- Don't use `gh auth login` flows when an audit trail of who authorized what is required; OAuth scopes granted to the CLI are user-bound. Reach for the GitHub web UI plus org-level SSO logs.
+- Don't use `gh api` for high-volume bulk fetches (>10k records) — rate limits bite. Reach for the GraphQL endpoint via `gh api graphql -F query=@file.gql` with pagination, or a GitHub App token.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `glab` (`hatch3r-cli-glab`) | GitLab forges — same operations, different vendor. |
+| `az-devops` (`hatch3r-cli-az-devops`) | Azure DevOps forges. |
+| `git` + `curl` against REST | Minimal environment (CI runner) where installing `gh` is blocked; trade convenience for raw HTTP. |
+| GitHub web UI | Operations needing org-level approval flows or SAML re-auth that the CLI cannot proxy. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v gh
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install gh
+```
+
+Homepage: https://cli.github.com/

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

@@ -0,0 +1,89 @@
+---
+id: hatch3r-cli-glab
+description: "GitLab CLI — merge requests, issues, pipelines. Use when GitLab merge-request review, pipeline retries, and issue triage; invoke `glab`. Authenticates via the platform's native token mechanism (OAuth / PAT)."
+tags: ["cli-tools", "forge"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: glab
+  bin: glab
+  tier: 2
+  category: forge
+  homepage: https://gitlab.com/gitlab-org/cli
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# glab
+
+GitLab CLI — merge requests, issues, pipelines
+
+## When to Use
+
+Reach for `glab` when the task is in the **forge** 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
+glab mr list --assignee=@me --output json | jq '.[] | {iid, title, web_url}'
+```
+List merge requests assigned to the authenticated user; `--output json` keeps stdout structured.
+
+```bash
+glab mr view 42 --output json
+```
+Fetch a single MR's metadata as JSON — avoids the HTML-decorated default view.
+
+```bash
+glab mr diff 42
+```
+Print the unified diff for an MR to stdout; pipe to `delta` for review or `diff -u` parsing.
+
+```bash
+glab issue create --title 'tracking-id mismatch on import' --label bug --label backend
+```
+Open an issue from a script; the URL is printed on stdout for the agent to capture.
+
+```bash
+glab ci view --branch main
+```
+Show the pipeline status for `main`; agents should re-run with `--output json` for parseable output.
+
+```bash
+glab api projects/:fullpath/jobs --paginate
+```
+Raw API call with auto-pagination for endpoints the high-level commands do not cover.
+
+## Wrong Choice When
+
+- The repo lives on GitHub, not GitLab — use `gh` (Tier 1) which has parity for issues/PRs/checks.
+- The repo lives in Azure Repos — use `az devops` (Tier 2 sibling) with the same credential model.
+- You only need to read a public file at a known URL — `curl` is one HTTP round-trip versus `glab`'s auth dance.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `gh` | GitHub-hosted repository. |
+| `az devops` | Azure DevOps / Azure Repos. |
+| `curl` + `GITLAB_TOKEN` | Endpoint not exposed by `glab api`; need explicit retry/timeout control. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v glab
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install glab
+```
+
+Homepage: https://gitlab.com/gitlab-org/cli

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

@@ -0,0 +1,89 @@
+---
+id: hatch3r-cli-jq
+description: "JSON processor and query language. Use when shaping JSON streams via jq-syntax filters and select expressions; invoke `jq`. Reads stdin and emits stdout; integrates seamlessly into shell pipelines."
+tags: ["cli-tools", "json", "core"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: jq
+  bin: jq
+  tier: 1
+  category: json
+  homepage: https://github.com/jqlang/jq
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# jq
+
+JSON processor and query language
+
+## When to Use
+
+Reach for `jq` when the task is in the **json** 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
+gh pr list --json number,title,isDraft | jq '.[] | select(.isDraft|not) | .number'
+```
+Pipeline from `gh` JSON into a selector — emits only open non-draft PR numbers.
+
+```bash
+jq -r '.[] | .name' inventory.json
+```
+Raw string output (`-r`) drops the JSON quoting — feeds straight into `xargs` or shell loops.
+
+```bash
+jq 'group_by(.category) | map({key: .[0].category, value: length}) | from_entries' findings.json
+```
+Group-then-count idiom — produces a `{category: count}` object suitable for direct comparison against a baseline.
+
+```bash
+jq --slurp 'add | unique_by(.id)' shard-*.json
+```
+Slurp multiple files into a single array, concatenate, dedupe by `id` — the canonical merge pattern for sharded JSON output.
+
+```bash
+jq -c '{id, title, severity}' findings.json
+```
+Compact (`-c`) one-object-per-line projection — perfect input for `xargs -L1` or `grep`-style downstream tools.
+
+## Wrong Choice When
+
+- Don't use `jq` for bidirectional grep on flattened paths; the inverse (`gron` outputs `obj.foo.bar = …` lines you can `rg` then translate back). Reach for `gron`.
+- Don't use `jq` directly on multi-document YAML or front-matter Markdown. Reach for `yq` (`hatch3r-cli-yq`) and pipe `yq -o=json` into `jq` only if you need jq's filter language.
+- Don't reach for `jq` when the file is a stream of newline-delimited JSON (`.ndjson`); use `jq -c` per line or `jaq`/`fx` for stream-friendly behavior — `jq` without `-c` slurps the whole file.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `yq` (`hatch3r-cli-yq`) | YAML, TOML, XML input — yq speaks them all, jq is JSON-only. |
+| `gron` | Flatten JSON to `path = value` lines for grep-based exploration and reverse-translation. |
+| `dasel` | Single binary across JSON/YAML/TOML/XML with a path-query DSL — handy in CI where you do not want jq+yq. |
+| `fx` | Interactive JSON browsing in a TTY; jq is the right call in scripts. |
+
+## Known Issues
+
+- **CVE-2026-32316 (active, no tagged fix as of 2026-05-18):** jq 1.8.1 ships with a heap buffer overflow in expression evaluation. Six additional CVEs were disclosed 2026-04-15; patches are committed on `jqlang/jq` `main` but no superseding tagged release exists yet. Do not invoke `jq` on JSON sourced from an untrusted producer (third-party API webhook, user-supplied upload) until a tagged release past 1.8.1 lands. Reference: https://github.com/jqlang/jq/security/advisories.
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v jq
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install jq
+```
+
+Homepage: https://github.com/jqlang/jq

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

@@ -0,0 +1,78 @@
+---
+id: hatch3r-cli-lazygit
+description: "Terminal UI for git with keyboard-driven workflows. Use when keyboard-driven terminal UI for staging, rebasing, branch switching; invoke `lazygit`. Reads `.git/objects` directly without invoking external services or remotes."
+tags: ["cli-tools", "git"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+cli_tool:
+  id: lazygit
+  bin: lazygit
+  tier: 2
+  category: git
+  homepage: https://github.com/jesseduffield/lazygit
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# lazygit
+
+Terminal UI for git with keyboard-driven workflows
+
+## When to Use
+
+Reach for `lazygit` when the task is in the **git** 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
+
+`lazygit` is a TUI for humans; agents should call plain `git` instead. The recipes below are key bindings inside the running TUI, not shell commands.
+
+```bash
+lazygit
+```
+Launch the TUI in the cwd repo — requires an interactive terminal; will hang in a non-TTY context.
+
+```bash
+lazygit -p path/to/repo
+```
+Open the TUI on a specific repo without changing directory first.
+
+Key bindings inside the TUI (human reference):
+- `a` — stage all changes in the focused file
+- `c` — open the commit message editor
+- `P` — push current branch
+- `p` — pull current branch
+- `?` — show the full keymap
+
+## Wrong Choice When
+
+- The caller is an autonomous agent (no human at the terminal) — use plain `git status` / `git add` / `git commit` instead; they emit parseable stdout.
+- The task is part of a CI script — `lazygit` cannot run headless; rely on `git` plumbing commands.
+- You need a scriptable diff view — pair `git diff` with `delta` or `difftastic` rather than launching a TUI.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `git` (plain) | Anything an agent or CI script runs. |
+| `tig` | Prefer a different TUI keymap; broadly similar capability. |
+| `gh` / `glab` | The operation is forge-side (PRs, issues), not local repo state. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v lazygit
+```
+
+Install (mac):
+
+```bash
+# brew
+brew install lazygit
+```
+
+Homepage: https://github.com/jesseduffield/lazygit

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-qsv` (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-qsv` (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