Workflows

Build complex multi-step AI orchestrations with YAML/JSON. Chain unlimited tools, pass outputs between steps, and create powerful automated reasoning processes.

What are Workflows?

Workflows let you chain multiple AI tools together into automated sequences. Each step can use outputs from previous steps, run in parallel, or branch conditionally. Think of them as recipes for collective intelligence.

Basic Workflow Structure

basic-workflow.yaml

Workflows vs Agent Chaining

TachiBot workflows go beyond simple sequential chaining. Here's the difference:

Simple Agent Chaining

Step 1

Step 2

Step 3

Step 4

One after another, linear flow.

TachiBot Swarm

Step 1 — Parallel

Model A

Model B

Model C

Model D

Synchronize all outputs

Deep collaborative reasoning (5 rounds)

Adversarial debate (3 rounds)

Final synthesis

Key Differences

Parallel execution — 4 models run simultaneously, not sequentially
Multi-round debates — Models argue and refine for N rounds
Different modes — Collaborative vs Debate vs Deep-reasoning
Synchronization — Combines outputs intelligently, not just concatenation
Adversarial verification — Models challenge each other's outputs

Simple Chaining

→

Sequential, one model per step

TachiBot Swarm

→

Sync

→

Debate×5

→

Challenge×3

→

Synth

Parallel + multi-round refinement

Variable Interpolation

Use ${variable_name} to reference outputs from previous steps:

variable-interpolation.yaml

Parallel Execution

Steps marked with parallel: true run simultaneously, dramatically reducing execution time.

Method 1: Group Parallel Steps (Recommended)

Use a single step with parallel: true and multiple tools:

parallel-group.yaml

Method 2: Individual Parallel Steps

Mark individual steps with parallel: true. All consecutive parallel steps run together:

parallel-individual.yaml

How Parallel Execution Works

Automatic batching — The workflow engine batches consecutive parallel: true steps
Wait for completion — The next non-parallel step waits for all parallel steps to finish
Variable access — Each parallel step outputs to its own variable, accessible in later steps
Error handling — If one parallel step fails, others continue; errors are collected
Performance gain — 4 parallel steps take ~1x time instead of 4x sequential time

Performance Example

Sequential: 4 models × 5 seconds each = 20 seconds total

Parallel: 4 models running simultaneously = ~5 seconds total

Real-Time Verification

Workflows can verify outputs against real-time information using Perplexity or Grok live search. This prevents hallucinations by grounding AI responses in actual, up-to-date data.

verified-workflow.yaml

Why This Matters

Prevents hallucinations — Models can't make up outdated information
Real-time accuracy — Get information from the past week, day, or hour
Cross-verification — Compare multiple search sources (Perplexity + Grok)
Fact-checking — Use verifier tool to validate claims against search results
Recency filters — Perplexity and Grok both support time-based filtering

Why Perplexity & Grok for Live Search?

TachiBot uses Perplexity and Grok for real-time verification because they provide explicit, parameterized recency filters:

Perplexity AI: Structured recency filters ("day," "week," "month," "year") via API
Grok: Deep Search with recency-focused filtering and trending information
Others: Gemini, Claude, and ChatGPT rely on prompt instructions only — no explicit recency API parameters

Best Practice: Always Verify

For critical decisions, use this pattern. Models brainstorm ideas, live search provides facts, verifier checks accuracy, then final synthesis combines both.

Generate

Verify

Synthesize

Complete Example: Multi-Model Council

The general-council workflow demonstrates TachiBot's orchestration power with 7 steps:

general-council.yaml

Running Workflows

Streaming Mode

For long-running workflows, use streaming mode to execute one step at a time with visual progress feedback:

Streaming mode provides real-time visual feedback with braille gradient progress bars, step-by-step output, and session management for pause/resume capability.

Workflow Features

Output Passing

Each step can save its output to a variable using output: variable_name. Later steps reference it with ${variable_name}.

Unlimited Steps

Chain as many steps as needed. Create complex multi-stage reasoning processes with dozens of steps.

JSON Support

Workflows work with both YAML and JSON formats:

