CLI Tools for AI Coding Agents on macOS

README.md

CLI Tools for AI Coding Agents on macOS

AI coding agents such as Claude Code, OpenCode, Codex, and local-model agents frequently use command-line tools to inspect repositories, search code, process structured data, run tests, and understand changes.

This guide installs a useful set of modern CLI tools on macOS using Homebrew.

Prerequisites

This guide assumes Homebrew is already installed.

Verify it with:

brew --version

If needed, see the Homebrew website for installation instructions.

Recommended Installation

Install the complete toolkit with:

brew install \
    ripgrep \
    fd \
    jq \
    yq \
    ast-grep \
    shellcheck \
    gh \
    bat \
    fzf \
    tree \
    hyperfine \
    watchexec \
    difftastic \
    git-delta \
    tokei

Homebrew will skip or update packages as appropriate if some are already installed.

---

1. ripgrep (rg)

Purpose: Fast recursive text and source-code search.

brew install ripgrep

Examples:

rg "TODO"
rg "class MyViewController"
rg "async throws" --type swift

Why agents benefit:

• Extremely fast recursive searching
• Respects .gitignore
• Supports regular expressions
• Can restrict searches by file type
• Excellent for finding symbols, strings, errors, and references

This is one of the most commonly useful tools for coding agents.

---

2. fd

Purpose: Fast, user-friendly alternative to find.

brew install fd

Examples:

fd Package.swift
fd '\.swift$'
fd test
fd Config

Why agents benefit:

• Simple syntax
• Fast repository traversal
• Respects .gitignore
• Avoids searching generated directories unnecessarily

A useful division of labor is:

• fd --- find files
• rg --- find text inside files

---

3. jq

Purpose: Query, transform, and filter JSON.

brew install jq

Examples:

cat package.json | jq .

jq '.dependencies' package.json

gh api repos/OWNER/REPO/pulls | jq '.[] | {number, title}'

Why agents benefit:

APIs and development tools frequently produce JSON. Instead of loading a huge JSON response into the model context, an agent can extract exactly the information it needs.

This can substantially reduce unnecessary context usage.

---

4. yq

Purpose: Query and modify YAML and other structured formats.

brew install yq

Examples:

yq '.services' docker-compose.yml

yq '.name' config.yaml

Why agents benefit:

Agents frequently work with:

• YAML
• CI configurations
• Docker Compose
• Kubernetes
• GitHub Actions
• configuration files

Modern yq can also process formats including JSON, XML, CSV, and properties documents.

---

5. ast-grep (sg)

Purpose: Search and rewrite source code using syntax trees instead of plain text.

brew install ast-grep

Why agents benefit:

This is particularly valuable for refactoring. An agent can reason about the structure of code instead of trying to approximate syntax with regular expressions.

Good uses include:

• finding function calls
• locating particular language constructs
• identifying structural patterns
• performing syntax-aware replacements
• large refactoring operations
• creating code lint rules

Use rg for ordinary text searches and consider ast-grep when the question is about code structure.

---

6. ShellCheck

Purpose: Static analysis and linting for shell scripts.

brew install shellcheck

Example:

shellcheck script.sh

Why agents benefit:

It creates a deterministic feedback loop:

1. Generate shell script
2. Run ShellCheck
3. Inspect warnings
4. Fix script
5. Run ShellCheck again
6. Execute script

This is especially valuable because agents frequently generate Bash and zsh scripts.

---

7. GitHub CLI (gh)

Purpose: Work with GitHub directly from the terminal.

brew install gh

Authenticate:

gh auth login

Examples:

gh issue list
gh issue view 123
gh pr list
gh pr view 42
gh pr diff 42
gh run list
gh run view
gh repo view

Why agents benefit:

gh lets an agent interact with:

• repositories
• pull requests
• issues
• GitHub Actions
• releases
• GitHub APIs

It can eliminate the need to manually navigate the GitHub website for many development workflows.

---

8. bat

Purpose: Modern alternative to cat for viewing files.

brew install bat

Examples:

bat Package.swift
bat README.md

Why agents benefit:

bat provides features such as:

• syntax highlighting
• line numbers
• Git change indicators
• paging

For machine processing, ordinary cat is still perfectly appropriate. bat is especially useful when terminal output is being inspected by a person.

---

9. fzf

Purpose: General-purpose fuzzy finder.

brew install fzf

Example:

fd | fzf

Or:

git branch | fzf

Why agents benefit:

It is useful for interactive terminal workflows and for quickly selecting from large collections of files, branches, commands, or other values.

It is generally more useful to human-driven and interactive agent workflows than fully autonomous ones.

---

10. tree

Purpose: Display directory structures.

brew install tree

Examples:

tree
tree -L 2
tree -L 3 Sources

