OpenFlow

A GUI desktop defines multi-agent workflows across Claude Code, Codex, Gemini and more — in parallel, full control.

Overview

OpenFlowDemo.mp4

OpenFlow is a local Electron app for orchestrating multi-agent coding workflows across agent platforms (Claude Code, Codex, Gemini, OpenCode, …).

Define a task into stages (e.g. plan → code → review), and each stage is run by an AI agent session on the platform of your choice. Tasks flow stage-to-stage with optional human-review gates. An optional leader agent can coordinate the sequence — for example, auto-rerunning the coding stage when the review stage hands back feedback.

OpenFlow is designed to give the user full control through the whole process. The stages are run by agent sessions: each task creates one tmux session, and each agent runs inside a tmux window in that tmux session. You can view and chat with the running agent session directly in the app, or attach the tmux session from your own terminal app (get yourself familiarity with basic tmux cmd helps, check docs/user-manual.md § Appendix › Tmux).

Agent integration. OpenFlow ships with a companion openflow CLI and /openflow skill for external agents and scripts. From any agent session, invoke /openflow to create a task by prompt instruction and drive its lifecycle (start, stop, resume, message the leader) without leaving the chat.

Task board — your workspace for every running and queued task.

Theater mode — full-screen view of a task, chat inline with the running agent.

Split view — watch up to four tasks side-by-side, iTerm2-style splits with live consoles.

Prerequisites

• macOS or Linux (Windows via WSL only for now).
• tmux on PATH — the app spawns it for every agent pane.
  • macOS: brew install tmux
  • Debian/Ubuntu: apt install tmux
• At least one agent CLI installed and on PATH (claude, codex, gemini, …). OpenFlow does not bundle them.
• For building from source: Node.js 22+ and pnpm 9+.

Install

Option A — Prebuilt DMG (recommended on macOS)

Or pick a specific build on the releases page.

1. Open the DMG and drag OpenFlow.app to /Applications.
2. First launch: builds are unsigned, so Gatekeeper blocks the app as "unidentified developer." Right-click → Open to bypass, or run xattr -dr com.apple.quarantine "/Applications/OpenFlow.app" once.

Option B — Build from source

git clone https://github.com/<owner>/openflow.git
cd openflow
pnpm install
pnpm dist           # produces release/mac-arm64/OpenFlow.app + DMG

Open release/mac-arm64/OpenFlow.app directly, or copy it to /Applications.

For an iterative dev loop (hot-reload Electron, no packaging), see docs/development.md.

Using the app

Create first task

1. Open OpenFlow. First run lands on the Setup page — finish it once and the app remembers your preferences.

2. Add a project. Sidebar → + Project. Point it at a local directory — only the path is stored, not the contents.

3. Create a task. + Task → choose the project, then fill in:

   • Description — the high-level task requirement, visible to every agent.

   • Stages — ordered work units. Each stage has its own prompt (the per-stage instruction) and is assigned to an agent.

   • Agents — each agent picks a platform (Claude Code, Codex, Gemini, …) and an optional agent prompt (from agent template). Assigning multiple stages to the same agent reuses one CLI session across those stages, so the later stage starts with the earlier stage's context still in scope (no /clear between them).

   • Team mode (per task)

     • Solo runs stages sequentially, one shot each, no rerun.
     • Team launches a coordinator (leader) agent alongside the stages. The leader watches each stage's output, dispatches the next stage, reruns earlier stages when a reviewer hands back feedback (e.g. reviewer → builder), and signals task completion. The leader is fully customizable — start from the built-in Default Leader agent template to see how it works, then fork your own and pick it under Advanced → Team leader.

   • Work-dir isolation (per task)

     • None runs the agents directly in the project repo.
     • Git Branch creates a fresh branch for the task in place.
     • Git Worktree creates a .worktrees/<taskId>/ checkout on a new branch so the main worktree stays untouched.

     The default for new tasks is configurable per project in Project settings.

   • Advanced (collapsed by default)

     • Max reruns / stage — caps how many times the leader can rerun a single stage (default 3).
     • Expected duration / stage — soft timeout used by the stuck-stage heuristic.
     • Team leader — pick a different prompt template, platform, or extra args for the coordinator on this task only.

4. Run the task. Hit Start. The task gets one tmux session; each agent runs in its own window inside that session, talking to the chosen CLI agent with the stage prompt. From the detail panel you can:

   • Watch live console output and reply to the agent inline. The console is expandable, or hit Theater mode for a full-screen view.
   • Open in Terminal to attach to the pane in iTerm2 or Terminal.app (macOS), or copy the tmux attach command and paste it into any terminal you prefer.

Task Flow

