Headless Mode and CLI Automation — מצב ללא ממשק ואוטומציה בשורת הפקודה

# בדיקת Claude Code
claude --version   # צריך 2.1.81 ומעלה

# בדיקת API key
echo $ANTHROPIC_API_KEY | head -c 10   # צריך להתחיל ב-sk-ant

# בדיקת jq
jq --version   # אם לא מותקן: brew install jq (macOS) / sudo apt install jq (Linux)

# בדיקת bash
bash --version   # צריך 4+ (macOS: brew install bash אם גרסה 3)

# Windows? בדקו WSL:
wsl --list   # אם לא מותקן: wsl --install בPowerShell כ-admin

מ-Interactive ל-Headless — שינוי הפרדיגמה

בשלושת הקורסים הקודמים עבדתם עם Claude Code בצורה אינטראקטיבית: פתחתם טרמינל, כתבתם prompt, קראתם את התשובה, אישרתם פעולות, שאלתם שאלות המשך. זו שיחה — יש בן אדם בלופ כל הזמן. זה מעולה ללמידה, לתכנון, ולעבודה יצירתית. אבל זה לא מתאים כשצריך שהתהליך ירוץ לבד.

Headless mode (מצב ללא ממשק, נקרא גם CLI mode או Print mode) מסיר את הבן אדם מהמשוואה לחלוטין. Claude מקבל פקודה, מריץ, מייצר פלט, ויוצא. אין back-and-forth, אין אישורים, אין ממשק. זה ההבדל בין לדבר עם עובד לבין לתת לו מעטפה עם הוראות ולקבל את התוצאה מוכנה על השולחן.

למה זה כל כך חשוב? כי כל מה שתלמדו בקורס הזה — CI/CD pipelines, GitHub Actions, SDK-based agents, automated testing, scheduled monitoring — הכל מבוסס על היכולת של Claude Code לרוץ בלי בן אדם. בלי Headless mode, אין אוטומציה.

דוגמאות מייצגות: מה אנשים עושים עם Headless mode

כדי להבין את הטווח של מה שאפשר לעשות, הנה כמה תרחישים נפוצים:

• Code review אוטומטי: כל PR שנפתח מקבל סקירת קוד מ-Claude בתוך 30 שניות — עם הערות על שורות ספציפיות
• Release notes: כשעושים git tag, סקריפט מייצר release notes מסוכמים מהcommits האחרונים
• ניטור יומי: cron job שכל בוקר בודק את הלוגים מהלילה ומזהה חריגות
• Documentation sync: כשמשנים API, Claude מעדכן אוטומטית את ה-docs להתאים לקוד
• Migration generation: מתארים שינוי ב-schema בשפה טבעית, Claude מייצר SQL migration
• Test generation: Claude כותב בדיקות יחידה לכל פונקציה חדשה שנכנסת ל-codebase

כל התרחישים האלה חולקים מאפיין משותף: הם חוזרים על עצמם, לא דורשים שיקול דעת אנושי בכל הרצה, ו-מייצרים ערך מצטבר. אם המשימה שלכם עונה על שלושת הקריטריונים האלה — היא מועמדת מצוינת ל-headless.

המעבר המנטלי — מ-"משתמש" ל-"אדריכל"

השינוי הכי חשוב הוא לא טכני — הוא מנטלי. כש-Claude Code רץ אינטראקטיבית, אתם משתמשים שמנהלים שיחה. כש-Claude Code רץ Headless, אתם אדריכלים שמעצבים מערכות אוטומטיות. חשבו על זה ככה: בשיחה אינטראקטיבית, אם Claude לא הבין — אתם מבהירים. ב-headless, ה-prompt צריך להיות מושלם מראש כי אין הזדמנות שנייה. זו אמנות שונה לגמרי.

ההבדל הזה משפיע על כל מה שתכתבו מעכשיו: prompts צריכים להיות מדויקים יותר, error handling צריך להיות מובנה מראש, ותכנון הפלט צריך לקחת בחשבון שמחשב — לא בן אדם — קורא את התוצאה. בואו נראה מה זה אומר בפועל:

הדגל -p — הכניסה לעולם ה-Headless

הדגל -p (קיצור של --print) הוא הכלי הבסיסי ביותר: הוא שולח prompt ל-Claude, מקבל תשובה, ומדפיס אותה ל-stdout (הפלט הסטנדרטי). אחרי שהתשובה מודפסת, התהליך נסגר אוטומטית. בניגוד למצב אינטראקטיבי, אין כאן שיחה מתמשכת — זה one-shot.

שימוש בסיסי

claude -p "analyze this codebase and list all TODO comments"

הפקודה הזו מריצה את Claude, הוא מנתח את ה-codebase (כן, יש לו גישה לכלי Read ו-Bash גם ב-headless), מוצא את כל ה-TODOs, ומדפיס את הרשימה. ברגע שהוא סיים — התהליך יוצא עם exit code 0.

שימו לב — Claude ב-headless mode לא "מוגבל" יותר מהמצב האינטראקטיבי. יש לו גישה לאותם כלים בדיוק: Read, Write, Edit, Bash, Grep, Glob, ואפילו WebSearch (אם מורשה). ההבדל היחיד הוא שאין בן אדם שמאשר פעולות — ולכן ההרשאות צריכות להיות מוגדרות מראש דרך --allowedTools או דרך ה-permission system.

שם Session ומעקב

כשמריצים הרבה הרצות headless, חשוב לתת להן שמות שאפשר לעקוב אחריהם:

# שם Session מותאם — קל למצוא אחר כך
claude -p "audit code quality" -n "nightly-audit-$(date +%Y%m%d)"

# השם יופיע ב-session history
claude sessions list | grep "nightly-audit"

