Claude Code Bash Patterns

# Claude Code Bash Patterns

**Status**: Production Ready ✅ | **Last Verified**: 2025-11-18

---

## Quick Start

### Basic Command

```bash
ls -la
```

### Command Chaining

```bash
bun install && bun run build && bun test
```

### Hooks

Create `.claude-hook-pretooluse.sh`:

```bash
#!/usr/bin/env bash
# PreToolUse hook - runs before every Bash command

echo "Running: $1"
```

**Load `references/hooks-examples.md` for complete hook patterns.**

---

## The Five Core Patterns

### 1. Sequential Operations (&&)

**Use when**: Each command depends on previous success

```bash
git add . && git commit -m "message" && git push
```

**Why**: Stops chain if any command fails

---

### 2. Parallel Operations (Multiple tool calls)

**Use when**: Commands are independent

```
Message with multiple Bash tool calls in parallel
```

**Load `references/cli-tool-integration.md` for parallel patterns.**

---

### 3. Session Persistence

**Use when**: Need to maintain state across commands

```bash
# Set environment variable
export API_KEY="sk-..."

# Use in later commands (same session)
curl -H "Authorization: Bearer $API_KEY" api.example.com
```

---

### 4. Background Processes

**Use when**: Long-running tasks

```bash
npm run dev &
# Get PID with $!
```

---

### 5. Hooks for Automation

**Use when**: Need pre/post command logic

**Load `references/hooks-examples.md` for all hook types.**

---

## Critical Rules

### Always Do ✅

1. **Use && for sequential dependencies** (not semicolons)
2. **Quote paths with spaces** (`cd "path with spaces"`)
3. **Check environment before destructive ops** (rm, git push --force)
4. **Use specialized tools first** (Read, Grep, Glob before Bash)
5. **Set timeouts for long operations** (up to 10 minutes)
6. **Validate inputs** before passing to shell commands
7. **Use hooks for repeated patterns** (logging, validation)
8. **Maintain session state** (export variables once)
9. **Handle errors explicitly** (check exit codes)
10. **Document custom commands** in .claude/commands/

### Never Do ❌

1. **Never use ; for dependent commands** (use &&)
2. **Never skip quoting paths** with spaces
3. **Never run rm -rf without confirmation**
4. **Never expose secrets** in command output
5. **Never ignore timeout limits** (max 10 min)
6. **Never use bash for file operations** when specialized tools exist
7. **Never chain with newlines** (use && or ; explicitly)
8. **Never force-push to main** without explicit user request
9. **Never skip hooks** (--no-verify) without user request
10. **Never use interactive commands** (git rebase -i, git add -i)

---

## Git Workflows

### Basic Commit

```bash
git add . && git commit -m "feat: add feature"
```

### Commit with Testing

```bash
npm test && git add . && git commit -m "fix: bug fix" && git push
```

### Pull Request

```bash
git checkout -b feature/new && git add . && git commit -m "feat: new feature" && git push -u origin feature/new
```

**Load `references/git-workflows.md` for complete workflows including:**
- Feature branch workflow
- PR creation automation
- Commit message conventions
- Pre-commit validation

---

## Hooks: Advanced Automation

### PreToolUse Hook

**`.claude-hook-pretooluse.sh`**:

```bash
#!/usr/bin/env bash
COMMAND="$1"

# Log all commands
echo "[$(date)] Running: $COMMAND" >> ~/claude-commands.log

# Block dangerous patterns
if [[ "$COMMAND" =~ rm\ -rf\ / ]]; then
    echo "❌ Blocked dangerous command"
    exit 1
fi
```

### Hook Types

- **pretooluse** - Before every Bash command
- **stop** - Before conversation ends
- **user-prompt-submit** - After user submits message

**Load `references/hooks-examples.md` for all hook types and examples.**

---

## CLI Tool Integration

### npm/bun

```bash
bun install && bun run build
```

### wrangler (Cloudflare)

```bash
bunx wrangler deploy
```

### gh (GitHub CLI)

```bash
gh pr create --title "Fix bug" --body "Description"
```

