Claude Agent icon

Claude Agent

Use Claude Code SDK to execute AI-powered coding tasks with customizable tool support

Actions2

Query

AI-generated

Summary

Starts a new Claude Code agent session via the Claude Agent SDK for each input item, running the given prompt with configurable tools, model and working directory, and returns the conversation in the chosen output format.

Inputs

  • prompt (required) — Instruction sent to Claude Code. Empty or whitespace-only prompts throw an error. Supports expressions such as {{$json.prompt}}.
  • model — Sonnet (default) or Opus.
  • maxTurns — Maximum conversation turns (default 25). If it is reached, the result is flagged as incomplete (error_max_turns).
  • timeout — Seconds before the run is aborted via an AbortController (default 300).
  • projectPath — Working directory for Claude Code. If empty, the n8n process's current directory is used.
  • outputFormat — Structured (default), Messages, or Text. Controls the shape of the output JSON.
  • allowedTools — Built-in tools Claude may use. Defaults to WebFetch, TodoWrite, WebSearch, exit_plan_mode and Task.
  • disallowedTools — Built-in tools that are blocked. They take precedence over Allowed Tools.
  • additionalOptions.systemPrompt — Extra instructions passed as the system prompt.
  • additionalOptions.permissionMode — Default, Accept Edits, Bypass Permissions (default) or Plan.
  • additionalOptions.fallbackModel — Model to switch to if the primary model is overloaded (Sonnet or Opus).
  • additionalOptions.maxThinkingTokens — Cap on thinking tokens. It is only applied when greater than 0.
  • additionalOptions.debug — Enables detailed debug logging through the n8n logger.

Output shape

One output item per input item, paired to its source item. Structured: {messages, summary {userMessageCount, assistantMessageCount, toolUseCount, hasResult, toolsAvailable}, result, metrics {duration_ms, num_turns, total_cost_usd, usage}, success}. Messages: {messages, messageCount}. Text: {result, success, duration_ms, total_cost_usd}.

The source hardcodes the Claude CLI path to /usr/local/bin/claude, so that executable must exist on the n8n host. Claude runs on the host with the selected tools, and permission mode defaults to bypassPermissions. In Text mode, errors and max-turns outcomes are returned as text in result with success=false instead of throwing. In the other formats, query errors throw. With Continue on Fail enabled, errors return {error, errorType: 'timeout' or 'execution_error', errorDetails, itemIndex}. The timeout error message refers to 'Additional Options', but Timeout is a top-level field. A timeout aborts the run, but the code does not guarantee a timeout-specific result.

Examples

Example 1: Summarize a repository's README and code structure using read-only tools.

prompt: 'Summarize this project's architecture'; projectPath: /srv/app; allowedTools: Read, Glob, Grep, LS; disallowedTools: Bash, Write, Edit; outputFormat: text.

Example 2: Research a topic from the web, using prompts from upstream nodes.

prompt: {{$json.question}}; model: opus; allowedTools: WebSearch, WebFetch; timeout: 600; outputFormat: structured.

Example 3: Let Claude make code edits and review the full trace.

prompt: 'Add input validation to parse_csv.py'; projectPath: /home/user/proj; allowedTools: Read, Edit, Write; permissionMode: acceptEdits; maxTurns: 40; outputFormat: messages.

Links

Discussion