agent-loadout

One command to load out your terminal for agentic coding.

npx agent-loadout

Why this exists

AI coding agents are only as good as the tools on the machine. A fresh Mac has few of them. agent-loadout installs a curated set of 37 terminal tools — the ones that actually matter for agentic workflows.

Pick presets, toggle individual tools, and get a verified installation with skill files your agent can read.

Tool catalog

Core (9 tools) — on by default

| Tool | Package | Description | |------|---------|-------------| | ripgrep | ripgrep | Fast code search | | fd | fd | Fast file finder | | jq | jq | JSON processor | | yq | yq | YAML processor | | bat | bat | Cat with syntax highlighting | | tree | tree | Directory structure viewer | | GitHub CLI | gh | PRs, issues, releases from the terminal | | fzf | fzf | Fuzzy finder | | xh | xh | Friendly HTTP client |

Agent (11 tools) — on by default

| Tool | Package | Description | |------|---------|-------------| | shellcheck | shellcheck | Static analysis for shell scripts | | ast-grep | ast-grep | Structural code search/replace | | just | just | Command runner (agent-readable task menu) | | grex | grex | Generate regex from examples | | knip | knip | Find unused code/deps in TS/JS | | sd | sd | Simpler sed replacement | | hyperfine | hyperfine | CLI benchmarking | | tokei | tokei | Code statistics | | tldr | tldr | Quick man page summaries | | biome | biome | Lint + format JS/TS | | difftastic | difftastic | Structural/AST diff |

Media (4 tools)

| Tool | Package | Description | |------|---------|-------------| | ffmpeg | ffmpeg | Audio/video Swiss army knife | | exiftool | exiftool | Image/media metadata | | ImageMagick | imagemagick | Image transforms | | svgo | svgo | SVG optimiser |

DX (10 tools)

| Tool | Package | Description | |------|---------|-------------| | eza | eza | Modern ls replacement | | zoxide | zoxide | Smarter cd | | delta | git-delta | Better git diffs | | glow | glow | Terminal markdown renderer | | mise | mise | Runtime version manager | | watchexec | watchexec | Run commands on file change | | mkcert | mkcert | Local HTTPS certs | | lazygit | lazygit | TUI git client | | dust | dust | Disk usage tree | | bottom | bottom | System monitor TUI |

Security (3 tools)

| Tool | Package | Description | |------|---------|-------------| | trivy | trivy | Vulnerability scanner | | act | act | Run GitHub Actions locally | | gitleaks | gitleaks | Secrets scanner |

How it works

1. Choose presets — Core and Agent are on by default; toggle Media, DX, Security
2. Toggle tools — Deselect anything you don't want
3. Preview — See the exact Brewfile and npm commands before anything runs
4. Install — Runs brew bundle and npm install -g for you
5. Verify — Checks every tool is actually working
6. Persist — Writes a receipt and skill files your AI agent can read

Commands

# Interactive install (default)
npx agent-loadout

# Install specific presets (dry run)
npx agent-loadout install --preset core agent

# Install specific presets (actually run it)
npx agent-loadout install --preset core agent --apply

# Install everything
npx agent-loadout install --all --apply

# Check what's installed
npx agent-loadout verify
npx agent-loadout verify --json

# List the full catalog
npx agent-loadout list
npx agent-loadout list --json

Brewfile alternative

Don't want the CLI? Copy the Brewfile, uncomment what you need, and run:

brew bundle

Skills

When you install tools, agent-loadout writes skill files to ~/.claude/skills/. Each skill is a focused playbook — what the tool does, trusted commands, gotchas — so your AI agent knows how to use it effectively.

Requirements

• macOS with Homebrew installed
• Node.js 20+ (for npx)
• npm (optional, only needed for knip and svgo)

Contributing

1. Fork and clone
2. pnpm install
3. pnpm dev -- list to run locally
4. Add tools in src/catalog.ts, skills in src/skills.ts
5. pnpm typecheck before submitting

Releasing

# Create a GitHub release — CI publishes to npm automatically
gh release create v0.2.0 --generate-notes

# The release workflow:
# extracts version from tag → syncs package.json → typecheck → build → npm publish

Requires NPM_TOKEN secret set in the repository settings.

License

MIT