שם ה-session לא משפיע על ההתנהגות — הוא רק עוזר לכם לזהות הרצות בהיסטוריה, במיוחד כשיש לכם עשרות הרצות מתוזמנות ביום. בלי שמות, כל ההרצות נראות אותו דבר ב-claude sessions list ואתם לא יודעים איזו הצליחה ואיזו נכשלה.

הדגל --append-system-prompt

לפעמים צריכים להוסיף הוראות ספציפיות בלי לשנות את CLAUDE.md. הדגל --append-system-prompt מאפשר להזריק הנחיות נוספות:

claude -p "review this code" --bare \
    --append-system-prompt "Focus only on security issues. Ignore style."

זה שימושי כשאותו סקריפט צריך לרוץ עם הנחיות שונות בהקשרים שונים — למשל, סקריפט אחד שפעם רץ כ-security audit ופעם כ-performance review.

Exit codes — השפה של הסקריפטים

כל תוכנית בלינוקס מחזירה exit code כשהיא מסיימת. 0 אומר "הצלחה", כל מספר אחר אומר "שגיאה". זה קריטי לסקריפטים כי אפשר לבנות תנאים על סמך זה:

# אם Claude הצליח — הדפס הצלחה. אם נכשל — הדפס שגיאה
claude -p "run tests" && echo "All good" || echo "Something failed"

# שמור את ה-exit code למשתנה
claude -p "check code quality" --bare
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
    echo "Claude failed with exit code $EXIT_CODE"
fi

הפניית פלט — stdout ו-pipes

מכיוון שהפלט יוצא ל-stdout, אפשר לעשות איתו כל מה שעושים עם פלט רגיל בלינוקס. זו הנקודה שהופכת את Claude Code לכלי CLI אמיתי: הוא משתלב ב-pipeline של Unix בדיוק כמו grep, sed, או כל כלי אחר שמייצר טקסט. אפשר לשמור לקובץ, לשמור למשתנה, להעביר ל-pipe, או להוסיף לקובץ קיים:

# שמירה לקובץ
claude -p "list all functions in main.py" --bare > functions.txt

# שמירה למשתנה
RESULT=$(claude -p "summarize README.md" --bare)

# העברה לכלי הבא ב-pipeline
claude -p "list bugs" --bare | grep "CRITICAL"

# הוספה לקובץ קיים (append)
claude -p "analyze errors" --bare >> daily-report.txt

שילוב עם מודלים שונים

לא חייבים להריץ Opus על כל משימה. אחד ההחלטות הכי חשובות ב-headless automation הוא בחירת מודל. Opus חכם יותר אבל יקר פי 5-15 מ-Sonnet, ו-Sonnet מספיק לרוב המשימות האוטומטיות. בחירת מודל חכמה חוסכת כסף משמעותי לאורך זמן:

# Sonnet למשימות רגילות — זול יותר, מהיר יותר
claude -p "quick code review" -m claude-sonnet-4-6

# Opus למשימות שדורשות שיקול דעת עמוק
claude -p "architecture review of entire system" -m claude-opus-4

# Haiku לבדיקות פשוטות — הכי זול
claude -p "check if file exists" -m claude-haiku-3

הדגל --bare — מהירות מקסימלית ל-CI/CD

הדגל --bare הוצג בגרסה 2.1.81 (מרץ 2026) ונועד לסביבות אוטומציה שבהן כל שנייה חשובה. כש-Claude Code מתחיל לרוץ, הוא בדרך כלל טוען hooks, מסנכרן plugins, סורק skills, מתחבר ל-MCP servers, וקורא את CLAUDE.md. כל זה לוקח 2-5 שניות. ב-pipeline של CI שרץ מאות פעמים ביום — זה מצטבר.

--bare מדלג על כל האתחול הזה:

שימו לב: CLAUDE.md כן נטען גם ב---bare. ההוראות שלכם לפרויקט עדיין תקפות. מה שמדולג הם רק הרכיבים הדינמיים שלוקחים זמן לאתחל.

עד כמה --bare מהיר יותר? בבדיקות טיפוסיות, ההבדל הוא 2-5 שניות בזמן startup. זה לא נשמע הרבה, אבל חשבו על CI pipeline שמריץ Claude על 30 PRs ביום — זה 60-150 שניות שנחסכות. ב-batch processing של 100 קבצים, זה 200-500 שניות. ככל שהנפח גדל, החיסכון מצטבר.

מגבלת אימות

ב---bare, אימות חייב לבוא מ-ANTHROPIC_API_KEY כמשתנה סביבה או מ-apiKeyHelper. אימות מבוסס OAuth או Keychain לא זמין במצב bare. זה הגיוני — ב-CI אין מישהו שיכול לאשר חלון OAuth.

# שימוש נכון ב---bare
export ANTHROPIC_API_KEY="sk-ant-..."
claude -p "review this PR" --bare

# --bare חייב לבוא עם -p
claude -p "your prompt" --bare  # נכון
claude --bare                    # לא יעבוד — צריך -p

JSON Output — פלט מובנה לאוטומציה

כברירת מחדל, הפלט של -p הוא טקסט חופשי — נהדר לקריאה אנושית, אבל קשה לפירסוק אוטומטי. הדגל --output-format json משנה את זה: במקום טקסט, מקבלים אובייקט JSON מובנה עם שדות מוגדרים.

מבנה הפלט

claude -p "list 3 common bugs" --output-format json

מחזיר אובייקט JSON עם שדות כמו:

{
  "result": "1. Off-by-one errors\n2. Null pointer...",
  "tokens_used": { "input": 150, "output": 200 },
  "cost": 0.0035,
  "model": "claude-sonnet-4-6",
  "duration_ms": 2340
}

פירסוק עם jq