• Once started, OpenFlow walks the task through its stages, in order for solo mode, leader agent watches progress decide flow in leader mode
• There're review checkpoints that user can setup, flow will stop there until user approve (user can check work, e.g. a plan, a design doc, code, etc.)
• All agent sessions are running inside a tmux session. User can see agent session for each stage in live console. Treat them as regular agent sessions that are working on your prompt instruction. Chat with the sessions if needed, common conditions are stage is done and wait for approval, user checked the work and determine it needs revise. Leader agent can be prompted to control workflow as well, e.g. rerun a stage with certain context or new info (only difference to stage agent is, suggest to input your msg to a leader inbox, which will carry the native leader prompt along with your msg)
  • Click Open in Iterm2 to view tmux session in terminal
  • Console can be expanded as a drawer
  • Enter theater mode by click button on title bar, for full screen console view
• You'll receive system notification for task events, e.g. task done, wait your approval, stage idle, etc. Notification also shows in Inbox from left panel. All settings are configurable in system level and project level
• If you quit app while tasks are running, you can choose to kill the tmux sessions, or keep them alive (agents with ongoing prompt will continue to run. Tmux sessions will be reattached next time when app opens)

Building blocks

Three reusable pieces back every task. Each lives as a plain file under ~/.openflow/ and is editable from the app or on disk. Config them under Library in left panel:

• Agent platform — a CLI integration (Claude Code, Codex, Gemini, OpenCode, …). The platform definition (~/.openflow/platforms/*.yaml) tells OpenFlow how to spawn the CLI, resume CLI, detect when it's ready (a msg shows on screen, indicate session is ready), and boot prompts (check settings tooltip for details)
• Agent template — a reusable system prompt (~/.openflow/agents/*.md, YAML frontmatter + prompt body) that defines a role like builder, reviewer, or a custom team leader. Pick one when assigning an agent to a stage; templates are platform-agnostic and can be swapped between platforms.
• Workflow template — a saved task shape (~/.openflow/workflows/*.yaml): the ordered stages, default agents, and team-mode settings. Use one to spin up new tasks without redefining stages each time.

Install the openflow CLI

The CLI lets external agents (Claude Code, Codex, cron, scripts) create and dispatch OpenFlow tasks from any shell.

From the DMG app

Open OpenFlow → System settings → Command line tool → Install. This creates a per-user symlink:

~/.local/bin/openflow -> /Applications/OpenFlow.app/Contents/Resources/app/bin/openflow

Equivalent manual command:

mkdir -p "$HOME/.local/bin"
ln -sf "/Applications/OpenFlow.app/Contents/Resources/app/bin/openflow" \
       "$HOME/.local/bin/openflow"

Make sure ~/.local/bin is on PATH, then verify:

openflow task list

From source

pnpm install
pnpm cli:build
pnpm link --global       # exposes `openflow` on PATH

CLI quick tour

# Discover ids
openflow project list --json
openflow agent list --json
openflow platform list --json
openflow workflow list --json

# Create a task (opens the New Task dialog pre-filled in the app)
openflow task create \
  --project openflow \
  --title "Add login screen" \
  --agent claude:builder

# Or create + start immediately, no GUI prompt
TASK_ID=$(openflow task create --project openflow --title nightly \
  --agent claude:builder --direct --json | jq -r '.taskId')
openflow task start "$TASK_ID"

task list and the other read-only commands work directly against $OPENFLOW_HOME even when the app is closed. Mutating commands (task create, start, stop, restart, resume, inbox) require the app to be running with System settings → Local HTTP bridge enabled.

Full reference, spec schema, exit codes, and bridge details: docs/cli.md, or openflow docs from the shell.

Using the CLI from an AI agent

Once openflow is on PATH, any CLI-based agent (Claude Code, Codex, Gemini, …) can call it via its shell tool. A typical loop:

1. Agent runs openflow docs to read the up-to-date task-creation recipe.
2. Agent runs openflow project list --json, openflow agent list --json, openflow workflow list --json to discover ids.
3. Agent drafts a task with openflow task create … (default opens the New Task dialog so the human can review).
4. Human approves in the dialog, or the agent uses --direct and task start for fully automated runs.

For Claude Code specifically, allow openflow in the session's Bash permission rules so the prompts disappear.

Metadata directory

OpenFlow stores all metadata under ~/.openflow/ (override with OPENFLOW_HOME). All metadata are plain files — safe to inspect, version, debug, or copy between machines.

Each task has a dedicated dir, all stage & agent execution info are snapshotted and persisted there.

~/.openflow/
  settings.json            # app-wide settings (theme, log level, bridge port, …)
  agents/                  # agent prompt templates, one .md per prompt
    builder.md             #   YAML frontmatter + system prompt body
    reviewer.md
    coordinator.md
    …
  platforms/               # Agent platform definitions, one .yaml per platform
    claude.yaml            #   spawn command, ready signal, follow-up prompt
    codex.yaml
    gemini.yaml
    opencode.yaml
    …
  workflows/               # reusable workflow templates
    plan-code-review.yaml
    write-article.yaml
    …
  projects/
    index.json             # { id → repoPath }
    {projectId}/
      project.json
      tasks/{taskId}/
        task.json          # task metadata
        agents/{sessionId}/  # per agent: tmux session + log capture
        stages/{stageId}/
          run-{n}/
            input.json     # stage initial context & prompt
            output.json    # stage output (status & context for leader / other stages)
        leader/            # team-mode coordinator working dir
          commands.jsonl   # workflow dispatch cmd, e.g. start stage-0, mark task done
          inbox.jsonl      # engine + user msg → leader
          task.json        # task snapshot the leader sees each tick
          log.jsonl
      messages/inbox.jsonl
      notifications.jsonl
  logs/                    # app logs, rotated daily
  .runtime/
    cli-port.json          # localhost bridge port + per-start auth token

agents/, platforms/, and workflows/ are the customization surface: edit a .md or .yaml file and OpenFlow picks it up on next read (the in-app editors round-trip the same files). projects/ is owned by the app — prefer the GUI or CLI for changes there.

If you move the data dir, set OPENFLOW_HOME for both the app and the CLI; the CLI does not honor the GUI's stored override.

Settings worth knowing

~/.openflow/settings.json:

Field	Purpose
appearanceTheme	light / dark / system
colorTheme	Named accent palette
logLevel	trace / debug / info / warn / error
notificationsDisabled	Mute system notifications
localHttpBridgeEnabled	Allow CLI/agent task creation
localHttpBridgePort	Fixed 127.0.0.1 port (default 61234)
preferredTerminalId	iterm2 / terminal (macOS "Open in Terminal")
defaultAgentPlatformId	Default agent CLI in the New Task dialog

All of these are also editable from System settings in the app.

FAQ

Does OpenFlow send my code anywhere?

No. OpenFlow is a local Electron app — it spawns the agent CLIs you already use (claude, codex, gemini, …) inside local tmux sessions. Code and prompts only leave your machine through whichever agent CLI you choose to run, on whatever account you've configured. OpenFlow has no telemetry and no servers.

Does OpenFlow add any cost on top of the agent CLIs?

No. Each stage runs inside a normal agent CLI session against your own account/subscription. OpenFlow only orchestrates them — it doesn't proxy or re-bill requests.

Only minimum extra cost is from a separate leader agent loads orchestration rule and watch over other agents, with a little task context. The token consumption is low.

Does it bundle Claude Code / Codex / Gemini?

No. Install whichever CLIs you want and set it up under Library -> Agent Platforms.

"tmux not installed"

OpenFlow runs every agent inside a tmux pane. Install it:

• macOS: brew install tmux
• Debian/Ubuntu: apt install tmux

Agent CLI is on my PATH in the terminal but OpenFlow can't find it

macOS apps launched from Finder don't inherit your shell PATH. Either launch OpenFlow from a terminal once (open /Applications/OpenFlow.app) to populate the env, or edit the platform .yaml to use an absolute path like /opt/homebrew/bin/claude.

Agent failed to start: "did not become ready"

This usually means the CLI showed an unhandled boot prompt before the agent session was ready. Open the agent pane to confirm the screen, then update Library -> Agent Platforms for that CLI: keep a stable Ready pattern and add or fix the matching Boot prompt. See docs/user-manual.md → Agent platform bootstrap for ready-pattern and boot-prompt examples.

Gatekeeper blocks the DMG ("unidentified developer")

Builds are unsigned. Right-click the app → Open the first time, or run once:

xattr -dr com.apple.quarantine "/Applications/OpenFlow.app"

CLI exits with code 4 ("cannot connect to app bridge")

The openflow CLI talks to the running app over a local HTTP bridge. Open the app, enable the Local HTTP bridge in settings, and make sure OPENFLOW_HOME matches between app and CLI. Full exit-code table in docs/cli.md.

Can multiple stages share one agent session?

Yes. Assign multiple stages to the same agent and they reuse one CLI session — the later stage starts with the earlier stage's context still in scope, no /clear between them unless user specifies it.

How do tasks stay isolated from each other?

Per-task work-dir isolation mode: None (run in place), Git Branch (fresh branch in the repo), or Git Worktree (.worktrees/<taskId>/ checkout so the main worktree is untouched). Configurable per project.

For git project, recommend git worktree for workspace isolation.

What happens if I quit the app while tasks are running?

You're asked whether to kill the tmux sessions or keep them alive. Kept-alive agents keep working in tmux; OpenFlow reattaches them next launch.

Where is OpenFlow data stored?

Tasks, projects, and templates live under ~/.openflow/ (or $OPENFLOW_HOME). Building blocks (agent prompts, platforms, stage prompts) are plain files there — editable from the app or on disk.

Windows support?

WSL only for now. Native Windows is post-v1.

arm64 vs x64 DMG?

Builds are arch-specific. Apple Silicon Macs need OpenFlow-<version>-arm64.dmg. Intel needs an x64 build (produce one with pnpm dist on an Intel host).

References

• docs/user-manual.md: day-to-day usage — concepts, modes, talking to agents/leader, workflows, debugging, troubleshooting, configuration reference, tmux primer.
• docs/development.md: Building locally, contributing, packaging, architecture, log levels, environment isolation, and the team-mode coordinator loop all live in . CLI internals and the
• docs/cli.md: bridge protocol, cli, openflow <> agent session integration