claude-code-bash-patterns

What this skill does

# Claude Code Bash Patterns

**Status**: Production Ready ✅
**Last Updated**: 2025-11-07
**Dependencies**: Claude Code CLI (latest version)
**Official Docs**: https://docs.claude.com/en/docs/claude-code/tools

---

## Quick Start (10 Minutes)

### 1. Understanding the Bash Tool

The Bash tool is Claude Code's primary interface for executing command-line operations. Unlike specialized tools (Read, Grep, Glob), the Bash tool provides direct shell access for complex workflows.

**Key Characteristics**:
- **Session Persistence**: Commands run in a persistent bash session within a conversation
- **Environment Inheritance**: Inherits environment variables and working directory
- **Output Limit**: Truncates output at 30,000 characters
- **Default Timeout**: 2 minutes (configurable up to 10 minutes)

**When to Use Bash Tool**:
- ✅ Running CLI tools (git, npm, wrangler, gh, etc.)
- ✅ Command chaining (sequential operations)
- ✅ Process orchestration (build, test, deploy)
- ✅ Environment setup and management

**When NOT to Use Bash Tool**:
- ❌ Reading files → Use **Read** tool instead
- ❌ Searching file patterns → Use **Glob** tool instead
- ❌ Searching content → Use **Grep** tool instead
- ❌ Editing files → Use **Edit** tool instead

### 2. Basic Command Patterns

```bash
# Single command
npm install

# Sequential with && (stops on first failure)
npm install && npm run build

# Sequential with ; (continues regardless)
npm install ; npm run build

# Parallel execution (make multiple Bash tool calls)
# Call 1: git status
# Call 2: git diff
# Call 3: git log
```

**Golden Rule**: Use `&&` when you care about failures, `;` when you don't, and parallel calls when operations are independent.

### 3. Configure Your First Hook

Hooks let you run code before/after tool execution. Here's a simple audit logger:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date -Iseconds)] $(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.tool_input.command')\" >> ~/.claude/bash-audit.log"
          }
        ]
      }
    ]
  }
}
```

Save this to `~/.claude/settings.json` to log every bash command with timestamp.

---

## The Five Core Patterns

### Pattern 1: Command Chaining

**When to Use**: Sequential operations where each depends on previous success

**Syntax**: `command1 && command2 && command3`

**Example**: Build and deploy workflow
```bash
npm install && npm run build && npx wrangler deploy
```

**Why It Matters**:
- Stops on first failure (prevents cascading errors)
- Maintains clean error messages (know exactly what failed)
- Saves tokens (no need to check status between commands)

**Anti-Pattern**: Using `;` when you care about failures
```bash
# ❌ Wrong: Continues even if install fails
npm install ; npm run build

# ✅ Correct: Stops if install fails
npm install && npm run build
```

**Advanced**: Conditional execution with `||`
```bash
# Run tests, or echo failure message
npm test || echo "Tests failed, not deploying"

# Try npm ci, fall back to npm install
npm ci || npm install
```

### Pattern 2: Parallel Execution

**When to Use**: Independent operations that can run simultaneously

**How**: Make multiple Bash tool calls in a single message

**Example**: Git workflow pre-commit analysis
```
# Claude makes 3 parallel Bash calls in one message:
Call 1: git status
Call 2: git diff --staged
Call 3: git log -5 --oneline
```

**Benefits**:
- ~40% faster than sequential (no waiting between calls)
- Reduces context usage (all results arrive together)
- Better user experience (appears instant)

**Important**: Only parallelize truly independent operations. If Call 2 depends on Call 1's output, run sequentially.

### Pattern 3: HEREDOC for Multi-Line Content

**When to Use**: Git commits, file creation, complex strings with newlines

**Syntax**: `cat <<'EOF' ... EOF`

**Example**: Git commit with detailed message
```bash
git commit -m "$(cat <<'EOF'
feat(auth): Add JWT verification middleware

