Toolbelt

Toolbelt Skill

Prefer these tools for interactive terminal work. Check availability on the current machine; repository tooling and the host agent's editing rules take precedence over these defaults.

Table of Contents

• Resolve uncertainty
• Substitution table (always-on)
• Tooling discipline (carried from global defaults)
• Runtimes & package managers
• Search & navigate
• Edit text
• HTTP / API debugging
• GitHub and GitLab
• Data & SQL
• Debug & inspect
• Benchmark
• Domain & infra tools (know these exist)
• When NOT to substitute

Rule of thumb: classic tools for piping inside scripts that must be portable; modern tools for interactive/agent work where clarity and ergonomics win.

Resolve uncertainty

Use command -v, the installed tool's --help, and repository configuration to resolve missing tools or unfamiliar flags. Continue with a supported fallback when it preserves the requested result. Ask when the remaining uncertainty changes scope, risks user data, or requires authority the user has not supplied. A recipe here is not permission to install tools, load-test a service, or mutate remote state.

Substitution table (always-on)

Reach for the right-hand tool by default; fall back to the classic only when the modern one is absent.

Tooling discipline (carried from global defaults)

Use these defaults when the project does not specify its own tooling:

• Mise for project tools — pin tools and runtimes in .mise.toml, and run them with mise exec -- <tool>. Nix/Home Manager supplies the global machine environment. Honor an existing project's devShell until its toolchain is deliberately migrated.
• make is the task runner — use the repository's own targets; run make check before commits and make validate before PRs. Verify actual hook configuration before claiming these gates run automatically.
• JSON → jq — always jq for JSON processing; never python3 -c or inline Python. Reach for dasel the moment the format isn't JSON.

Runtimes & package managers

Use the project's declared runtime and lockfile. For ad-hoc work, prefer uv and bun when compatible.

• uv — Python runtime + dependency + project manager (replaces python/pip/venv/pipx/poetry):
  • uv run script.py (auto-resolves deps), uv run pytest (run a tool in the project env)
  • uv add httpx / uv remove httpx (manage pyproject.toml), uv sync (install lockfile)
  • uv venv (create env), uv pip install -r req.txt (pip-compatible shim)
  • uvx — run a Python CLI tool one-off without installing: uvx ruff check, uvx ruff@0.6 format.
• bun — JS/TS runtime + package manager + bundler (replaces node/npm/npx/yarn/pnpm):
  • bun run script.ts (runs TS directly, no compile step), bun test
  • bun install (fast install), bun add zod / bun remove zod
  • bunx — execute a package, downloading it if needed: bunx prettier --check config.json, bunx tsx file.ts.

Caveats: preserve the project's package manager, interpreter, and CI contract; changing runners can change compatibility or lockfiles. For one-off commands, inspect the installed version's help before using version-sensitive flags.

Search & navigate

Prefer rg/fd over grep -r/find — faster, respects .gitignore, sane defaults. When piping bat output, add -p to strip line numbers/borders.

• ast-grep (sg) — structural, syntax-aware code search & rewrite (matches by AST, not regex — immune to formatting/whitespace):
  • sg run -p 'console.log($A)' -l ts (find every console.log(...) call, any argument)
  • sg run -p 'foo($$$ARGS)' --rewrite 'bar($$$ARGS)' -l py -U (rename a call, preserving all args; -U applies in place)
  • Reach for sg over rg the moment the pattern is about code shape (a call, an import, a JSX element) rather than literal text — no brittle regex, no false hits inside strings/comments.

Edit text

