海流

Prerequisites

• Bun v1.2.3+
• tmux
• Claude Code CLI
• jq
• Redis — optional, enables event persistence and delivery retry. Without it, pipeline events fire but aren't persisted. Run with docker run -d -p 6379:6379 redis.

1. Install dependencies

bun install

Setup

2. Install hooks

Haiflow uses Claude Code hooks to track session state. The setup command merges hook config into ~/.claude/settings.json:

bun run setup

The hooks are thin HTTP forwarders — they POST Claude Code events to the haiflow server. If the server isn't running, they silently no-op. They won't interfere with non-orchestrated Claude sessions (the server ignores unknown session IDs).

Setup

1. Create pipeline.json in your HAIFLOW_DATA_DIR (default /tmp/haiflow):

{
  "topics": {
    "design.ready": {
      "description": "Design agent completed its analysis",
      "subscribers": [
        {
          "session": "developer",
          "promptTemplate": "Implement this design:\n\n{{message}}"
        }
      ]
    },
    "code.ready": {
      "subscribers": [
        {
          "session": "code-reviewer",
          "promptTemplate": "Review these changes:\n\n{{message}}"
        }
      ]
    }
  },
  "emitters": {
    "design-agent": ["design.ready"],
    "developer": ["code.ready"]
  }
}

1. Start your agents and trigger the first one. The pipeline handles the rest.

```bash

Quick start

Integration examples

Haiflow works with any tool that can make HTTP requests. Here are a few examples:

n8n (example workflow templates included)

Import the chained calc workflow from examples/chained-calc/: - chained-calc-step1.json — Step 1: calculate 2+2 - chained-calc-step2.json — Step 2: multiply result by 5 - chained-calc-step3.json — Step 3: multiply result by 10 - pipeline-calc-chain.json — Pipeline configuration that wires them together

Edit .env and set HAIFLOW_API_KEY to any secret string you choose

bun run dev # starts server with hot reload ```

3. Configure environment (optional)

cp .env.example .env

View pipeline config, Redis status, and recent events

curl -s -H "Authorization: Bearer $HAIFLOW_API_KEY" \ http://localhost:3333/pipeline | jq .

API

See API.md for the full API reference: all endpoints, parameters, and examples. The same surface is also published as an interactive reference in the docs site.

Agent pipeline

Chain agents together with event-driven pub/sub. Each agent subscribes to topics it cares about and emits events when done — no hardcoded dependencies between agents.

Design Agent ──emit──▶ design.ready ──subscribe──▶ Developer Agent
Developer    ──emit──▶ code.ready   ──subscribe──▶ Code Reviewer
Reviewer     ──emit──▶ review.done  ──subscribe──▶ QA Agent

See Pipeline for setup.

Pipeline

The pipeline system lets you chain agents together using pub/sub topics. When an agent finishes a task, haiflow automatically emits its output to configured topics. Other agents subscribed to those topics receive the output as their next prompt.

Trigger the first agent — the pipeline chains the rest

curl -X POST http://localhost:3333/trigger \ -H "Authorization: Bearer $HAIFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "Analyse the Figma design at ...", "session": "design-agent"}' ```