Why agents benefit:

A shallow tree is an excellent way for an agent to quickly understand repository organization without reading every file.

Prefer bounded depth for large repositories:

tree -L 2

rather than dumping the entire repository.

---

11. hyperfine

Purpose: Command-line benchmarking.

brew install hyperfine

Example:

hyperfine './old-version' './new-version'

Or:

hyperfine 'rg foo' 'grep -R foo .'

Why agents benefit:

Performance work benefits enormously from measurable feedback.

An agent can:

1. Establish a baseline
2. Modify the implementation
3. Benchmark again
4. Compare results
5. Continue iterating

This makes it especially useful for optimization tasks and agent "quests."

---

12. watchexec

Purpose: Automatically execute commands when files change.

brew install watchexec

Example:

watchexec swift test

Why agents benefit:

It can create rapid development feedback loops for:

• tests
• builds
• linters
• generators
• scripts

This is useful when an agent or developer is repeatedly changing files and validating the result.

---

13. difftastic

Purpose: Syntax-aware diffing.

brew install difftastic

Why agents benefit:

Traditional diffs operate on lines. Difftastic understands programming-language syntax, which can make substantial refactorings easier to understand.

It is particularly useful when:

• functions move
• expressions are restructured
• indentation changes
• code is reorganized
• large refactorings occur

The executable is commonly invoked as:

difft

---

14. git-delta (delta)

Purpose: Improved display of Git diffs.

brew install git-delta

The executable is:

delta

Why agents benefit:

Delta makes ordinary Git diffs easier to inspect and can provide improved syntax highlighting and navigation.

It is complementary to Difftastic:

• delta --- improved presentation of traditional Git diffs
• difftastic --- syntax-aware structural diffing

---

15. tokei

Purpose: Analyze source-code statistics.

brew install tokei

Run it in a repository:

tokei

Why agents benefit:

It gives an agent a quick picture of a codebase, including:

• languages
• number of files
• lines of code
• comments
• blank lines

This can help an agent understand the scale and composition of an unfamiliar repository before beginning work.

---

Suggested Agent Instructions

Installing these tools does not guarantee an AI coding agent will use them. Some agents have built-in search and file tools, while others primarily execute shell commands.

Consider adding instructions like these to your project's AGENTS.md or equivalent agent configuration:

## Command-Line Tools

Prefer these command-line tools when appropriate:

- Use `rg` instead of `grep` for recursive source-code searches.
- Use `fd` instead of `find` for locating files.
- Use `jq` for querying and transforming JSON.
- Use `yq` for YAML and other supported structured configuration formats.
- Use `ast-grep` (`sg`) when structural code search is more appropriate
  than text or regular-expression search.
- Use `shellcheck` to validate generated shell scripts.
- Use `gh` for GitHub repositories, issues, pull requests, Actions,
  releases, and API operations.
- Use `tree -L <depth>` for a bounded overview of repository structure.
- Use `hyperfine` when comparing command or implementation performance.
- Use `watchexec` when a file-change-driven test/build loop is useful.
- Use `difft` for syntax-aware diffs.
- Use `delta` for improved traditional Git diff presentation.
- Use `tokei` to quickly understand repository size and language composition.

Avoid producing enormous command outputs. Filter output with tools such as
`rg`, `jq`, `yq`, `head`, or other appropriate commands before adding it
to the model context.

Verify the Installation

After installing everything:

command -v rg
command -v fd
command -v jq
command -v yq
command -v sg
command -v shellcheck
command -v gh
command -v bat
command -v fzf
command -v tree
command -v hyperfine
command -v watchexec
command -v difft
command -v delta
command -v tokei

You can also inspect the Homebrew packages:

brew list --versions \
    ripgrep \
    fd \
    jq \
    yq \
    ast-grep \
    shellcheck \
    gh \
    bat \
    fzf \
    tree \
    hyperfine \
    watchexec \
    difftastic \
    git-delta \
    tokei

Recommended Core Set

If you do not want the entire collection, start with:

brew install \
    ripgrep \
    fd \
    jq \
    yq \
    ast-grep \
    shellcheck \
    gh

These provide the greatest general benefit to coding agents.

Quick Reference

Command Homebrew package Primary use

---

rg ripgrep Text/code search fd fd File discovery jq jq JSON processing yq yq YAML/structured data sg ast-grep AST-aware code search/rewrite shellcheck shellcheck Shell linting gh gh GitHub operations bat bat Enhanced file viewing fzf fzf Fuzzy selection tree tree Directory visualization hyperfine hyperfine Benchmarking watchexec watchexec File-change automation difft difftastic Syntax-aware diffs delta git-delta Enhanced Git diffs tokei tokei Codebase statistics