jackspace/claudeskillz/claude-code-bash-patterns

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

# 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:

{
  "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

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

# ❌ 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 ||

# 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

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 <noreply@anthropic.com>
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

# ❌ 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

BRANCH=$(git rev-parse --abbrev-ref HEAD)
echo "Current branch: $BRANCH"

Example: Conditional logic based on output

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:

# 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

git diff --quiet || npm test

Example: Different commands based on file existence

[ -f package-lock.json ] && npm ci || npm install

Example: Multi-condition logic

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

#!/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:

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

Use Case 2: Log All Bash Commands

{
  "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:

#!/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 pnpm. Please use 'pnpm' instead of 'npm' or 'yarn'." >&2
  exit 2
fi
 
if [ -f yarn.lock ] && echo "$COMMAND" | grep -qE '^(npm|pnpm) '; then
  echo "ERROR: This repo uses yarn. Please use 'yarn' instead of 'npm' or 'pnpm'." >&2
  exit 2
fi
 
exit 0

PostToolUse: The Cleanup Crew

Purpose: Runs after successful tool execution (exit code 0 only)

Example: Auto-format after file edits

{
  "matcher": "Write|Edit",
  "hooks": [
    {
      "type": "command",
      "command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.tool_input.file_path'); [ -f \"$FILE\" ] && prettier --write \"$FILE\" || true"
    }
  ]
}

Example: Run tests after code changes

{
  "matcher": "Write|Edit",
  "hooks": [
    {
      "type": "command",
      "command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.tool_input.file_path'); if echo \"$FILE\" | grep -qE '\\.(ts|tsx|js|jsx)$'; then npm test -- \"$FILE\"; fi"
    }
  ]
}

SessionStart: Environment Setup

Purpose: Runs once at session start, sets up environment

Example: Load project-specific environment

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "[ -f .envrc ] && source .envrc || true; env > $CLAUDE_ENV_FILE"
          }
        ]
      }
    ]
  }
}

Environment Variables Available in Hooks:

• $CLAUDE_TOOL_INPUT - JSON string of tool call
• $CLAUDE_ENV_FILE - Path to environment file
• Standard env vars ($HOME, $USER, $PWD, etc.)

Git Workflows (Production-Tested)

These patterns are used by Anthropic's engineering team for 90%+ of git interactions.

Pattern: Intelligent Git Commits

Step 1: Gather context (parallel calls)

# Call 1
git status
 
# Call 2
git diff --staged
 
# Call 3
git log -5 --oneline

Why Parallel: Independent operations, faster response, better UX

Step 2: Analyze changes

• Review actual code changes (not just file names!)
• Match commit message style from git log
• Focus on "why" not "what"
• Keep message concise (1-2 sentences)

Step 3: Commit with HEREDOC

git add [files] && 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 <noreply@anthropic.com>
EOF
)"

Step 4: Verify

git status

Important: If pre-commit hook modifies files:

1. Check authorship: git log -1 --format='%an %ae'
2. Check not pushed: git status (should show "ahead of origin")
3. If both safe: git add . && git commit --amend --no-edit
4. If not safe: git add . && git commit -m "Apply pre-commit hook changes"

Pattern: Pull Request Creation

Step 1: Understand branch state (parallel)

# Call 1
git status
 
# Call 2
git diff main...HEAD
 
# Call 3
git log main..HEAD --oneline

Step 2: Analyze ALL commits (not just latest!)

• What changed since branch diverged from main?
• What's the overall goal of this branch?
• What needs testing?

Step 3: Create PR with gh CLI

gh pr create --title "feat: User Authentication" --body "$(cat <<'EOF'
## Summary
- Implement JWT verification with Clerk
- Add login/logout endpoints
- Update database schema for users table
 
## Test Plan
- [ ] Verify JWT token validation
- [ ] Test login flow
- [ ] Test logout flow
- [ ] Confirm database migrations work
 
🤖 Generated with Claude Code
EOF
)"

Result: Professional PR with clear summary and test plan

CLI Tool Integration

GitHub CLI (gh)

Claude knows gh CLI by default. Common patterns:

# View PR comments
gh api repos/owner/repo/pulls/123/comments
 
# Check CI status
gh run list --limit 5
 
# Create issue
gh issue create --title "Bug: Description" --body "Details here"
 
# Comment on PR
gh pr comment 123 --body "LGTM! 🚀"