Introduction to FlowState

FlowState is a workflow engine that orchestrates multi-step processes using a state machine model. It excels at tasks that span multiple tools, require human intervention, or need to survive interruptions.

What FlowState Solves

Traditional shell scripts fall short when workflows need to:

• Resume after interruption - A script stops mid-execution; you start over from scratch
• Wait for external events - Polling loops waste resources or block indefinitely
• Involve multiple AI tools - Coordinating Claude, Gemini, and Codex requires manual orchestration
• Track state across sessions - Variables and progress are lost when the terminal closes

FlowState addresses these with persistent workflow instances that pause, resume, and branch based on conditions.

Core Concepts

Workflows

A workflow is a YAML file defining a series of connected states. Each workflow has a name, starting state, and a collection of state definitions.

name: my-workflow
start-at: first-step

states:
  first-step:
    tool: bash
    arguments:
      command: echo "Hello"
    next: second-step

  second-step:
    tool: bash
    arguments:
      command: echo "Done"

States

States are the building blocks of workflows. Each state:

• Invokes a tool with arguments
• Optionally captures output to variables or files
• Transitions to the next state (or ends the workflow)
• Can handle errors via on-error mappings

Tools

FlowState provides built-in tools for common operations:

Tool	Purpose
bash	Execute shell commands
claude	Non-interactive Claude prompts
claude-code	Interactive Claude Code sessions
codex	OpenAI Codex prompts
gemini	Google Gemini prompts
ask-user	Prompt for user input
get-gh-issue	Fetch GitHub issue details
parallel	Run tasks concurrently
sub-flow	Call another workflow
pause	Halt execution until resumed
switch	Conditional branching

Variables

Variables store values that persist across states. Set them by capturing tool output:

get-name:
  tool: ask-user
  arguments:
    question: "What is your name?"
  output: var(user_name)
  next: greet

greet:
  tool: bash
  arguments:
    command: 'echo "Hello, {{ user_name }}"'

Instances

When you run a workflow, FlowState creates an instance - a working directory that stores:

• The workflow definition
• Variable values
• Execution state (current position, status)
• Output files

Instances enable pause/resume, parallel runs of the same workflow, and post-mortem debugging.

The State Machine Model

FlowState workflows follow a predictable execution pattern:

1. Start at the state specified by start-at
2. Execute the state’s tool with substituted arguments
3. If the tool succeeds, transition via next (or goto for switch)
4. If the tool fails, check on-error mappings
5. Repeat until reaching a terminal state (no next) or an unhandled error

This model makes workflows:

• Predictable - Each execution follows defined paths
• Debuggable - The current state is always known
• Recoverable - Failed states can route to error handlers

When to Use FlowState

FlowState is ideal for:

• Multi-step automation - Build, test, deploy pipelines
• AI-assisted workflows - Code review with multiple LLMs
• Human-in-the-loop processes - Gather input, process, await approval
• Event-driven orchestration - Pause until external conditions are met

Consider alternatives when:

• A simple shell script suffices (no resumption needed)
• You need sub-second task scheduling
• Workflows require distributed execution across machines