jq הוא כלי שורת הפקודה הסטנדרטי לעיבוד JSON. אם אין לכם אותו — התקינו עכשיו (brew install jq ב-Mac, apt install jq באובונטו).

# חילוץ רק התוצאה
claude -p "list bugs" --output-format json | jq -r '.result'

# חילוץ העלות
claude -p "analyze code" --output-format json | jq '.cost'

# חילוץ מספר הטוקנים
claude -p "review PR" --output-format json | jq '.tokens_used.output'

פירסוק ב-Python

import subprocess, json

result = subprocess.run(
    ["claude", "-p", "list all functions in main.py", "--output-format", "json"],
    capture_output=True, text=True, timeout=120
)

data = json.loads(result.stdout)
print(f"Result: {data['result']}")
print(f"Cost: ${data['cost']:.4f}")
print(f"Tokens: {data['tokens_used']}")

פירסוק ב-TypeScript / Node.js

import { execFile } from 'child_process';
import { promisify } from 'util';

const exec = promisify(execFile);

const { stdout } = await exec('claude', [
  '-p', 'summarize this project',
  '--output-format', 'json'
], { timeout: 120000 });

const data = JSON.parse(stdout);
console.log(`Result: ${data.result}`);
console.log(`Cost: $${data.cost.toFixed(4)}`);

Stream-JSON — פלט בזמן אמת

בנוסף ל-json רגיל, יש גם stream-json שמחזיר chunks בזמן אמת. זה שימושי כשבונים UI שמראה progress, או כשצריכים לעבד פלט ארוך בלי לחכות שהכל יסתיים:

# Stream JSON — כל chunk הוא אירוע נפרד
claude -p "long analysis task" --output-format stream-json | \
    jq -j '.event.delta.text? // empty'

ב-stream-json, כל שורה היא אירוע JSON נפרד עם type (text, tool_use, tool_result, done). אפשר לפלטר אותם ולהגיב בזמן אמת — למשל, להציג "מנתח קובץ X..." כל פעם שClaude משתמש בכלי Read. ב-Python אפשר לעבד stream-json כך:

import subprocess, json

process = subprocess.Popen(
    ["claude", "-p", "analyze codebase", "--output-format", "stream-json"],
    stdout=subprocess.PIPE, text=True
)
for line in process.stdout:
    event = json.loads(line)
    if event.get("type") == "tool_use":
        print(f"Claude is using: {event['tool']}")
    elif event.get("type") == "text":
        print(event.get("text", ""), end="")
process.wait()

stream-json שימושי במיוחד כשבונים dashboard או CLI tool שמראה progress — המשתמש רואה שClaude עובד במקום לחכות בחושך לתשובה.

הגבלת מבנה הפלט עם --json-schema

רוצים שהתוצאה תהיה בפורמט מדויק? השתמשו ב---json-schema כדי לכפות סכמה ספציפית:

claude -p "list 3 bugs" --output-format json \
  --json-schema '{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string"}}}}'

הפלט יהיה בדיוק לפי הסכמה שהגדרתם — מושלם לעיבוד אוטומטי ב-downstream pipeline.

שלושה פורמטים — מתי להשתמש בכל אחד

כלל אצבע: אם הפלט מגיע לסקריפט או לקוד — תמיד השתמשו ב-json. פירסוק טקסט חופשי עם regex הוא שברירי ויישבר ברגע שClaude ישנה את הניסוח.

Shell Scripting עם Claude Code

עכשיו שאתם יודעים להריץ Claude ב-headless ולפרסק את הפלט, הגיע הזמן לשלב את זה בסקריפטים אמיתיים. Claude Code משתלב בסקריפטי bash/zsh כמו כל כלי CLI אחר — הוא מקבל קלט, נותן פלט, ואפשר לשרשר אותו עם כלים אחרים.

# צרו את הקובץ
cat > ~/.claude-env.sh << 'EOF'
#!/bin/bash
export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"
# הוסיפו עוד משתנים לפי הצורך (ראו סעיף Environment Variables בהמשך)
EOF

# הגנו על הקובץ
chmod 600 ~/.claude-env.sh

# ודאו שלא יכנס ל-git (חשוב!)
echo ".claude-env.sh" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

# בדקו שעובד
source ~/.claude-env.sh && echo "API key loaded: ${ANTHROPIC_API_KEY:0:10}..."

שלד הסקריפט (Script Skeleton)

כל סקריפט שמשלב Claude Code צריך את אותו שלד בסיסי. הנה התבנית שתעבוד ל-90% מהמקרים — העתיקו אותה, התאימו את ה-prompt, והוסיפו לוגיקה ספציפית:

#!/bin/bash
set -euo pipefail  # strict mode: עצור בכל שגיאה (ראו הסבר למעלה)

# 1. טען משתני סביבה (צריך ליצור קודם — ראו ההכנה למעלה)
source ~/.claude-env.sh

# 2. הגדר timeout ופרמטרים
TIMEOUT=120
MODEL="claude-sonnet-4-6"

# 3. הרץ Claude עם timeout
RESULT=$(timeout $TIMEOUT claude -p "$PROMPT" -m $MODEL --bare --output-format json 2>/dev/null)

# 4. בדוק exit code
if [ $? -ne 0 ]; then
    echo "ERROR: Claude call failed" >&2
    exit 1
fi

# 5. פרסק את התוצאה
echo "$RESULT" | jq -r '.result'

# 6. רשום ללוג
echo "$(date): Claude call completed, cost: $(echo $RESULT | jq '.cost')" >> /var/log/claude-runs.log

ארבעת דפוסי הסקריפטים

רוב הסקריפטים שתכתבו נופלים לאחד מארבעה דפוסים:

דפוס 1: The Validator (המאמת)

