Advanced Patterns

Headless / CI Usage

Run Claude non-interactively in scripts, pipelines, and CI/CD:

# One-shot, structured output
claude -p "fix all lint errors" --permissions acceptEdits --output-format json

# Check success/failure
if claude -p "run tests and fix failures" --permissions acceptEdits; then
  echo "Done"
else
  echo "Failed" && exit 1
fi

# Stream JSON for large outputs
claude -p "analyze entire codebase" --output-format stream-json | jq -c '.content'

GitHub Actions Example

- name: Claude Code Review
  run: |
    git diff origin/main | claude -p "review these changes for bugs" \
      --output-format md \
      --model claude-sonnet-4-6

Piping and Composition

# Analyze logs
tail -100 app.log | claude -p "what went wrong?"

# Review a diff
git diff | claude -p "code review, focus on security"

# Fix test failures
npm test 2>&1 | claude -p "fix these test failures" --permissions acceptEdits

# Chain with jq
claude -p "list exported functions" --output-format json \
  | jq -r '.functions[].name'

Custom System Prompts

# Domain-specific assistant
claude --system-prompt "You are a PostgreSQL expert. Focus on query optimization and indexing."

# Append style rules without replacing the default
claude --append-system-prompt "Always use pnpm. Never use npm. Explain every decision."

In CLAUDE.md (applies every session):

## Behavior
- Always explain your reasoning before making changes
- Ask before making changes to more than 3 files at once
- Prefer security over convenience
- Use pnpm, not npm

Context Management for Large Codebases

Exclude large generated directories from reads:

{
  "permissions": {
    "deny": [
      "Read(node_modules/**)",
      "Read(dist/**)",
      "Read(build/**)",
      "Read(.git/**)"
    ]
  }
}

Create a domain-scoped subagent that ignores irrelevant code:

---
name: "frontend-dev"
description: "Frontend development in src/ui/ and src/components/"
---

You focus exclusively on files in `src/ui/` and `src/components/`.
Ignore backend code, database migrations, and infrastructure files.

Multi-Agent Orchestration

Delegate independent tasks to specialized agents in one prompt:

I need three things done in parallel:
1. @Explore: map the entire authentication flow across all files
2. @code-reviewer: review my changes in src/auth/
3. @Plan: design the new OAuth2 integration

Combine the findings into a single implementation plan.

Background Sessions

Run a long task in the background while you continue working:

/background

Or start a session in the background from the CLI:

claude --background "refactor all API handlers to use the new error format"

Session Forking

Branch a session to explore alternatives without losing your current state:

claude --fork-session <session-id>

Extend with apiKeyHelper

Rotate API keys dynamically (useful for temporary credentials):

{
  "apiKeyHelper": "/usr/local/bin/get-claude-key.sh"
}

The script runs before each request and must print an API key to stdout.

Minimal CI Security Profile

Lock down permissions to the minimum needed in CI:

{
  "permissions": {
    "allow": [
      "Read",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm *)",
      "Edit(/secrets/**)",
      "WebFetch"
    ]
  },
  "defaultMode": "dontAsk"
}

Multiple Working Directories

# Grant access to a shared library alongside the project
claude --add-dir /path/to/shared-lib

# Or in settings.json
{
  "additionalDirectories": ["/path/to/shared-lib"]
}

Rewind / Checkpoints

Undo recent file changes (requires fileCheckpointingEnabled: true):

Esc + Esc    # rewind to previous state
/rewind      # view checkpoint history

Output Styles

Create a custom output style in .claude/output-styles/concise.md:

---
name: "concise"
description: "Short, direct responses with minimal explanation"
---

Respond concisely. Skip preamble. Use bullet points. No filler phrases.

Activate with:

/output-style concise

🧠 Quick Recall

• Trick: “claude -p turns Claude into a Unix filter: pipe in, JSON out.”

👨‍🏫 Teach It

• Show: git diff main | claude -p "review" --output-format json | jq — one line.
• They’ll trip on: scripting without --output-format json and parsing prose.

---

Learning path: ⬅ 32-agent-teams.md · Index · ➡ 34-routines-scheduling.md