Implement custom JWT template support for Clerk auth.
Extracts email and metadata claims for user context.

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>
EOF
)"
```

**Why Single Quotes**: `<<'EOF'` prevents variable expansion in the content. Use `<<"EOF"` if you want variables to expand.

**Common Mistake**: Forgetting quotes around `$()` wrapper
```bash
# ❌ Wrong: Newlines lost
git commit -m $(cat <<'EOF'
Line 1
Line 2
EOF
)

# ✅ Correct: Preserves newlines
git commit -m "$(cat <<'EOF'
Line 1
Line 2
EOF
)"
```

### Pattern 4: Output Capture and Processing

**When to Use**: Need to process command output before using it

**Pattern**: Command substitution with `$()`

**Example**: Get current branch name
```bash
BRANCH=$(git rev-parse --abbrev-ref HEAD)
echo "Current branch: $BRANCH"
```

**Example**: Conditional logic based on output
```bash
if git diff --quiet; then
  echo "No changes detected"
else
  echo "Changes detected, running tests..."
  npm test
fi
```

**Limitation**: Output truncated at 30,000 characters. For large outputs:
```bash
# Limit output
npm test 2>&1 | head -100

# Or save to file
npm test > test-results.txt && tail -50 test-results.txt
```

### Pattern 5: Conditional Execution

**When to Use**: Different actions based on conditions

**Pattern**: Test commands with `&&` / `||`

**Example**: Run tests only if files changed
```bash
git diff --quiet || npm test
```

**Example**: Different commands based on file existence
```bash
[ -f package-lock.json ] && npm ci || npm install
```

**Example**: Multi-condition logic
```bash
if [ -f pnpm-lock.yaml ]; then
  pnpm install
elif [ -f yarn.lock ]; then
  yarn install
else
  npm install
fi
```

---

## Hooks: Advanced Automation

Hooks are shell commands or Claude prompts that run before/after tool execution. They're your security guards, cleanup crew, and automation helpers.

### PreToolUse: The Security Guard

**Purpose**: Runs before tool execution, can block or modify behavior

**Exit Codes**:
- `0` = Allow execution
- `1` = Block with generic error
- `2` = Block with custom error message (from stderr)

#### Use Case 1: Block Dangerous Commands

**File**: `~/.claude/hooks/dangerous-command-guard.py`
```python
#!/usr/bin/env python3
import json
import sys
import re

# Read hook input from stdin
data = json.load(sys.stdin)
command = data.get('tool_input', {}).get('command', '')

# Dangerous patterns to block
DANGEROUS = [
    r'rm\s+-rf\s+/',           # Delete root
    r'dd\s+if=',                # Disk operations
    r'mkfs\.',                  # Format filesystem
    r':()\{.*\}:',              # Fork bomb
    r'sudo\s+rm',               # Sudo delete
    r'git\s+push.*--force.*main',  # Force push to main
]

for pattern in DANGEROUS:
    if re.search(pattern, command):
        print(f"BLOCKED: Dangerous command pattern '{pattern}'", file=sys.stderr)
        sys.exit(2)

# Allow execution
sys.exit(0)
```

**Settings Configuration**:
```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/dangerous-command-guard.py"
          }
        ]
      }
    ]
  }
}
```

#### Use Case 2: Log All Bash Commands

```json
{
  "matcher": "Bash",
  "hooks": [
    {
      "type": "command",
      "command": "echo \"[$(date -Iseconds)] $(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.tool_input.command')\" >> ~/.claude/bash-audit.log"
    }
  ]
}
```

**Result**: Every bash command logged with timestamp to `~/.claude/bash-audit.log`

#### Use Case 3: Enforce Package Manager

Check for lockfile and block wrong package manager:

```bash
#!/bin/bash
# File: ~/.claude/hooks/package-manager-enforcer.sh

COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.tool_input.command')

if [ -f pnpm-lock.yaml ] && echo "$COMMAND" | grep -qE '^(npm|yarn) '; then
  echo "ERROR: This repo uses