# בדיקת PR לבעיות אבטחה — התראה רק אם יש CRITICAL
claude -p "review this PR diff for security issues" --bare | grep -q "CRITICAL" \
    && echo "SECURITY ALERT: Critical issue found!" \
    || echo "No critical issues"

דפוס 2: The Generator (המחולל)

# יצירת migration SQL מתיאור
claude -p "generate a migration SQL for adding status column to users table" --bare \
    > migrations/002_add_status.sql

דפוס 3: The Analyzer (המנתח)

# ניתוח שינויים ויצירת release notes
git diff HEAD~5 | claude -p "summarize these changes for release notes" --bare \
    > RELEASE_NOTES.md

דפוס 4: The Decision Maker (מקבל ההחלטות)

# Claude מחליט YES/NO — הסקריפט פועל בהתאם
DECISION=$(claude -p "Should this deploy proceed? Analyze: $(cat deploy-check.txt). Answer only YES or NO" --bare)
if [ "$DECISION" = "YES" ]; then
    ./deploy.sh
else
    echo "Deploy blocked by Claude analysis"
fi

Error Handling מקצועי

הדפוסים למעלה הם הבסיס, אבל בסביבת ייצור צריך error handling מקצועי. הנה הדפוס המלא:

#!/bin/bash
set -euo pipefail

# פונקציית עזר ל-error handling
handle_error() {
    local exit_code=$1
    local line_number=$2
    echo "$(date): ERROR at line $line_number, exit code $exit_code" >> /var/log/claude-errors.log
    # שלחו התראה — email, Slack webhook, או PagerDuty
    curl -s -X POST "$SLACK_WEBHOOK" \
        -d "{\"text\": \"Claude script failed at line $line_number\"}" 2>/dev/null
    exit $exit_code
}
trap 'handle_error $? $LINENO' ERR

# פונקציה שמריצה Claude עם retries
run_claude() {
    local prompt="$1"
    local max_retries=3
    local retry=0

    while [ $retry -lt $max_retries ]; do
        RESULT=$(timeout 120 claude -p "$prompt" --bare --output-format json 2>/dev/null) && break
        retry=$((retry + 1))
        echo "$(date): Retry $retry/$max_retries" >> /var/log/claude-runs.log
        sleep $((retry * 5))  # exponential backoff: 5s, 10s, 15s
    done

    if [ $retry -eq $max_retries ]; then
        echo "$(date): FAILED after $max_retries retries" >> /var/log/claude-runs.log
        return 1
    fi

    echo "$RESULT"
}

# שימוש
ANALYSIS=$(run_claude "analyze error.log and report critical issues")
echo "$ANALYSIS" | jq -r '.result'

שימו לב ל-exponential backoff — כל retry מחכה יותר זמן מהקודם. זה חשוב כי rate limiting הוא הסיבה הנפוצה ביותר לכשלון, ושליחת retry מיידי רק מחמירה את הבעיה.

דפוסי שילוב מתקדמים

כשמשלבים Claude Code בסקריפטים גדולים, שימו לב לכמה דפוסים מתקדמים:

# דפוס Chain — פלט של קריאה אחת הופך לקלט של הבאה
SUMMARY=$(claude -p "summarize this README.md" --bare)
TRANSLATION=$(echo "$SUMMARY" | claude -p "translate this to Hebrew" --bare)
echo "$TRANSLATION" > README.he.md

# דפוס Map-Reduce — עבדו על חלקים במקביל, אחדו בסוף
for module in auth payments notifications; do
    claude -p "review the $module module" --bare > /tmp/review-$module.txt &
done
wait
cat /tmp/review-*.txt | claude -p "synthesize these reviews into a unified report" --bare > final-review.txt

# דפוס Guard — בדיקת תנאי מקדים לפני פעולה
SAFE=$(claude -p "Is it safe to run database migration right now? Check: $(pg_stat_activity). Answer YES or NO only" --bare)
if [ "$SAFE" != "YES" ]; then
    echo "Migration blocked: database is busy"
    exit 1
fi
./run-migration.sh

הזרמת נתונים ל-Claude

אפשר להזרים נתונים לתוך Claude באמצעות pipe. זו אחת הדרכים החזקות ביותר לשלב Claude ב-pipeline — במקום שClaude יקרא קבצים בעצמו, אתם שולחים לו את הנתונים ישירות:

# ניתוח לוג שגיאות
cat error.log | claude -p "analyze these errors and suggest fixes" --bare

# ניתוח diff — Claude מקבל את השינויים ישירות
git diff | claude -p "review this code change" --bare

# ניתוח תוצאות בדיקות
npm test 2>&1 | claude -p "explain these test failures" --bare

# שרשור כלים — grep מסנן, Claude מנתח
grep "ERROR" application.log | tail -50 | claude -p "categorize these errors by root cause" --bare

# בדיקת חולשות אבטחה — npm audit מייצר דוח, Claude מפרש
npm audit --json | claude -p "prioritize these vulnerabilities by risk" --bare

טיפ חשוב: כשמזרימים נתונים דרך pipe, הנתונים הופכים לחלק מה-prompt. אם הקובץ גדול (10,000+ שורות), זה צורך הרבה טוקנים. סננו עם head, tail, או grep לפני ששולחים ל-Claude.

שילוב כלים — Claude כחלק מ-pipeline

הכוח האמיתי של headless mode הוא שClaude הופך לכלי CLI רגיל. בדיוק כמו שמשתמשים ב-grep, sed, awk — אפשר לשלב את claude -p בתוך pipeline:

# Pipeline מלא: מצא שינויים → סנן Python → Claude מנתח → שמור דוח
git diff --name-only HEAD~3 | \
    grep "\.py$" | \
    xargs -I {} sh -c 'echo "=== {} ===" && cat {}' | \
    claude -p "review these Python changes for bugs and suggest fixes" --bare \
    > code-review-report.txt

