Bash Expert

Caution

Ad-hoc bash is the leading cause of deploy incidents. Missing set -euo pipefail, unquoted variables, hardcoded /usr/local paths — each one is a time bomb. The agent writes scripts that are correct by construction, not by luck.

Tip

Trigger by describing the script you need. “create a setup script for my plugin”, “bash script to check homebrew services”, “install script for macOS and Linux” — the agent picks the right template, adds error handling, and validates syntax before handing back the file.

Quick reference

Field	Value
Model	opus
Tools	Read, Write, Edit, Glob, Grep, Bash, WebFetch
Triggers	”create script”, “bash script”, “shell script”, “install script”, “setup script”
Output	`.sh` file + `bash -n` + ShellCheck report

When to use

Plugin lifecycle scripts — setup, install, teardown, version-bump for brewcode/brewtools/brewui/brewdoc
CI helper scripts — health checks, service validation, environment bootstrap
Cross-platform portability — script must run on both macOS (ARM + Intel) and Linux without modification
Structured output — script prints markdown tables or phase headers consumed by Claude Code skills
Idempotent installers — safe to re-run; checks state before mutating

Examples

# Natural language triggers
"create a setup script for the brewtools plugin"
"bash script to check if all homebrew services are running"
"write an install script that works on macOS and Linux"

# Direct invocation
/brewcode bash-expert — write a multi-mode script with status/install/help commands

# Plugin path context automatically injected
"create a version-bump script using BC_PLUGIN_ROOT"

Flow

Analyze the request
Reads existing scripts in the repo (Glob + Grep) to match conventions. Identifies target platform, required commands, and expected output format before writing a single line.
Choose a template
Minimal (single-purpose, ≤20 lines) or full multi-mode dispatch (`CMD="${1:-help}"` + case block). Plugin scripts always get SCRIPT_DIR self-location and $BC_PLUGIN_ROOT awareness.
Implement
Writes the script with set -euo pipefail, quoted variables, trap cleanup EXIT where needed, and status symbols (✅ ❌ ⚠️) in output. macOS/Linux divergences handled via platform detection, not hardcoded paths.
Validate
Runs bash -n script.sh (syntax check) and shellcheck script.sh (static analysis). Fixes all ShellCheck warnings before reporting.
Report
Prints a structured summary: file path, purpose, platform, and a checklist of verified properties. You get a ready-to-run script, not a draft.

Internals — patterns, templates, and platform handling

Strict mode and error handling

Pattern	Example	Use
Strict mode	`set -euo pipefail`	Every script, always
Exit on fail	`cmd \|\| exit 1`	Critical steps
Capture code	`cmd; EC=$?`	Conditional branching
Default value	`${VAR:-default}`	Missing vars
Required var	`${VAR:?error msg}`	Mandatory args
Cleanup trap	`trap cleanup EXIT`	Temp files, locks

Arguments

Type	Pattern
Positional with default	`CMD="${1:-help}"`
Flag parsing	`while getopts "hvdf:" opt; do case $opt in ...`
Keyword detection	`[[ "$ARG" =~ (install\|setup) ]] && MODE="install"`

Minimal template

#!/bin/bash
set -euo pipefail
ARG="${1:-}"
[[ -z "$ARG" ]] && { echo "Usage: script.sh <arg>"; exit 1; }
echo "Processing: $ARG"
echo "✅ Done"

macOS vs Linux divergences

Feature	macOS	Linux
Brew prefix	`/opt/homebrew` (ARM), `/usr/local` (Intel)	`/home/linuxbrew/.linuxbrew`
timeout	`gtimeout` (coreutils)	`timeout`
sed in-place	`sed -i ''`	`sed -i`
readlink	`greadlink -f`	`readlink -f`

Always derive prefix via $(brew --prefix) — never hardcode.

Homebrew service operations

Op	Command
Check installed	`brew list PKG &>/dev/null`
Install	`brew install PKG`
Service start	`brew services start PKG`
Service status	`brew services list \| grep PKG \| grep started`

JSON parsing fallback chain

jq -r '.key' file.json
python3 -c "import json,sys;print(json.load(sys.stdin)['key'])"
grep -oP '"key":\s*"\K[^"]+' file.json

Plugin path variables

Variable	Available in
`$CLAUDE_PLUGIN_ROOT`	Hooks only
`${CLAUDE_SKILL_DIR}`	Skills (string substitution)
`$BC_PLUGIN_ROOT`	Agents (injected by `pre-task.mjs`)

Anti-patterns

Avoid	Prefer
`[ $VAR ]`	`[[ -n "$VAR" ]]`
`cat file \| grep`	`grep X file`
`ls \| while read`	`find -exec` or glob
`cd dir; cmd; cd -`	`(cd dir && cmd)`
`echo $VAR`	`echo "$VAR"`
`if [ $? -eq 0 ]`	`if cmd; then`
`/usr/local` hardcoded	`$(brew --prefix)`

Delivery checklist

#	Check
1	`#!/bin/bash` shebang
2	`set -euo pipefail`
3	Usage header comment
4	`shellcheck` clean
5	`bash -n` passes
6	`help` subcommand works
7	Error paths tested
8	Idempotent — safe re-run

💻

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.