Skip to content

Headless Pattern (Claude Code)

The Headless Pattern is a fully autonomous execution mode within Claude Code that requires no human intervention during the task lifecycle^[001-TODO__Claude_Code_5种Agent模式_-从顺序流到自主工作流.md]. It represents the highest level of autonomy in the Claude Code Agent Patterns spectrum, suitable for tasks that can be clearly defined, scheduled, and verified without active supervision^[001-TODO__Claude_Code_5种Agent模式-_从顺序流到自主工作流.md].

Execution Mechanism

This pattern operates using the -p (prompt) flag, which allows commands to be passed directly to Claude Code without launching an interactive terminal session^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].

Basic Usage

claude -p "review yesterday's git commits and write a summary to morning-report.md"

Integration with Schedulers

Because the pattern requires no user interaction, it is commonly integrated with system schedulers like cron to trigger tasks automatically^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].

# crontab 示例：每天早上 7 点自动生成日报
0 7 * * * claude -p "review yesterday's work and write summary to morning-report.md"

Common Applications

The Headless Pattern is typically applied to routine, repetitive, or batch-processing tasks^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md]:

  • Automated Reporting: Analyzing git commits or work logs to generate daily summaries^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].
  • Content Production: Extracting video subtitles via scripts and passing them to Claude Code to generate social media posts^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].
  • Batch Processing: Executing fully automated workflows by combining the headless command with [[Skills]] (custom tools)^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].

Guardrails and Safety

Since human oversight is absent, applying strict guardrails is critical to prevent unintended consequences^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].

  • Verification Principle: Only use this pattern for tasks where the output is easily verifiable^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].
  • Reversible Actions: Avoid tasks that involve destructive or hard-to-revert operations^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].
  • Tool Restrictions: Permissions can be restricted to read-only capabilities to prevent accidental modifications^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].
# 限制工具权限（只读）
claude -p "task" --allowed-tools "Read,Search"

Advanced Iterations

To handle complex refinement without human intervention, a "Ralph Loop" strategy can be employed^[001-TODO__Claude_Code_5种Agent模式_-从顺序流到自主工作流.md]. This involves feeding the result of the previous execution back into the prompt, allowing Claude to iterate on its own output until a satisfactory state is achieved^[001-TODO__Claude_Code_5种Agent模式-_从顺序流到自主工作流.md].

Position in Agent Patterns

The Headless Pattern sits at the top of the complexity and autonomy spectrum^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].

  1. Sequential Flow: Single terminal, sequential execution.
  2. Operator: Multi-terminal, manual coordination.
  3. Split & Merge: Single session, fan-out/fan-in execution.
  4. Agent Teams: Multi-agent collaboration with shared state.
  5. Headless: No human-in-the-loop, scheduled/script-driven^[001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md].
  • [[Agent Teams (Claude Code)]]
  • [[Split & Merge Pattern (Claude Code)]]
  • [[Operator Pattern (Claude Code)]]
  • [[Skills (Claude Code)]]

Sources

  • 001-TODO__Claude_Code_5种Agent模式_-_从顺序流到自主工作流.md