בדוגמה הזו, ארבעה כלים עובדים ביחד: git diff מוצא שינויים, grep מסנן רק Python, xargs+cat מדפיס את התוכן, ו-Claude מנתח הכל. זה pipeline automation אמיתי.

עוד דפוס חזק: Claude כמתווך בין שני כלים. למשל, npm audit מייצר רשימת חולשות אבטחה בפורמט טכני מסובך. Claude הופך את זה לדוח מסודר עם סדר עדיפויות:

# npm audit מחזיר JSON טכני → Claude ממיר לדוח מובן
npm audit --json 2>/dev/null | \
    claude -p "Analyze this npm audit report. List the top 5 vulnerabilities by severity. For each: package name, severity, recommendation. Format as Markdown." --bare \
    > security-report.md

או דפוס compare-and-decide: שני outputs שונים, Claude מחליט מה עדיף:

# השוואה בין שני branches — Claude ממליץ מה לעשות merge
DIFF_A=$(git diff main...feature-a -- src/)
DIFF_B=$(git diff main...feature-b -- src/)

echo "Branch A changes: $DIFF_A" > /tmp/compare.txt
echo "Branch B changes: $DIFF_B" >> /tmp/compare.txt

RECOMMENDATION=$(cat /tmp/compare.txt | \
    claude -p "Compare these two sets of changes. Which should merge first? Why? Any conflicts?" --bare)

echo "$RECOMMENDATION"

Batch Processing — עיבוד קבצים במקביל

אחד השימושים החזקים ביותר של headless mode הוא עיבוד אצווה — הרצת אותה פעולה על עשרות או מאות קבצים. במקום לפתוח כל קובץ ידנית ב-Claude ולבקש review, אפשר לכתוב לולאה שעוברת על כל הקבצים ומעבדת אותם אוטומטית.

לולאה בסיסית

