claude-code

NAME

claude-code - open an interactive Claude Code session

SYNOPSIS

state-name:
  tool: claude-code
  arguments:
    prompt: <initial-prompt>
    model: <model-name>  # optional

DESCRIPTION

The claude-code tool launches an interactive Claude Code terminal session. Unlike the non-interactive claude tool, this provides the full TUI experience where users can continue the conversation, approve tool calls, and interact with Claude in real-time.

The session starts with the provided prompt as the initial message. The user then interacts freely until exiting the session (Ctrl+C or completing the task).

Important: This tool does not support output capture. The session is fully interactive with the terminal.

ARGUMENTS

Argument	Required	Default	Description
`prompt`	Yes	-	Initial prompt to start the session
`model`	No	Default model	Model to use (e.g., `sonnet`, `opus`)

EXIT CODES

Code	Meaning
`0`	Session completed normally
`1`	Failed to start Claude
Other	User exit or error

OUTPUT

Output capture is not supported. A warning is displayed if output is specified:

Warning: claude-code tool does not support output capture. Running interactively.

EXAMPLES

Basic Interactive Session

code-with-claude:
  tool: claude-code
  arguments:
    prompt: "Help me refactor the authentication module"

With Model Selection

complex-task:
  tool: claude-code
  arguments:
    prompt: "{{ file(./prompts/architecture-review.md) }}"
    model: opus

In a Workflow

start-at: prepare

states:
  prepare:
    tool: bash
    arguments:
      command: git checkout -b feature/new-api
    next: implement

  implement:
    tool: claude-code
    arguments:
      prompt: |
        Implement a new REST API endpoint for user preferences.

        Requirements:
        - GET /api/users/:id/preferences
        - POST /api/users/:id/preferences
        - Follow existing patterns in src/routes/
    next: review

  review:
    tool: bash
    arguments:
      command: npm test

Following Up

When the workflow continues after a claude-code session, subsequent states can work with any files Claude created or modified:

implement:
  tool: claude-code
  arguments:
    prompt: "Create unit tests for the UserService class"
  next: verify-tests

verify-tests:
  tool: bash
  arguments:
    command: npm test -- --coverage

WORKING DIRECTORY

The session runs in the project root directory, giving Claude full access to the codebase. This matches the behavior of running claude directly in the terminal.

RESTRICTIONS

Cannot be used in parallel blocks (requires interactive terminal)
No output capture available
Session blocks workflow until user exits

USE CASES

Human-in-the-Loop Development

start-at: setup

states:
  setup:
    tool: bash
    arguments:
      command: |
        git fetch origin
        git checkout -b feature/$(date +%Y%m%d)
    next: develop

  develop:
    tool: claude-code
    arguments:
      prompt: |
        I need to implement {{ feature_description }}.

        Context:
        {{ file(@/docs/requirements.md) }}
    next: test

  test:
    tool: bash
    arguments:
      command: npm test
    on-error:
      _: develop  # Go back to Claude if tests fail
    next: done

Code Review Sessions

review-session:
  tool: claude-code
  arguments:
    prompt: |
      Please review the changes in this PR:

      $(git diff main...HEAD)

      Focus on:
      - Security concerns
      - Performance implications
      - Code style consistency