api-review.json

Configuring Output

Control how step outputs are displayed using the output configuration.

Output Parameters

truncateSteps

Controls whether step outputs are truncated. Set to false for code review and UX analysis where you need full output.

maxStepTokens

Maximum tokens per step when truncating. Default: 2500 (~10,000 characters). Increase for research-heavy workflows.

Examples by Workflow Type

Runtime Override

Override workflow settings at runtime:

Workflow Type	truncateSteps	maxStepTokens	Reason
Quick brainstorm	`true`	`1000`	Fast iteration
Code review	`false`	—	Need full analysis
Research	`false`	—	Comprehensive findings
UX analysis	`false`	—	Full user journey
Debug workflow	`true`	`5000`	Balance detail/readability

Understanding Truncation Messages

When output is truncated, you'll see informative messages:

Reference

Detailed schema, built-in workflows, patterns, and management tools.

SchemaComplete Workflow Schema

Full TypeScript schema for workflow configuration with all parameters.

Key Features:

Sequential execution: Use tool + input for one-at-a-time steps
Parallel execution: Use parallel: true + tools array for simultaneous execution
Variable interpolation: Reference previous outputs with ${variable_name}
Flexible formats: Write workflows in YAML or JSON

Schema Requirements

name: Every step MUST have a name field
input: Use input (NOT params)
output: MUST be object { variable: "name" } (NOT string)

Built-inProduction-Ready Workflows

TachiBot ships with production-ready workflows you can run immediately.

1. Comprehensive Code Review

Multi-perspective code review covering architecture, security, performance, and readability. 6 steps with 4 parallel analyses using Gemini, Grok, Qwen, Perplexity, and OpenAI.

code-review.yaml

Usage: tachibot workflow run comprehensive-code-review "$(cat src/myfile.py)"

2. UX Research Flow

Iterative UX analysis with multi-model verification. Round 1: Identify issues (Gemini + OpenAI) → Verify with Perplexity. Round 2: Generate solutions (Qwen + Grok) → Verify → Challenge → Final synthesis.

ux-research-flow.yaml

Usage: tachibot workflow run ux-research-flow "$(cat src/components/Dashboard.tsx)"

3. Accessibility Code Audit

WCAG 2.2 compliance pipeline: Scan (Gemini) → Research standards (Perplexity) → Collaborative fix debate (Gemini + Qwen) → Multi-model verification → Generate fixed code (Qwen).

accessibility-code-audit.yaml

Usage: tachibot workflow run accessibility-code-audit "$(cat src/pages/index.html)"

4. Creative Brainstorm

5-step creative pipeline: Ideas (Gemini) → Expand (OpenAI) → Research validation (Perplexity) → Contrarian challenge → Final synthesis (Focus mode).

brainstorm.json

Usage: tachibot workflow run creative-brainstorm "New features for collaborative code editor"

Key Patterns in Built-in Workflows

Parallel execution: Code review runs 4 analyses simultaneously (4x faster)
Iterative verification: UX flow verifies after each round with different tools
Multi-model debates: Pingpong tool enables collaborative/debate modes
Research backing: Perplexity/Grok provide real-time validation
Adversarial testing: Challenger tool finds weaknesses in proposals
Cost optimization: Smart routing and caching keep costs low ($0.50–$2.00)

ExamplesWorkflow Patterns

Pattern 1: Sequential Research Pipeline

Research → Reason → Verify → Synthesize

research-pipeline.yaml

Pattern 2: Parallel Intelligence Gathering

Multiple models run simultaneously for diverse perspectives

parallel-analysis.yaml

Pattern 3: Adversarial Debate & Challenge

Models debate and challenge each other to improve quality

debate-workflow.yaml

Pattern 4: Code Analysis & Generation

Analyze requirements, generate code, review, and optimize

code-pipeline.yaml

Pattern 5: Market Intelligence Sync

Competitive analysis with multi-model debate and dual verification

market-intelligence-sync.yaml

APIWorkflow Management Tools

workflow — Execute a workflow

list_workflows — List available workflows