# עיבוד כל קבצי TypeScript בתיקייה
for f in src/*.ts; do
    echo "Processing: $f"
    claude -p "review $f for type safety issues" --bare >> review-report.txt
    echo "---" >> review-report.txt
done

עיבוד מקבילי עם xargs

# הרצה מקבילית — 4 תהליכים במקביל
find . -name "*.py" | xargs -P 4 -I {} \
    claude -p "add docstrings to all functions in {}" --bare

זהירות: -P 4 אומר 4 תהליכים במקביל. אל תשימו 100 — ה-API יחסום אתכם עם rate limiting. ההמלצה היא להתחיל עם 2-4 תהליכים מקביליים, לבדוק שאין שגיאות 429, ולהעלות בהדרגה רק אם ה-API מאפשר. בתוכניות Enterprise יש לפעמים rate limits גבוהים יותר, אבל תמיד כדאי להתחיל צנוע.

הפקודה /batch

Claude Code מציע גם פקודה מובנית — /batch — שעובדת ברמה גבוהה יותר:

• סורקת את ה-codebase ומבינה את המבנה
• מחלקת את העבודה ל-עד 30 יחידות עצמאיות
• כל יחידה רצה ב-git worktree מבודד — כך שאין התנגשויות
• כל יחידה פותחת PR נפרד — קל לעשות review ו-merge

הפעלה: פתחו Claude Code במצב אינטראקטיבי והקלידו:

# בתוך Claude Code interactive session:
/batch add comprehensive JSDoc comments to all exported functions

# Claude יסרוק את הפרויקט, יחלק את העבודה, ויפתח PR נפרד לכל חלק.
# תראו פלט כזה:
# Planning batch operation...
# Found 12 files to process
# Creating 4 worktrees...
# [1/4] Processing src/auth/*.ts → PR #42
# [2/4] Processing src/api/*.ts → PR #43
# ...

ההבדל: /batch מתאים לשינויים מתואמים שצריכים עקביות (למשל, שינוי API signature בכל הקבצים שמשתמשים בו). לולאות ידניות מתאימות לפעולות בלתי תלויות (למשל, review לכל קובץ בנפרד). אם אתם לא בטוחים — השאלה היא: "אם משימה אחת נכשלת, זה משפיע על האחרות?" אם כן — /batch. אם לא — לולאה ידנית.

חישוב עלויות לפני batch

לפני שמריצים batch על 200 קבצים, חשבו על העלות. הנה נוסחה פשוטה:

# עלות משוערת
מספר_קבצים × טוקנים_ממוצעים_לקובץ / 1,000,000 × מחיר_למיליון_טוקנים

# דוגמה: 200 קבצים, 2000 טוקנים בממוצע, Sonnet ($3/M input)
200 × 2000 / 1,000,000 × 3 = $1.20

# אותה עבודה עם Opus ($15/M input)
200 × 2000 / 1,000,000 × 15 = $6.00

ההפרש פי 5 מסביר למה batch processing צריך להשתמש במודל הזול ביותר שנותן תוצאות מספיק טובות. Sonnet מצטיין במשימות שגרתיות כמו docstrings, type hints, ו-code review. שמרו את Opus למשימות שדורשות שיקול דעת עמוק.

דפוס ה-Dry Run

לפני שמעבדים 200 קבצים, תמיד עשו dry run על 3 קבצים ראשונים:

# Dry run — רק 3 קבצים ראשונים
for f in $(ls src/*.ts | head -3); do
    echo "=== DRY RUN: $f ==="
    claude -p "review $f" --bare
done

# אם התוצאות טובות — רוצו על הכל
echo "Dry run complete. Run full batch? (y/n)"
read CONFIRM
if [ "$CONFIRM" = "y" ]; then
    for f in src/*.ts; do
        claude -p "review $f" --bare >> full-review.txt
        sleep 2  # rate limiting
    done
fi

מעקב אחרי עלויות

TOTAL_COST=0
for f in src/*.ts; do
    RESULT=$(claude -p "review $f" --bare --output-format json)
    COST=$(echo $RESULT | jq '.cost')
    TOTAL_COST=$(echo "$TOTAL_COST + $COST" | bc)
    echo "$f: $$COST" >> cost-log.txt
done
echo "Total batch cost: $$TOTAL_COST"

Environment Variables והגדרות

כל הרצה של Claude Code ב-headless mode תלויה במשתני סביבה. אם ה-API key לא מוגדר — שום דבר לא ירוץ. אבל יש הרבה יותר משתנים מעבר ל-API key, וסדר הקדימויות שלהם חשוב.

המשתנים החיוניים

היררכיית הגדרות

Claude Code קורא הגדרות ממספר מקורות, ויש להן סדר קדימויות ברור:

משתני סביבה (הכי גבוה)
    ↓
settings.json ברמת פרויקט (.claude/settings.json)
    ↓
settings.json גלובלי (~/.claude/settings.json)
    ↓
ברירות מחדל (הכי נמוך)

זה אומר שאם הגדרתם CLAUDE_MODEL כמשתנה סביבה, זה ידרוס כל הגדרה ב-settings.json.

הדפוס של .claude-env.sh

במקום להגדיר משתנים בכל סקריפט מחדש, צרו קובץ אחד:

# ~/.claude-env.sh — DON'T commit to git!
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export CLAUDE_MODEL="claude-sonnet-4-6"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS="4096"

ואז בכל סקריפט:

#!/bin/bash
source ~/.claude-env.sh
# ... rest of script

חשוב: הוסיפו את .claude-env.sh ל-.gitignore כדי שהמפתח שלכם לא יגיע ל-git.

apiKeyHelper — עבור סביבות Enterprise

בארגונים גדולים, API keys מתחלפים בקביעות (key rotation). במקום לעדכן כל סקריפט ידנית, אפשר להשתמש ב-apiKeyHelper — סקריפט שמחזיר key טרי בכל קריאה:

# apiKeyHelper הוא סקריפט שמחזיר API key
# Claude Code מריץ אותו לפני כל קריאת API

# דוגמה: סקריפט שקורא key מ-AWS Secrets Manager
#!/bin/bash
aws secretsmanager get-secret-value \
    --secret-id "claude-api-key" \
    --query 'SecretString' \
    --output text

# ב-settings.json:
{
  "apiKeyHelper": "/path/to/get-api-key.sh"
}

זה רלוונטי בעיקר לסביבות שבהן אסור לשמור API keys כטקסט — למשל ארגונים עם תקני אבטחה מחמירים (SOC2, ISO 27001). אם אתם מפתחים יחידים, .claude-env.sh עם .gitignore מספיק.

הגדרות ב-settings.json

מעבר למשתני סביבה, אפשר להגדיר הגדרות קבועות ב-settings.json:

# הגדרות ברמת פרויקט — .claude/settings.json
{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Read", "Grep", "Glob"],
    "deny": ["Write", "Edit", "Bash"]
  },
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "4096"
  }
}

# הגדרות גלובליות — ~/.claude/settings.json
{
  "model": "claude-sonnet-4-6",
  "theme": "dark"
}

ההגדרות ברמת פרויקט חשובות במיוחד ל-headless: הן מגדירות אילו כלים Claude מורשה להשתמש בהם כשאין בן אדם שמאשר. אם אתם מריצים Claude על cron job שרק קורא נתונים — הגבילו ל-Read ו-Grep בלבד. זה מונע מצב שבו Claude משנה קבצים בטעות.

Cron Jobs ותהליכים מתוזמנים

עד עכשיו הרצתם Claude ידנית — גם אם זה מסקריפט, עדיין הייתם צריכים להפעיל את הסקריפט. השלב הבא: תהליכים שרצים לבד, על לוח זמנים, בלי שתיגעו בהם. זה מה שהופך אוטומציה מ-"נוחות" ל-"תשתית": ברגע שסקריפט רץ על cron, הוא הופך לחלק מהתשתית של הארגון שלכם — כמו מערכת ניטור, כמו backup, כמו CI. והחלק הכי יפה? Claude Code עובד מעולה בתרחישים כאלה כי הוא מבין הקשר ויכול לזהות דפוסים שכלים מסורתיים מפספסים.

cron — הקלאסיקה

Cron הוא מנגנון התזמון הוותיק ביותר בלינוקס. הוא פשוט, אמין, ועובד על כל מערכת Unix/Linux. כל שורה ב-crontab מגדירה שני דברים: מתי לרוץ ומה להריץ. אם אתם עובדים עם שרתים — cron הוא כנראה מה שתשתמשו בו. אם אתם בענן — יש אלטרנטיבות מודרניות (נגיע אליהן בהמשך).

# פתחו את ה-crontab לעריכה
crontab -e

# הוסיפו שורה — דוגמה: כל יום ב-8 בבוקר
0 8 * * * /usr/local/bin/claude -p "generate daily report for project X" --bare > /var/log/claude-daily.log 2>&1

# כל שעה בימי עבודה (ראשון-חמישי)
0 * * * 0-4 /home/user/scripts/claude-monitor.sh >> /var/log/claude-monitor.log 2>&1

תחביר cron:

דקה  שעה  יום-בחודש  חודש  יום-בשבוע
  0    8       *         *       *        = כל יום ב-8:00
  */5  *       *         *       *        = כל 5 דקות
  0    0       1         *       *        = ה-1 לחודש בחצות

systemd timers — האלטרנטיבה המודרנית

systemd timers מציעים יתרונות על cron: logging מובנה (אפשר לראות הכל ב-journalctl), מנגנון restart אוטומטי אם הסקריפט קורס, ניהול תלויות (למשל "אל תריץ אם אין רשת"), ואפשרות לראות סטטוס בזמן אמת. ברוב ההתקנות המודרניות של Linux, systemd timers הם הבחירה המועדפת.

