AI-Assisted Development

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

If you use Zed or a JetBrains IDE, you can also use the Ironflow agent (@ironflow/agent). It is an ACP coding agent that carries the Ironflow skills and runs with your own model key, so the setup below is not necessary for it.

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"],
      "env": { "IRONFLOW_API_KEY": "${IRONFLOW_API_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, paste this into your agent. It installs the engine and the skills, showing you each command first:

Read https://ironflow.run/start.md and set up Ironflow in this project.

To install only the skills, without the engine:

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 --agent claude  # or codex, gemini

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, Go and Python
• 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, worker listing, documentation retrieval, and the reload barrier, 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.
• Ironflow Agent for Zed and JetBrains — An ACP coding agent with the Ironflow skills built in. Bring your own model key.
• Remote MCP — Let a hosted AI agent use an Ironflow engine over MCP with its own API key.
• Run the Ironflow Agent Against a Team Server — Server setup, keys, data flow and rollout for teams that share one server.
• 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.