FlowState Tools Reference

FlowState provides built-in tools for workflow automation. Each tool follows a consistent interface: receive arguments, perform an action, return an exit code.

Tool Categories

Execution Tools

Tool	Description
bash	Execute shell commands
claude	Non-interactive Claude prompts
claude-code	Interactive Claude Code sessions
codex	OpenAI Codex prompts
gemini	Google Gemini prompts

Input/Output Tools

Tool	Description
ask-user	Prompt for user input
get-gh-issue	Fetch GitHub issue details

Conditional Tools

Tool	Description
if-empty	Check if value is empty
if-not-empty	Check if value has content
if-equal	Check if two values are equal
if-not-equal	Check if two values differ
if-greater	Numeric comparison: left > right
if-less	Numeric comparison: left < right
if-greater-equal	Numeric comparison: left >= right
if-less-equal	Numeric comparison: left <= right

Flow Control Tools

Tool	Description
switch	Conditional branching
pause	Halt execution until resumed
sub-flow	Call another workflow
parallel	Run tasks concurrently
for-each	Iterate over items

Common Exit Codes

All tools follow standard exit code conventions:

Code	Meaning
0	Success
1	General error
2	Invalid arguments or tool not found
124	Timeout exceeded
130	User cancelled (Ctrl+C)
-1	Pause requested (internal)

Output Capture

Tools that produce stdout can have their output captured:

my-state:
  tool: bash
  arguments:
    command: echo "hello"
  output: var(greeting)

Capture destinations:

• var(name) - Store in a workflow variable
• file(path) - Write to a file

Tool Interface

Every tool implements:

1. Execute - Run with provided arguments
2. Validate - Check required arguments before execution
3. Log Display - Format for execution logging

Custom tools can be added by implementing the ITool interface in the FlowState codebase.