# /etc/systemd/system/claude-audit.service
[Unit]
Description=Claude Code Daily Audit
After=network.target

[Service]
Type=oneshot
ExecStart=/home/user/scripts/claude-audit.sh
User=user
Environment=ANTHROPIC_API_KEY=sk-ant-...

# /etc/systemd/system/claude-audit.timer
[Unit]
Description=Run Claude audit daily

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

# הפעלה
sudo systemctl enable --now claude-audit.timer

# בדיקת סטטוס
systemctl status claude-audit.timer
systemctl list-timers

Desktop Scheduled Tasks — תזמון ב-macOS ו-Windows

מגרסת 2.1.81, Claude Code מציע גם Desktop Scheduled Tasks — תזמון שרץ מהאפליקציה הדסקטופית ושורד restarts. זה זמין ב-macOS ו-Windows בלבד (לא Linux). היתרון: לא צריך להגדיר cron ידנית, הממשק גרפי, והמשימות רצות כל עוד האפליקציה פתוחה.

חשוב: Desktop Scheduled Tasks הם אופציה נוחה לפיתוח מקומי, אבל ל-production תמיד העדיפו cron או systemd — הם אמינים יותר, עובדים ב-headless (שרתים בלי GUI), ומשתלבים במערכות ניטור.

Cloud Schedulers

אם ה-infrastructure שלכם בענן, יש אלטרנטיבות מודרניות ל-cron:

# GitHub Actions scheduled workflow — cron בלי שרת
name: Daily Claude Audit
on:
  schedule:
    - cron: '0 8 * * *'  # כל יום ב-8 בבוקר UTC
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          npm install -g @anthropic-ai/claude-code
          claude -p "audit codebase for security issues" --bare > audit-report.txt
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

בפרק הבא נעמיק ב-GitHub Actions, אבל שימו לב — גם תזמון של Claude יכול לרוץ ב-GitHub Actions בלי שום שרת משלכם.

הפקודה /loop — תזמון בתוך session

אם אתם צריכים תזמון בתוך session פעיל (לא headless), יש את /loop:

/loop 5m check deploy status

זה ירוץ כל 5 דקות כל עוד ה-session פתוח. שימושי לניטור deploy בזמן אמת, או לבדיקת CI status כשמחכים ל-build. אבל /loop לא מחליף cron — כי זה מת ברגע שסוגרים את ה-session. חשבו על זה כ-"timer זמני" לשימוש חד-פעמי, לא כ-"שירות מתוזמן".

Idempotency — למה זה חשוב לתזמון

Idempotency (אידמפוטנטיות) אומר שפעולה מייצרת את אותה תוצאה גם אם מריצים אותה פעמיים. זה קריטי ל-cron jobs כי:

• Cron יכול להריץ פעמיים בגלל שעון קיץ או עיכוב
• systemd יכול לעשות retry אחרי כשלון
• הפלט של Claude הוא לא דטרמיניסטי — אותו prompt יכול לתת תשובות שונות בכל הרצה

פתרון: הוסיפו שכבת validation שבודקת את הפלט לפני שמשתמשים בו. למשל:

#!/bin/bash
# cron job עם validation layer
REPORT=$(claude -p "generate daily security report" --bare --output-format json)

# בדיקות validation
WORD_COUNT=$(echo "$REPORT" | jq -r '.result' | wc -w)
if [ "$WORD_COUNT" -lt 50 ]; then
    echo "$(date): Report too short ($WORD_COUNT words), skipping" >> /var/log/claude-cron.log
    exit 1
fi

# בדיקה שאין שגיאה ב-output
if echo "$REPORT" | jq -r '.result' | grep -qi "error\|unable\|cannot"; then
    echo "$(date): Report contains error indicators, manual review needed" >> /var/log/claude-cron.log
    exit 1
fi

# הכל תקין — שמור את הדוח
echo "$REPORT" | jq -r '.result' > /var/reports/daily-$(date +%Y%m%d).txt
echo "$(date): Report generated successfully" >> /var/log/claude-cron.log

שימו לב לדפוס: קודם בדקו שהפלט הגיוני (אורך, תוכן), ורק אז השתמשו בו. זה מוסיף כמה שורות לסקריפט, אבל חוסך מצבים שבהם דוח ריק או שגוי נשלח ללקוחות.

ניטור הרצות מתוזמנות

ברגע שיש לכם כמה cron jobs שמריצים Claude, אתם צריכים ניטור. הנה גישה פשוטה:

# בכל סקריפט — כתבו שורת סטטוס סטנדרטית
echo "$(date)|$SCRIPT_NAME|$STATUS|$COST|$DURATION_MS" >> /var/log/claude-monitor.csv

# סקריפט ניטור שבועי — מסכם עלויות וכשלונות
echo "=== Weekly Claude Summary ==="
echo "Total runs: $(wc -l < /var/log/claude-monitor.csv)"
echo "Failures: $(grep "|FAILED|" /var/log/claude-monitor.csv | wc -l)"
echo "Total cost: $(awk -F'|' '{sum+=$4}END{print sum}' /var/log/claude-monitor.csv)"

Git Worktrees במצב Headless

הדגל -w (worktree) משלב את headless mode עם git worktrees — כלי מבודד שמאפשר לעבוד על כמה branches במקביל בלי לעשות checkout:

# Claude יוצר worktree חדש, עובר ל-branch, מריץ את המשימה
claude -p "implement feature X" -w feature-x --bare

מה קורה מאחורי הקלעים:

1. נוצר git worktree חדש ב-.claude/worktrees/feature-x
2. נוצר branch חדש feature-x
3. Claude רץ ב-worktree המבודד — כל השינויים שלו שם
4. השינויים נשמרים ב-branch ולא משפיעים על ה-main