**Load `references/cli-tool-integration.md` for complete tool patterns.**

---

## Custom Commands

Create `.claude/commands/deploy.md`:

```markdown
---
description: Deploy to production
---

Run these steps:
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `wrangler deploy`
```

User can invoke with: `/deploy`

**Load `templates/custom-command-template.md` for template.**

---

## Security

### Allowlisting Tools

**`settings.json`**:

```json
{
  "dangerousCommandsAllowList": [
    "git push --force"
  ]
}
```

### Secrets Management

```bash
# ✅ Good: Use environment variables
export API_KEY="$SECURE_VALUE"

# ❌ Bad: Hardcode secrets
curl -H "Authorization: Bearer sk-abc123..."
```

**Load `references/security-best-practices.md` for complete security guide.**

---

## Common Use Cases

### Use Case 1: Test Before Commit

```bash
npm test && git add . && git commit -m "message"
```

### Use Case 2: Deploy with Validation

```bash
npm run lint && npm test && npm run build && bunx wrangler deploy
```

### Use Case 3: Multi-Repo Operations

```bash
cd repo1 && git pull && cd ../repo2 && git pull
```

### Use Case 4: Background Process

```bash
npm run dev &
```

**Load `references/cli-tool-integration.md` for more patterns.**

---

## Troubleshooting

### Issue: Command times out

**Solution**: Increase timeout or use background mode

```bash
# Background mode
npm run dev &
```

### Issue: Path with spaces fails

**Solution**: Quote the path

```bash
cd "path with spaces/file.txt"
```

### Issue: Hook blocks command

**Solution**: Check hook logic in `.claude-hook-pretooluse.sh`

**Load `references/troubleshooting-guide.md` for all issues.**

---

## When to Load References

### Load `references/git-workflows.md` when:
- Setting up git automation
- Creating PRs programmatically
- Need commit message conventions
- Want pre-commit validation patterns

### Load `references/hooks-examples.md` when:
- Creating custom hooks
- Need hook templates
- Want validation patterns
- Implementing logging/security

### Load `references/cli-tool-integration.md` when:
- Orchestrating multiple CLI tools
- Need tool-specific patterns
- Want parallel execution examples
- Troubleshooting tool integration

### Load `references/security-best-practices.md` when:
- Configuring security guards
- Setting up allowlisting
- Managing secrets
- Preventing dangerous operations

### Load `references/troubleshooting-guide.md` when:
- Debugging command failures
- Encountering timeouts
- Hooks behaving unexpectedly
- Session state issues

---

## Using Bundled Resources

### References (references/)

- **git-workflows.md** - Complete git automation patterns
- **hooks-examples.md** - All hook types with examples
- **cli-tool-integration.md** - Tool orchestration patterns
- **security-best-practices.md** - Security configuration guide
- **troubleshooting-guide.md** - Common issues and solutions

### Templates (templates/)

- **custom-command-template.md** - Custom command template
- **settings.json** - Security settings example
- **.envrc.example** - Environment variables example
- **github-workflow.yml** - GitHub Actions integration
- **dangerous-commands.json** - Dangerous patterns list

---

## Examples

### Feature Development Workflow

```bash
git checkout -b feature/oauth && \
  npm test && \
  git add . && \
  git commit -m "feat(auth): add OAuth support" && \
  git push -u origin feature/oauth
```

### CI/CD Pipeline

```bash
npm run lint && \
  npm test && \
  npm run build && \
  bunx wrangler deploy
```

### Multi-Project Update

```bash
cd project1 && bun install && cd ../project2 && bun install
```

---

## Official Documentation

- **Claude Code Bash Tool**: https://docs.claude.com/en/docs/claude-code/tools
- **Hooks**: https://docs.claude.com/en/docs/claude-code/hooks
- **Custom Commands**: https://docs.claude.com/en/docs/claude-code/custom-commands

---

**Questions? Issues?**

1. Check `references/troubleshooting-guide.md` for common issues
2. Review `references/git-workflows.md` for git patterns
3. See `references/hooks-examples.md` for automation
4. Load `references/security-best-practices.md` for security