create_workflow — Create a custom workflow

visualize_workflow — Show workflow structure

Custom Workflows

TachiBot supports multiple ways to add and organize workflows. Choose the approach that best fits your use case.

For Different User Types

Contributors (Source Code)

If you're running TachiBot from source, add workflows directly to the package:

Teams (Project-Specific)

Share workflows via git — they'll be discovered automatically:

Now everyone on the team can run: workflow run deploy

Individuals (Personal)

Create personal workflows that work with any TachiBot installation:

Works with Claude Desktop (MCPB) — no rebuild needed.

Power Users (Ad-Hoc)

Run workflows from anywhere without registration:

Discovery Order

When you run workflow run my-flow, TachiBot searches in this order:

Project: .tachibot/workflows/my-flow.yaml (checked first)
User: ~/.config/tachibot/workflows/my-flow.yaml (checked second)
Built-in: <package>/workflows/my-flow.yaml (checked last)

First match wins! This lets you override built-in workflows with your own versions.

Subdirectory Organization

Workflows are discovered recursively (max 4 levels deep):

All found automatically. Organize however you like.

Best Practices by Use Case

Use Case	Location	Git Commit?
Built-in	`workflows/`	Yes
Team workflows	`.tachibot/workflows/`	Yes
Personal	`~/.config/tachibot/workflows/`	No
Experiments	Anywhere + `--file`	No

Troubleshooting

My workflow isn't showing in list_workflows

Check discovery order. Is it being overridden by another workflow with the same name?

Can I edit built-in workflows?

Copy to ~/.config/tachibot/workflows/ with the same name to override.

Does Claude Desktop MCPB need a rebuild?

No. Use ~/.config/tachibot/workflows/ — works immediately.

Best Practices

Start with diverse perspectives (multiple models)
Use synchronization steps to combine insights
Add challenge/debate steps to improve quality
End with synthesis for final recommendations
Name variables clearly (research_findings not r1)
Use parallel steps when inputs don't depend on each other
Set truncateSteps: false for comprehensive analysis workflows
Increase maxStepTokens for research-heavy workflows

Next Steps

Level up your orchestration skills

PingPong Debates

Make models debate in workflows

Explore Tools

See all available tools

Quick Start

More workflow examples

Workflows

Build complex multi-step AI orchestrations with YAML/JSON. Chain unlimited tools, pass outputs between steps, and create powerful automated reasoning processes.

What are Workflows?

Basic Workflow Structure

basic-workflow.yaml

Workflows vs Agent Chaining

TachiBot workflows go beyond simple sequential chaining. Here's the difference:

Simple Agent Chaining

Step 1

Step 2

Step 3

Step 4

One after another, linear flow.

TachiBot Swarm

Step 1 — Parallel

Model A

Model B

Model C

Model D

Synchronize all outputs

Deep collaborative reasoning (5 rounds)

Adversarial debate (3 rounds)

Final synthesis

Key Differences

Parallel execution — 4 models run simultaneously, not sequentially
Multi-round debates — Models argue and refine for N rounds
Different modes — Collaborative vs Debate vs Deep-reasoning
Synchronization — Combines outputs intelligently, not just concatenation
Adversarial verification — Models challenge each other's outputs

Simple Chaining

→

Sequential, one model per step

TachiBot Swarm

→

Sync

→

Debate×5

→

Challenge×3

→

Synth

Parallel + multi-round refinement

Variable Interpolation

Use ${variable_name} to reference outputs from previous steps:

variable-interpolation.yaml

Parallel Execution

Steps marked with parallel: true run simultaneously, dramatically reducing execution time.

Method 1: Group Parallel Steps (Recommended)

Use a single step with parallel: true and multiple tools:

parallel-group.yaml

Method 2: Individual Parallel Steps

Mark individual steps with parallel: true. All consecutive parallel steps run together:

parallel-individual.yaml

How Parallel Execution Works

Automatic batching — The workflow engine batches consecutive parallel: true steps
Wait for completion — The next non-parallel step waits for all parallel steps to finish
Variable access — Each parallel step outputs to its own variable, accessible in later steps
Error handling — If one parallel step fails, others continue; errors are collected
Performance gain — 4 parallel steps take ~1x time instead of 4x sequential time

