1# Headless mode1# Run Claude Code programmatically
2 2
3> Run Claude Code programmatically without interactive UI3> Use the Agent SDK to run Claude Code programmatically from the CLI, Python, or TypeScript.
4 4
5## Overview5The [Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) gives you the same tools, agent loop, and context management that power Claude Code. It's available as a CLI for scripts and CI/CD, or as [Python](https://platform.claude.com/docs/en/agent-sdk/python) and [TypeScript](https://platform.claude.com/docs/en/agent-sdk/typescript) packages for full programmatic control.
6 6
7The headless mode allows you to run Claude Code programmatically from command line scripts and automation tools without any interactive UI.7<Note>
8 The CLI was previously called "headless mode." The `-p` flag and all CLI options work the same way.
9</Note>
8 10
9## Basic usage11To run Claude Code programmatically from the CLI, pass `-p` with your prompt and any [CLI options](/en/cli-reference):
10
11The primary command-line interface to Claude Code is the `claude` command. Use the `--print` (or `-p`) flag to run in non-interactive mode and print the final result:
12 12
13```bash theme={null}13```bash theme={null}
14claude -p "Stage my changes and write a set of commits for them" \14claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
15 --allowedTools "Bash,Read" \
16 --permission-mode acceptEdits
17```15```
18 16
19## Configuration Options17This page covers using the Agent SDK via the CLI (`claude -p`). For the Python and TypeScript SDK packages with structured outputs, tool approval callbacks, and native message objects, see the [full Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview).
20 18
21Headless mode leverages all the CLI options available in Claude Code. Here are the key ones for automation and scripting:19## Basic usage
22
23| Flag | Description | Example |
24| :------------------------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |
25| `--print`, `-p` | Run in non-interactive mode | `claude -p "query"` |
26| `--output-format` | Specify output format (`text`, `json`, `stream-json`) | `claude -p --output-format json` |
27| `--resume`, `-r` | Resume a conversation by session ID | `claude --resume abc123` |
28| `--continue`, `-c` | Continue the most recent conversation | `claude --continue` |
29| `--verbose` | Enable verbose logging | `claude --verbose` |
30| `--append-system-prompt` | Append to system prompt (only with `--print`) | `claude --append-system-prompt "Custom instruction"` |
31| `--allowedTools` | Tools that execute without prompting for permission (use `--tools` to restrict available tools) | `claude --allowedTools mcp__slack mcp__filesystem`<br /><br />`claude --allowedTools "Bash(npm install),mcp__filesystem"` |
32| `--disallowedTools` | Tools removed from the model's context (cannot be used) | `claude --disallowedTools mcp__splunk mcp__github`<br /><br />`claude --disallowedTools "Bash(git commit),mcp__github"` |
33| `--mcp-config` | Load MCP servers from a JSON file | `claude --mcp-config servers.json` |
34| `--permission-prompt-tool` | MCP tool for handling permission prompts (only with `--print`) | `claude --permission-prompt-tool mcp__auth__prompt` |
35 20
36For a complete list of CLI options and features, see the [CLI reference](/en/cli-reference) documentation.21Add the `-p` (or `--print`) flag to any `claude` command to run it non-interactively. All [CLI options](/en/cli-reference) work with `-p`, including:
37 22
38## Multi-turn conversations23* `--continue` for [continuing conversations](#continue-conversations)
24* `--allowedTools` for [auto-approving tools](#auto-approve-tools)
25* `--output-format` for [structured output](#get-structured-output)
39 26
40For multi-turn conversations, you can resume conversations or continue from the most recent session:27This example asks Claude a question about your codebase and prints the response:
41 28
42```bash theme={null}29```bash theme={null}
43# Continue the most recent conversation30claude -p "What does the auth module do?"
44claude --continue "Now refactor this for better performance"
45
46# Resume a specific conversation by session ID
47claude --resume 550e8400-e29b-41d4-a716-446655440000 "Update the tests"
48
49# Resume in non-interactive mode
50claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix all linting issues" --no-interactive
51```31```
52 32
53## Output Formats33## Examples
54 34
55### Text Output (Default)35These examples highlight common CLI patterns.
56 36
57```bash theme={null}37### Get structured output
58claude -p "Explain file src/components/Header.tsx"
59# Output: This is a React component showing...
60```
61 38
62### JSON Output39Use `--output-format` to control how responses are returned:
63 40
64Returns structured data including metadata:41* `text` (default): plain text output
42* `json`: structured JSON with result, session ID, and metadata
43* `stream-json`: newline-delimited JSON for real-time streaming
65 44
66```bash theme={null}45```bash theme={null}
67claude -p "How does the data layer work?" --output-format json46claude -p "Summarize this project" --output-format json
68```
69
70Response format:
71
72```json theme={null}
73{
74 "type": "result",
75 "subtype": "success",
76 "total_cost_usd": 0.003,
77 "is_error": false,
78 "duration_ms": 1234,
79 "duration_api_ms": 800,
80 "num_turns": 6,
81 "result": "The response text here...",
82 "session_id": "abc123"
83}
84```47```
85 48
86### Streaming JSON Output49### Auto-approve tools
87 50
88Streams each message as it is received:51Use `--allowedTools` to let Claude use certain tools without prompting. This example runs a test suite and fixes failures, allowing Claude to execute Bash commands and read/edit files without asking for permission:
89 52
90```bash theme={null}53```bash theme={null}
91claude -p "Build an application" --output-format stream-json54claude -p "Run the test suite and fix any failures" \
55 --allowedTools "Bash,Read,Edit"
92```56```
93 57
94Each conversation begins with an initial `init` system message, followed by a list of user and assistant messages, followed by a final `result` system message with stats. Each message is emitted as a separate JSON object.58### Run slash commands
95
96## Input Formats
97 59
98### Text Input (Default)60Run [slash commands](/en/slash-commands) non-interactively. This example generates a commit for staged changes using the `/commit` slash command:
99 61
100```bash theme={null}62```bash theme={null}
101# Direct argument63claude -p "/commit"
102claude -p "Explain this code"
103
104# From stdin
105echo "Explain this code" | claude -p
106```64```
107 65
108### Streaming JSON Input66### Customize the system prompt
109 67
110A stream of messages provided via `stdin` where each message represents a user turn. This allows multiple turns of a conversation without re-launching the `claude` binary and allows providing guidance to the model while it is processing a request.68Use `--append-system-prompt` to add instructions while keeping Claude Code's default behavior. This example pipes a PR diff to Claude and instructs it to review for security vulnerabilities:
111
112Each message is a JSON 'User message' object, following the same format as the output message schema. Messages are formatted using the [`jsonl`](https://jsonlines.org/) format where each line of input is a complete JSON object. Streaming JSON input requires `-p` and `--output-format stream-json`.
113 69
114```bash theme={null}70```bash theme={null}
115echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explain this code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose71gh pr diff "$1" | claude -p \
72 --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
73 --output-format json
116```74```
117 75
118## Agent Integration Examples76See [system prompt flags](/en/cli-reference#system-prompt-flags) for more options including `--system-prompt` to fully replace the default prompt.
119
120### SRE Incident Response Bot
121 77
122```bash theme={null}78### Continue conversations
123#!/bin/bash
124
125# Automated incident response agent
126investigate_incident() {
127 local incident_description="$1"
128 local severity="${2:-medium}"
129
130 claude -p "Incident: $incident_description (Severity: $severity)" \
131 --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
132 --output-format json \
133 --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
134 --mcp-config monitoring-tools.json
135}
136
137# Usage
138investigate_incident "Payment API returning 500 errors" "high"
139```
140 79
141### Automated Security Review80Use `--continue` to continue the most recent conversation, or `--resume` with a session ID to continue a specific conversation. This example runs a review, then sends follow-up prompts:
142 81
143```bash theme={null}82```bash theme={null}
144# Security audit agent for pull requests83# First request
145audit_pr() {84claude -p "Review this codebase for performance issues"
146 local pr_number="$1"85
147 86# Continue the most recent conversation
148 gh pr diff "$pr_number" | claude -p \87claude -p "Now focus on the database queries" --continue
149 --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \88claude -p "Generate a summary of all issues found" --continue
150 --output-format json \
151 --allowedTools "Read,Grep,WebSearch"
152}
153
154# Usage and save to file
155audit_pr 123 > security-report.json
156```89```
157 90
158### Multi-turn Legal Assistant91If you're running multiple conversations, capture the session ID to resume a specific one:
159 92
160```bash theme={null}93```bash theme={null}
161# Legal document review with session persistence94session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
162session_id=$(claude -p "Start legal review session" --output-format json | jq -r '.session_id')95claude -p "Continue that review" --resume "$session_id"
163
164# Review contract in multiple steps
165claude -p --resume "$session_id" "Review contract.pdf for liability clauses"
166claude -p --resume "$session_id" "Check compliance with GDPR requirements"
167claude -p --resume "$session_id" "Generate executive summary of risks"
168```96```
169 97
170## Best Practices98## Next steps
171
172* **Use JSON output format** for programmatic parsing of responses:
173
174 ```bash theme={null}
175 # Parse JSON response with jq
176 result=$(claude -p "Generate code" --output-format json)
177 code=$(echo "$result" | jq -r '.result')
178 cost=$(echo "$result" | jq -r '.cost_usd')
179 ```
180
181* **Handle errors gracefully** - check exit codes and stderr:
182
183 ```bash theme={null}
184 if ! claude -p "$prompt" 2>error.log; then
185 echo "Error occurred:" >&2
186 cat error.log >&2
187 exit 1
188 fi
189 ```
190
191* **Use session management** for maintaining context in multi-turn conversations
192
193* **Consider timeouts** for long-running operations:
194 99
195 ```bash theme={null}100<CardGroup cols={2}>
196 timeout 300 claude -p "$complex_prompt" || echo "Timed out after 5 minutes"101 <Card title="Agent SDK quickstart" icon="play" href="https://platform.claude.com/docs/en/agent-sdk/quickstart">
197 ```102 Build your first agent with Python or TypeScript
103 </Card>
198 104
199* **Respect rate limits** when making multiple requests by adding delays between calls105 <Card title="CLI reference" icon="terminal" href="/en/cli-reference">
106 Explore all CLI flags and options
107 </Card>
200 108
201## Related Resources109 <Card title="GitHub Actions" icon="github" href="/en/github-actions">
110 Use the Agent SDK in GitHub workflows
111 </Card>
202 112
203* [CLI usage and controls](/en/cli-reference) - Complete CLI documentation113 <Card title="GitLab CI/CD" icon="gitlab" href="/en/gitlab-ci-cd">
204* [Common workflows](/en/common-workflows) - Step-by-step guides for common use cases114 Use the Agent SDK in GitLab pipelines
115 </Card>
116</CardGroup>
205 117
206 118
207---119---
