AI-Assisted Development

This guide helps you use AI coding assistants (Claude Code, Cursor, Copilot, Windsurf, etc.) effectively when building applications with Ironflow.

Why This Matters

AI assistants excel at writing workflow code when they understand the core architectural patterns. Without proper context, they often make predictable mistakes:

Non-idempotent steps: Creating side effects that repeat on retry.
Side effects outside steps: Performing I/O that runs on every replay.
Missing memoization: Treating workflows like standard scripts.
Incorrect event matching: Using wrong field paths for correlation.

Setup Guide

1. Set Up the MCP Server

The MCP server lets your AI assistant interact with your Ironflow server directly from the IDE — inspect runs, emit events, query projections, and debug.

Add to your project’s .mcp.json:

{
  "mcpServers": {
    "ironflow": {
      "command": "ironflow",
      "args": ["mcp", "--allow-writes"]
    }
  }
}

For servers with auth enabled or custom URLs:

{
  "mcpServers": {
    "ironflow": {
      "command": "ironflow",
      "args": ["mcp", "--allow-writes", "--server-url", "http://localhost:9000", "--api-key", "ifkey_your_key"]
    }
  }
}

2. Install AI Skills (Recommended)

Install AI Skills for interactive, workflow-guided assistance across Claude Code, Codex CLI, and Gemini CLI.

If you have not installed Ironflow yet, one command gets the skills and wires your agent:

npx skills add sahina/ironflow-releases

If you already run the engine, sync them from the binary instead — they match its version exactly:

ironflow skills sync
ironflow skills doctor

Skills activate automatically based on your prompt — use /ironflow as the universal entry point, or invoke specialized skills directly (/ironflow-fit, /ironflow-start, /ironflow-code, /ironflow-ops, /ironflow-docs).

3. Add the Agent Template

Copy the Agent Template as agent.md, CLAUDE.md, or .cursorrules in your project root. This gives the AI:

SDK reference for TypeScript and Go
Critical patterns (all side effects inside step.run(), unique step IDs, pure projections)
Common mistakes to avoid

If you’ve installed AI Skills, the agent template is optional — skills include the same SDK reference plus interactive workflows.

4. Use CLI for Development Loops

The CLI is your primary tool — it covers every Ironflow feature except the KV store, overview stats, and worker listing, which MCP covers instead. Config management is a gap in both: it is reachable only from the SDKs, the REST API, and the dashboard. MCP is read-only unless you pass --allow-writes. Key pattern:

# Test workflow with synchronous feedback
ironflow emit order.placed --data '{"orderId":"ord-1"}' --wait --json

# Debug failures
ironflow run list --status failed --json
ironflow run get <run-id> --json

# Time-travel debug
ironflow inspect <run-id>

The --wait flag is critical — it blocks until the run completes, giving the AI a tight build-test-fix loop.

What to Ask Your AI

“Create a workflow that processes orders with idempotent steps”
“Emit an order.placed event and show me the run result”
“Debug the failed run from step 3”
“Query the order-stats projection”
“Show me recent runs and their step outputs”

CLI vs MCP: When to Use Each

Use Case	Recommended Tool	Why
Testing workflows with feedback	CLI (`--wait` flag)	Synchronous result, tight loop
Debugging failed runs	CLI	Full step details, `--json` output
KV store operations	MCP	CLI has no `ironflow kv` command yet
Worker monitoring	MCP	`ironflow_list_workers` tool
Overview stats	MCP	`ironflow_overview` tool

See the full CLI vs MCP Coverage comparison for details.

In This Section

AI Skills — Install interactive skills for Claude Code, Codex CLI, and Gemini CLI.
MCP Server — Configure AI assistants to operate Ironflow from the IDE.
CLI vs MCP Coverage — Complete comparison of capabilities.
Agent Template — The full template to copy into your project.
Common Pitfalls — Mistakes AI makes and how to avoid them.
Build with AI Assistants — Step-by-step first workflow with AI assistance.