• sd — find & replace, literal-friendly, real regex (no sed escaping pain):
  • sd 'foo' 'bar' file.txt (in-place, no -i needed)
  • sd -p 'foo' 'bar' file.txt (preview diff, don't write)
  • sd '(\w+)@(\w+)' '$2.$1' file (capture groups with $1)
  • Reach for sed only for stream edits in portable scripts.
  • For code-structure rewrites (rename a call, swap an API) use ast-grep --rewrite instead — it edits by AST, not text, so formatting and string/comment matches can't trip it up.

HTTP / API debugging

• xh — httpie-style client, faster than curl for hand-driven requests:
  • xh get https://api.example.com/users (auto-pretty JSON)
  • xh post api.local/items name=example (JSON body from k=v)
  • xh -f post url field=val (form), xh --headers get url (headers only)
  • xh get url Authorization:"Bearer $TOK" (header with :)
  • Use curl in scripts / when exact wire control or --resolve is needed.
• oha — load testing: oha -n 1000 -c 50 https://api.local/health.

GitHub and GitLab

• gh — GitHub-native repository, PR, release, and workflow operations:
  • gh repo view OWNER/REPO --json nameWithOwner,defaultBranchRef
  • gh api repos/OWNER/REPO/releases/tags/v1.2.3 --jq '{name,body,html_url}'
  • gh pr create --fill, gh pr view, gh run view
  • Prefer gh api over raw HTTP for GitHub metadata; use --jq to keep responses focused.
• glab — GitLab-native equivalent for projects, merge requests, releases, and pipelines:
  • glab mr create --fill, glab mr view, glab pipeline view

Use the provider-native CLI when the task targets GitHub or GitLab state. Keep xh for generic HTTP APIs and curl for scripts requiring exact wire control.

Data & SQL

• dasel — one tool to query/convert JSON/YAML/TOML/XML/CSV:
  • dasel -f config.yaml '.services.web.port'
  • dasel -f data.json -r json -w yaml (convert JSON→YAML)
  • dasel put -f config.yaml -v 8080 '.services.web.port' (edit YAML/TOML/etc. in place)
  • Use jq for pure-JSON pipelines (it's still the default for JSON); reach for dasel the moment the format isn't JSON. dasel handles YAML query and edit — it's the one tool for non-JSON structured data here.
• tokei — count lines of code quickly:
  • tokei . (recursive code statistics by language)
• duckdb — fast analytical SQL over files, no server:
  • duckdb -c "select * from 'data.csv' limit 5"
  • duckdb -c "select count(*) from read_parquet('*.parquet')"
• miller (mlr) — CSV/TSV/JSON record processing:
  • mlr --csv cut -f a,b then sort -nr b data.csv
• psql (from postgresql) — Postgres client. Not installed globally: it arrives through a project's .mise.toml (mise exec -- psql) or , psql for a one-off, so check before assuming it is on PATH.
  • psql "$DATABASE_URL" -c '\dt', psql -h host -U user db
• sqlx-cli — Rust SQL toolkit / migrations:
  • sqlx database create, sqlx migrate add <name>, sqlx migrate run
  • sqlx migrate revert, cargo sqlx prepare (offline query cache)

Debug & inspect

• procs — modern ps:
  • procs (all), procs nginx (filter by name), procs --tree
  • procs --sortd cpu (sort by CPU desc), shows ports/TTY/user.
• doggo — modern dig for DNS debugging:
  • doggo example.com, doggo MX example.com
  • doggo example.com @1.1.1.1 (specific resolver), --json for parsing.
• hexyl — colored hex viewer:
  • hexyl file.bin, hexyl -n 64 file (first 64 bytes), inspect encodings/headers.
• tailspin (tspin) — auto-highlight logs: tspin app.log or cmd | tspin.
• btop — interactive system monitor.
• grex — generate regular expressions from user-provided test cases:
  • grex a b c (returns ^[a-c]$)
  • grex -d -w -p email@example.com (generate with digits, words, non-space)
• typos — fast source-code spell checker (skips code identifiers sensibly):
  • typos (check the tree), typos -w (auto-fix), typos path/to/file
  • Good as a pre-commit gate and before shipping docs; low false-positive rate.
• delta — the git pager, wired in by programs.delta. git diff/log/show/blame render side-by-side with line numbers and n/N to jump hunks. Use git --no-pager diff for raw unified text to parse, or in a narrow terminal.
• difftastic (difft) — the opt-in structural diff: compares ASTs, so reflow is not a change. delta highlights a line diff; difft changes what counts as a difference.
  • difft old.rs new.rs (standalone), or for one command: GIT_EXTERNAL_DIFF=difft git diff
  • Reach for it only when a plain diff is noisy because indentation or wrapping moved but the code didn't.

Terminal multiplexing: tmux.

Benchmark

• hyperfine — CLI command benchmarking with stats:
  • hyperfine 'rg foo' 'grep -r foo .' (compare), --warmup 3.
• oha — HTTP load (see above).

Domain & infra tools (know these exist)

Candidates for specialized work. Availability varies by machine; check the executable and the project's own targets before choosing one.

For tools outside this list, prefer an existing dependency or native capability. Install only within the task's authorization and the project's tool-management convention.

When NOT to substitute

• Portable shell scripts that may run on minimal/other machines → stick to POSIX (grep, sed, find, curl) so they don't depend on this toolbelt.

• Pure-JSON pipelines → jq remains the default (per global CLAUDE.md).

• For a tool command -v cannot find, comma fetches and runs any nixpkgs binary on demand. Its command name is a single comma, so it reads oddly inline:

  , ffmpeg -i in.mov out.mp4
  

  Good for a one-off; reaching for the same tool repeatedly is a signal to add it to harus-config. Fall back to the classic when comma is unavailable too.

• command -v <tool> is the check. Tool inventories drift: scripts/tools is hand-maintained help text, packages.nix declares intent a machine may not have switched to, and this skill's own table is a third copy. Verify against the machine.