Claude Reference

Complete configuration reference for the Claude Code agent provider

Overview

The Claude agent wraps the Claude Code CLI via ClaudeAgentApi. Configure it through Spring properties under agent-client.claude.*.

agent-client:
  claude:
    model: claude-sonnet-4-5
    timeout: PT5M
    yolo: true

Configuration Properties

Prefix: agent-client.claude

Property	Type	Default	Description
model	String	claude-sonnet-4-5	Claude model to use for agent tasks
timeout	Duration	5m	Timeout for agent task execution
yolo	boolean	true	Bypass all permission checks
executable-path	String	—	Path to the Claude CLI executable (auto-discovered if not set)
effort	String	—	Reasoning effort level (--effort): low, medium, high, xhigh, max. Overrides the portable effort when both are set
max-thinking-tokens	Integer	—	Maximum thinking tokens for extended thinking mode
system-prompt	String	—	System prompt to use for the agent
allowed-tools	List<String>	[]	Tools that are allowed to be used
disallowed-tools	List<String>	[]	Tools that are not allowed to be used
permission-mode	String	—	Permission mode for tool execution (overrides yolo if set)
json-schema	Map<String,Object>	—	JSON schema for structured output
max-tokens	Integer	—	Maximum tokens for the response
max-turns	Integer	—	Maximum number of agentic turns before stopping
max-budget-usd	Double	—	Maximum budget in USD before stopping
fallback-model	String	—	Fallback model if the primary model is unavailable
append-system-prompt	String	—	Additional text appended to the default system prompt

Advanced Options

These options provide full parity with the Claude Code Python SDK:

Property	Type	Default	Description
add-dirs	List<String>	[]	Additional directories to include in Claude’s context
settings	String	—	Custom settings file path
permission-prompt-tool-name	String	—	Permission prompt tool name for interactive permission handling
extra-args	Map<String,String>	—	Arbitrary extra CLI arguments (keys are flag names without --)
env	Map<String,String>	—	Custom environment variables for the CLI process
max-buffer-size	Integer	—	Maximum buffer size for JSON parsing in bytes (default 1MB)
user	String	—	Unix user to run the CLI process as (requires sudo configuration)

Permission Modes

The permission-mode property overrides yolo when set. Available modes:

Mode	Description
bypassPermissions	Skip all permission checks (equivalent to yolo=true)
default	Use Claude Code’s default permission behavior

agent-client:
  claude:
    permission-mode: bypassPermissions
    # yolo is ignored when permission-mode is set

Tool Filtering

Control which tools Claude can use:

agent-client:
  claude:
    allowed-tools:
      - Read
      - Write
      - Bash
    disallowed-tools:
      - WebSearch

allowed-tools and disallowed-tools are mutually exclusive in practice. If both are set, allowed-tools takes precedence.

Budget Controls

Limit agent execution costs and turns:

agent-client:
  claude:
    max-turns: 10           # Stop after 10 agentic turns
    max-budget-usd: 0.50    # Stop after $0.50 spent
    max-tokens: 4096        # Limit response tokens

Structured Output

Request structured JSON output using a JSON schema:

agent-client:
  claude:
    json-schema:
      type: object
      properties:
        summary:
          type: string
        files_changed:
          type: array
          items:
            type: string

Authentication

Session Auth (Recommended)

claude auth login

The Claude CLI uses its own session token. No environment variables needed.

API Key

export ANTHROPIC_API_KEY=sk-ant-...

Do not mix session auth and API key auth — this can cause authentication conflicts.