claude

NAME

claude - execute non-interactive Claude prompts via the Claude CLI

SYNOPSIS

state-name:
  tool: claude
  arguments:
    prompt: <prompt-text>
    model: <model-name>             # optional
    timeout: <duration>             # optional
    resume: <session-id>            # optional
    append-system-prompt: <text>    # optional
    allowed-tools: <tools>          # optional
    output-format: <format>         # optional
    json-output-schema: <schema>    # optional

DESCRIPTION

The claude tool invokes Claude via the CLI’s non-interactive mode (-p flag). It sends a prompt, waits for the response, and returns the output. Unlike claude-code, this tool does not provide an interactive terminal session.

The tool runs in the project root directory, giving Claude access to the full project context for code-aware responses.

ARGUMENTS

Argument	Required	Default	Description
`prompt`	Yes	-	The prompt to send to Claude
`model`	No	Default model	Model to use (e.g., `sonnet`, `opus`)
`timeout`	No	`5m`	Maximum execution time
`resume`	No	-	Session ID to resume
`append-system-prompt`	No	-	Additional system prompt text
`allowed-tools`	No	-	Comma-separated list of allowed tools
`output-format`	No	-	Output format (e.g., `json`, `stream-json`)
`json-output-schema`	No	-	JSON Schema for structured output validation

Timeout Format

30s - 30 seconds
5m - 5 minutes
1h - 1 hour

EXIT CODES

Code	Meaning
`0`	Success
`1`	Claude CLI error or invalid arguments
`124`	Timeout exceeded

OUTPUT

Both stdout and stderr from Claude are merged and available for capture:

get-analysis:
  tool: claude
  arguments:
    prompt: "Analyze this code for bugs"
  output: var(analysis)

EXAMPLES

Simple Prompt

summarize:
  tool: claude
  arguments:
    prompt: "Summarize the README.md in this project"

With Model Selection

complex-analysis:
  tool: claude
  arguments:
    prompt: "{{ file(./prompts/analysis.md) }}"
    model: opus

With Timeout

long-task:
  tool: claude
  arguments:
    prompt: "Review all TypeScript files in src/"
    timeout: 10m
  on-error:
    124: handle-timeout

Using File Content

review-code:
  tool: claude
  arguments:
    prompt: |
      Review this code:

      {{ file(./src/main.ts) }}

Capturing Response

get-suggestion:
  tool: claude
  arguments:
    prompt: "Suggest a commit message for the staged changes"
  output: var(commit_message)
  next: show-message

show-message:
  tool: bash
  arguments:
    command: 'echo "Suggested: {{ commit_message }}"'

With Allowed Tools

code-task:
  tool: claude
  arguments:
    prompt: "Fix the failing tests in this project"
    allowed-tools: Read,Glob,Grep,Edit

JSON Output

structured-response:
  tool: claude
  arguments:
    prompt: "List all TODOs in the codebase as JSON"
    output-format: json
  output: var(todos_json)

JSON Schema Validation

Use json-output-schema to enforce a specific JSON structure. The schema ensures Claude’s response matches your expected format. When used, output-format is automatically set to json.

get-analysis:
  tool: claude
  arguments:
    prompt: "Analyze this codebase and provide a summary"
    json-output-schema: |
      {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "file_count": { "type": "integer" },
          "languages": {
            "type": "array",
            "items": { "type": "string" }
          },
          "recommendations": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["summary", "file_count", "languages"]
      }
  output: var(analysis)

The captured output contains only the validated JSON object (extracted from Claude’s structured_output response field), making it easy to use in subsequent states.

Schema from File

extract-data:
  tool: claude
  arguments:
    prompt: "Extract contact information from: {{ file(./input.txt) }}"
    json-output-schema: "{{ file(./schemas/contact.json) }}"
  output: var(contact_data)

Resuming Session

continue-conversation:
  tool: claude
  arguments:
    prompt: "Now implement the changes we discussed"
    resume: "{{ session_id }}"

WORKING DIRECTORY

The tool runs in the project root (directory containing .flowstate/), not the instance directory. This gives Claude access to the full project context.