Performance Example

Sequential: 4 models × 5 seconds each = 20 seconds total

Parallel: 4 models running simultaneously = ~5 seconds total

Real-Time Verification

Workflows can verify outputs against real-time information using Perplexity or Grok live search. This prevents hallucinations by grounding AI responses in actual, up-to-date data.

verified-workflow.yaml

Why This Matters

Prevents hallucinations — Models can't make up outdated information
Real-time accuracy — Get information from the past week, day, or hour
Cross-verification — Compare multiple search sources (Perplexity + Grok)
Fact-checking — Use verifier tool to validate claims against search results
Recency filters — Perplexity and Grok both support time-based filtering

Why Perplexity & Grok for Live Search?

TachiBot uses Perplexity and Grok for real-time verification because they provide explicit, parameterized recency filters:

Perplexity AI: Structured recency filters ("day," "week," "month," "year") via API
Grok: Deep Search with recency-focused filtering and trending information
Others: Gemini, Claude, and ChatGPT rely on prompt instructions only — no explicit recency API parameters

Best Practice: Always Verify

For critical decisions, use this pattern. Models brainstorm ideas, live search provides facts, verifier checks accuracy, then final synthesis combines both.

Generate

Verify

Synthesize

Complete Example: Multi-Model Council

The general-council workflow demonstrates TachiBot's orchestration power with 7 steps:

general-council.yaml

Running Workflows

Streaming Mode

For long-running workflows, use streaming mode to execute one step at a time with visual progress feedback:

Streaming mode provides real-time visual feedback with braille gradient progress bars, step-by-step output, and session management for pause/resume capability.

Workflow Features

Output Passing

Each step can save its output to a variable using output: variable_name. Later steps reference it with ${variable_name}.

Unlimited Steps

Chain as many steps as needed. Create complex multi-stage reasoning processes with dozens of steps.

JSON Support

Workflows work with both YAML and JSON formats:

api-review.json

Configuring Output

Control how step outputs are displayed using the output configuration.

Output Parameters

truncateSteps

Controls whether step outputs are truncated. Set to false for code review and UX analysis where you need full output.

maxStepTokens

Maximum tokens per step when truncating. Default: 2500 (~10,000 characters). Increase for research-heavy workflows.

Examples by Workflow Type

Runtime Override

Override workflow settings at runtime:

Workflow Type	truncateSteps	maxStepTokens	Reason
Quick brainstorm	`true`	`1000`	Fast iteration
Code review	`false`	—	Need full analysis
Research	`false`	—	Comprehensive findings
UX analysis	`false`	—	Full user journey
Debug workflow	`true`	`5000`	Balance detail/readability

Understanding Truncation Messages

When output is truncated, you'll see informative messages:

Reference

Detailed schema, built-in workflows, patterns, and management tools.

SchemaComplete Workflow Schema

Full TypeScript schema for workflow configuration with all parameters.

Key Features:

Sequential execution: Use tool + input for one-at-a-time steps
Parallel execution: Use parallel: true + tools array for simultaneous execution
Variable interpolation: Reference previous outputs with ${variable_name}
Flexible formats: Write workflows in YAML or JSON

Schema Requirements

name: Every step MUST have a name field
input: Use input (NOT params)
output: MUST be object { variable: "name" } (NOT string)

Built-inProduction-Ready Workflows

TachiBot ships with production-ready workflows you can run immediately.

1. Comprehensive Code Review

Multi-perspective code review covering architecture, security, performance, and readability. 6 steps with 4 parallel analyses using Gemini, Grok, Qwen, Perplexity, and OpenAI.

code-review.yaml

Usage: tachibot workflow run comprehensive-code-review "$(cat src/myfile.py)"

2. UX Research Flow

ux-research-flow.yaml

Usage: tachibot workflow run ux-research-flow "$(cat src/components/Dashboard.tsx)"

3. Accessibility Code Audit

