Headless Claude Code — Tool Restriction and Configuration

Core 6 min +25 XP

💡

THE ANALOGY

A remote-controlled drone vs a piloted plane. The drone follows programmed constraints exactly — you can't course-correct in real time. Precise upfront configuration is critical: restrict what it can do to what it should do.

⚠️ EXAM TRAP — The Wrong Answer People Choose

Giving headless Claude Code all tools for flexibility. In non-interactive mode, you cannot intervene if Claude calls file_delete when it shouldn't. Restrict to minimum necessary.

KEY POINTS

1 --allowedTools: explicit whitelist of permitted tools for this invocation only.

2 --disallowedTools: explicit blacklist — useful when you want most tools except specific dangerous ones.

3 Timeouts are critical for all headless runs — unconstrained runs block pipelines.

4 Idempotent operations: headless jobs should be safe to re-run without double processing.

5 --env for configuration — pass settings without hardcoding credentials in commands.

Tool Selection by Task Type

# Read-only review — no write tools
claude -p \
  --allowedTools "file_read,grep,glob" \
  --timeout 120 \
  "Analyze code quality..."

# Documentation generation — write but not delete or bash
claude -p \
  --allowedTools "file_read,file_write,glob" \
  --disallowedTools "bash,file_delete" \
  --timeout 180 \
  "Generate API documentation..."

# Test runner — needs bash for test execution, not file write
claude -p \
  --allowedTools "file_read,bash,grep" \
  --timeout 300 \
  "Run tests and report coverage gaps..."

# Environment-specific configuration
claude -p \
  --allowedTools "file_read,bash" \
  --env "DATABASE_URL=postgresql://localhost/test_db" \
  --env "ENVIRONMENT=ci" \
  --timeout 240 \
  "Run integration tests..."

Idempotency — Check Before Doing

# Non-idempotent: running twice creates duplicate entries
claude -p "Add changelog entry for version $VERSION to CHANGELOG.md"

# Idempotent: safe to re-run
claude -p \
  --allowedTools "file_read,file_write" \
  "Check CHANGELOG.md for a version $VERSION entry.
  If found: return {action: 'skip', reason: 'already exists'}
  If not found: add the entry and return {action: 'added'}"

Tool Access Reference

Task	Allowed	Blocked
Code review	file_read, grep, glob	file_write, bash, file_delete
Doc generation	file_read, file_write	bash, file_delete
Test analysis	file_read, bash	file_write, file_delete
Security scan	file_read, grep, glob	file_write, file_delete

Timeout Handling

# Bash timeout with exit code handling
timeout 300 claude -p "..." > output.txt
EXIT=$?
if [ $EXIT -eq 124 ]; then
  echo "Timed out after 300 seconds"; exit 1
elif [ $EXIT -ne 0 ]; then
  echo "Claude Code failed: exit $EXIT"; exit 1
fi

Key Takeaways

Minimum tools — cannot intervene in non-interactive mode
Always set timeout — prevent indefinite pipeline hangs
Idempotent design — check before doing, safe to re-run
—env for config — not hardcoded in commands
—disallowedTools when you want most tools except specific dangerous ones