עבודה מקבילית

# הרצת 3 features במקביל
for feature in "add-auth" "fix-cache" "update-docs"; do
    claude -p "implement: $feature" -w "$feature" --bare &
done
wait  # חכה לכולם

שילוב worktree עם --bare

השילוב של -w עם --bare נותן ביצועים מקסימליים ב-CI: כל worktree רץ ב-branch נפרד, בלי overhead של hooks:

# CI job שמריץ 3 features במקביל עם bare
for feature in "add-auth" "fix-cache" "update-docs"; do
    claude -p "implement: $feature. Write tests. Commit changes." \
        -w "$feature" --bare &
done
wait  # חכה לכל ה-backgrounds

# אחרי שסיימו — בדוק את ה-branches
for feature in "add-auth" "fix-cache" "update-docs"; do
    echo "=== $feature ==="
    git log "$feature" --oneline -3
done

Sparse Paths — לפרויקטים גדולים

ב-monorepo גדול (למשל, פרויקט עם 50 packages), לא צריך לטעון את כל הקוד לכל worktree. ההגדרה worktree.sparsePaths מגבילה אילו נתיבים נטענים — מה שמאיץ את היצירה ומקטין צריכת דיסק:

# ב-settings.json
{
  "worktree": {
    "sparsePaths": ["packages/auth/", "packages/shared/"]
  }
}

כש-sparsePaths מוגדר, ה-worktree ייצור רק עם הנתיבים האלה — Claude לא יראה את שאר הקוד, וזה גם חוסך context tokens.

ניקוי

Worktrees שנשארים אחרי שהעבודה הסתיימה תופסים מקום בדיסק ומבלבלים. נקו אותם:

git worktree prune  # מנקה worktrees שנמחקו מהדיסק
git worktree list   # רואים מה עדיין קיים

# ניקוי אגרסיבי — מוחק את כל ה-worktrees של Claude
rm -rf .claude/worktrees/*
git worktree prune

#!/bin/bash
# cleanup-worktrees.sh — מנקה worktrees שלא השתנו ביום האחרון
find .claude/worktrees -maxdepth 1 -type d -mtime +1 -exec rm -rf {} \; 2>/dev/null
git worktree prune
echo "$(date): Cleaned stale worktrees" >> /tmp/worktree-cleanup.log

Debugging של הרצות Headless

כשהרצה headless נכשלת או מחזירה תוצאה לא צפויה, אין ממשק אינטראקטיבי שמסביר מה קרה. צריך כלים אחרים.

הדגל --verbose

# הרצה עם logging מפורט
claude -p "analyze project" --bare --verbose 2>debug.log

# הפלט הרגיל הולך ל-stdout, ה-debug ל-stderr (שנשמר לקובץ)

--verbose מוסיף מידע על: אילו כלים Claude השתמש, כמה זמן כל שלב לקח, מה ההחלטות שהוא קיבל, ואם היו שגיאות פנימיות.

סולם ה-Debug (Debug Ladder)

כשמשהו לא עובד, תעברו על הסולם הזה מלמעלה למטה:

ה-Skill /debug

אם אין לכם כוח לעבור על הסולם ידנית, Claude Code מציע skill מובנה: /debug. מריצים אותו ב-mode אינטראקטיבי אחרי הרצת headless שנכשלה, והוא קורא את ה-debug logs ומסביר מה קרה:

# שלב 1: הריצו headless עם verbose log
claude -p "complex task" --bare --verbose 2>debug-$(date +%Y%m%d).log

# שלב 2: אם נכשל — פתחו session אינטראקטיבי
claude
> /debug debug-20260331.log

/debug מנתח את הלוג, מזהה היכן Claude "תקע" או נכשל, ומסביר בשפה ברורה מה לתקן. זה חוסך זמן רב לעומת קריאה ידנית של לוגים.

כשלים נפוצים וטיפול

דפוס ה-Prompt Test Suite

לפרויקטים רציניים, שמרו קובץ עם prompt-output pairs צפויים ובדקו headless runs מולם:

# prompt-tests.sh — בדיקת regression ל-prompts
TESTS_PASSED=0
TESTS_FAILED=0

# Test 1: Claude יחזיר JSON תקין
RESULT=$(claude -p "return JSON: {\"status\": \"ok\"}" --bare)
if echo "$RESULT" | jq . > /dev/null 2>&1; then
    ((TESTS_PASSED++))
    echo "PASS: JSON output valid"
else
    ((TESTS_FAILED++))
    echo "FAIL: JSON output invalid"
fi

# Test 2: Claude יזהה שפת תכנות
RESULT=$(claude -p "what language is this: print('hello')" --bare)
if echo "$RESULT" | grep -qi "python"; then
    ((TESTS_PASSED++))
else
    ((TESTS_FAILED++))
    echo "FAIL: Language detection"
fi

echo "Results: $TESTS_PASSED passed, $TESTS_FAILED failed"

ה-test suite הזה רץ כחלק מה-CI שלכם — כל פעם שמשנים CLAUDE.md או מעדכנים גרסת Claude Code, מריצים את הבדיקות ומוודאים שהכל עדיין עובד כצפוי. חשוב: הבדיקות צריכות לבדוק מבנה ותוכן כללי, לא טקסט מדויק — כי הפלט של Claude הוא לא דטרמיניסטי ויכול להשתנות בין הרצות. בדקו "האם הפלט מכיל JSON תקין?" במקום "האם הפלט שווה בדיוק למחרוזת X?".

שגרת עבודה — Headless שוטף

אם אתם עושים רק דבר אחד מהפרק הזה

בדוק את עצמך

סיכום הפרק

צ׳קליסט סיום