WCAG 2.2 compliance pipeline: Scan (Gemini) → Research standards (Perplexity) → Collaborative fix debate (Gemini + Qwen) → Multi-model verification → Generate fixed code (Qwen).

accessibility-code-audit.yaml

Usage: tachibot workflow run accessibility-code-audit "$(cat src/pages/index.html)"

4. Creative Brainstorm

5-step creative pipeline: Ideas (Gemini) → Expand (OpenAI) → Research validation (Perplexity) → Contrarian challenge → Final synthesis (Focus mode).

brainstorm.json

Usage: tachibot workflow run creative-brainstorm "New features for collaborative code editor"

Key Patterns in Built-in Workflows

Parallel execution: Code review runs 4 analyses simultaneously (4x faster)
Iterative verification: UX flow verifies after each round with different tools
Multi-model debates: Pingpong tool enables collaborative/debate modes
Research backing: Perplexity/Grok provide real-time validation
Adversarial testing: Challenger tool finds weaknesses in proposals
Cost optimization: Smart routing and caching keep costs low ($0.50–$2.00)

ExamplesWorkflow Patterns

Pattern 1: Sequential Research Pipeline

Research → Reason → Verify → Synthesize

research-pipeline.yaml

Pattern 2: Parallel Intelligence Gathering

Multiple models run simultaneously for diverse perspectives

parallel-analysis.yaml

Pattern 3: Adversarial Debate & Challenge

Models debate and challenge each other to improve quality

debate-workflow.yaml

Pattern 4: Code Analysis & Generation

Analyze requirements, generate code, review, and optimize

code-pipeline.yaml

Pattern 5: Market Intelligence Sync

Competitive analysis with multi-model debate and dual verification

market-intelligence-sync.yaml

APIWorkflow Management Tools

workflow — Execute a workflow

list_workflows — List available workflows

create_workflow — Create a custom workflow

visualize_workflow — Show workflow structure

Custom Workflows

TachiBot supports multiple ways to add and organize workflows. Choose the approach that best fits your use case.

For Different User Types

Contributors (Source Code)

If you're running TachiBot from source, add workflows directly to the package:

Teams (Project-Specific)

Share workflows via git — they'll be discovered automatically:

Now everyone on the team can run: workflow run deploy

Individuals (Personal)

Create personal workflows that work with any TachiBot installation:

Works with Claude Desktop (MCPB) — no rebuild needed.

Power Users (Ad-Hoc)

Run workflows from anywhere without registration:

Discovery Order

When you run workflow run my-flow, TachiBot searches in this order:

Project: .tachibot/workflows/my-flow.yaml (checked first)
User: ~/.config/tachibot/workflows/my-flow.yaml (checked second)
Built-in: <package>/workflows/my-flow.yaml (checked last)

First match wins! This lets you override built-in workflows with your own versions.

Subdirectory Organization

Workflows are discovered recursively (max 4 levels deep):

All found automatically. Organize however you like.

Best Practices by Use Case

Use Case	Location	Git Commit?
Built-in	`workflows/`	Yes
Team workflows	`.tachibot/workflows/`	Yes
Personal	`~/.config/tachibot/workflows/`	No
Experiments	Anywhere + `--file`	No

Troubleshooting

My workflow isn't showing in list_workflows

Check discovery order. Is it being overridden by another workflow with the same name?

Can I edit built-in workflows?

Copy to ~/.config/tachibot/workflows/ with the same name to override.

Does Claude Desktop MCPB need a rebuild?

No. Use ~/.config/tachibot/workflows/ — works immediately.

Best Practices

Start with diverse perspectives (multiple models)
Use synchronization steps to combine insights
Add challenge/debate steps to improve quality
End with synthesis for final recommendations
Name variables clearly (research_findings not r1)
Use parallel steps when inputs don't depend on each other
Set truncateSteps: false for comprehensive analysis workflows
Increase maxStepTokens for research-heavy workflows

Next Steps

Level up your orchestration skills

PingPong Debates

Make models debate in workflows

Explore Tools

See all available tools

Quick Start

More workflow examples