Agent-Native Integration Strategy

How Flow Mesh becomes indispensable to every coding agent/platform.

The Opportunity

Every coding agent (pi, Claude Code, Codex, Cursor, Windsurf, Cline, Aider) faces the same unsolved problem: work management is disconnected from code. The agent writes code, but:

  • Doesn't know what tasks exist across the team
  • Can't update project status when work completes
  • Can't coordinate with other agents or humans
  • Has no memory of what was done across sessions
  • Can't trigger cross-platform workflows (Asana → Discord → Beads)

Flow Mesh can be the work management brain that sits underneath every coding agent — the universal bridge between "what needs to be done" and "what's being coded."


Integration Depth Matrix

Platform Level 1: CLI Level 2: MCP Level 3: Native Level 4: Embedded
Pi ✅ Done ✅ Done 🟡 Extension 🟡 SDK
Claude Code ✅ Done ✅ Done 🟡 Plugin ❌ N/A
Cursor ✅ Done ✅ Done 🟡 Rules ❌ N/A
Codex ✅ Done ❌ No MCP 🟡 Instructions ❌ N/A
Windsurf ✅ Done ✅ MCP 🟡 Rules ❌ N/A
Cline ✅ Done ✅ MCP 🟡 Config ❌ N/A
Aider ✅ Done ❌ No MCP 🟡 Config ❌ N/A

Level 1: CLI (universal, already done)

Every agent can call mesh task list --format json. Zero integration cost.

  • Cost: 0 tokens for tool definition
  • Friction: Agent must know the commands exist (AGENTS.md / SKILL.md)
  • Already shipped: 36 CLI commands, all with --format json

Level 2: MCP (standardized, already done)

Agents with MCP support discover Flow Mesh tools automatically.

  • Cost: ~200 tokens (single gateway tool)
  • Friction: User adds mesh mcp to their MCP config
  • Already shipped: mesh_run tool + 4 resources (meshes, tasks, conflicts, status)

Level 3: Native (platform-specific, high value)

Deep integration that makes Flow Mesh "just work" with each platform.

Level 4: Embedded (SDK, pi-only)

Flow Mesh spawns and controls the agent programmatically.


Platform-Specific Integration Plans

🔵 Pi — Deepest Integration (Extension + SDK)

Pi has the richest extension API of any coding agent. Flow Mesh can integrate at 4 levels:

A. Pi Extension: pi-flow-mesh (npm package)

// .pi/extensions/flow-mesh.ts
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function(pi: ExtensionAPI) {
  // 1. AUTO-CONTEXT: Inject current task into every prompt
  pi.on("agent_start", async (_event, ctx) => {
    const task = await getCurrentTask();
    if (task) {
      ctx.setSystemPromptSuffix(
        `\nActive task: "${task.title}" (${task.status}, P${task.priority})\n` +
        `Mesh: ${task.mesh} | Asana: ${task.asana_url} | Discord: ${task.discord_url}`
      );
    }
  });

  // 2. AUTO-COMPLETE: When agent finishes work, update task status
  pi.on("session_end", async (_event, ctx) => {
    const task = await getCurrentTask();
    if (task && task.status === "in_progress") {
      const confirm = await ctx.ui.confirm(
        "Task Complete?",
        `Mark "${task.title}" as done?`
      );
      if (confirm) {
        await exec("mesh task close " + task.id);
        ctx.ui.notify("✅ Task marked complete, synced to Asana + Discord", "success");
      }
    }
  });

  // 3. TOOLS: Agent can manage tasks without leaving the session
  pi.registerTool({
    name: "mesh_tasks",
    description: "List, create, update, or close tasks across all connected systems",
    parameters: Type.Object({
      action: Type.String({ enum: ["list", "create", "update", "close", "show"] }),
      args: Type.Optional(Type.String()),
    }),
    execute: async ({ action, args }) => {
      return await exec(`mesh task ${action} ${args || ""} --format json`);
    },
  });

  pi.registerTool({
    name: "mesh_status",
    description: "Show sync status, conflicts, and pending events",
    execute: async () => await exec("mesh status --format json"),
  });

  // 4. COMMANDS: User can manage mesh from pi
  pi.registerCommand("task", {
    description: "Show current task and mesh status",
    handler: async (_args, ctx) => {
      const status = await exec("mesh status --format json");
      ctx.ui.notify(formatStatus(status), "info");
    },
  });

  pi.registerCommand("done", {
    description: "Mark current task as complete",
    handler: async (_args, ctx) => {
      await exec("mesh task close CURRENT_TASK_ID");
      ctx.ui.notify("Task closed and synced!", "success");
    },
  });

  // 5. EVENT HOOKS: Auto-commit links tasks to code changes
  pi.on("tool_result", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.startsWith("git commit")) {
      // Auto-add task reference to commit message
      const task = await getCurrentTask();
      if (task) {
        await exec(`mesh task update ${task.id} --note "Commit: ${extractCommitMsg(event)}"`);
      }
    }
  });
}

Distribution: pi install npm:pi-flow-mesh — one command install.

B. Pi SDK: Flow Mesh Controls Pi

Flow Mesh's intelligence layer already delegates coding to pi. With the SDK:

// Flow Mesh intelligence spawns pi programmatically
import { createAgentSession } from "@mariozechner/pi-coding-agent";

async function delegateToPi(task: Task, instructions: string) {
  const { session } = await createAgentSession({
    tools: ["read", "edit", "write", "bash"],
    workingDirectory: task.repoPath,
  });

  // Inject task context
  await session.prompt(
    `You are working on: "${task.title}"\n` +
    `Description: ${task.description}\n` +
    `Instructions: ${instructions}\n` +
    `When done, commit with message referencing task ${task.id}.`
  );

  // Stream progress back to Discord/Asana
  session.subscribe((event) => {
    if (event.type === "message_update") {
      meshClient.addComment(task.id, event.text);
    }
  });
}

Value prop: "Ask Flow Mesh to implement a feature in Discord → it assigns pi, pi writes the code, Flow Mesh updates Asana and Discord with results."

C. Pi Skill: SKILL.md (already done, 455 lines)

Auto-loads when pi works in a Flow Mesh project directory.


🟣 Claude Code — Plugin + MCP + Hooks

A. MCP Server (already done)

// .mcp.json in project root
{
  "mcpServers": {
    "flow-mesh": {
      "command": "mesh",
      "args": ["mcp"]
    }
  }
}

B. Claude Code Plugin (NEW)

Claude Code has a plugin system (.claude/plugins/). A Flow Mesh plugin would:

// .claude/plugins/flow-mesh/manifest.json
{
  "name": "flow-mesh",
  "description": "Bidirectional work sync — tasks, Asana, Discord",
  "version": "1.0.0",
  "mcpServers": {
    "flow-mesh": {
      "command": "mesh",
      "args": ["mcp"],
      "env": {}
    }
  },
  "agents": {
    "task-context": {
      "description": "Provides current task context to Claude",
      "trigger": "session_start"
    }
  }
}

C. Hooks Integration

Claude Code hooks fire on tool calls. Flow Mesh can hook into git commits:

// .claude/settings.json hooks
{
  "hooks": {
    "PostToolCall": [{
      "matcher": "bash:git commit*",
      "hooks": [{
        "command": "mesh task update CURRENT --note 'Committed: $(git log -1 --oneline)'",
        "type": "command"
      }]
    }]
  }
}

D. CLAUDE.md Auto-Instructions

<!-- CLAUDE.md in project root -->
## Flow Mesh Integration
This project uses Flow Mesh for task management.
- List tasks: `mesh task list --format json`
- Current task: check `mesh task list --status in_progress --format json`
- When completing work: `mesh task close TASK_ID`
- When creating sub-tasks: `mesh task create --mesh MESH_ID --title "Sub-task"`

🟢 Cursor — MCP + Rules

A. MCP Config

// .cursor/mcp.json
{
  "mcpServers": {
    "flow-mesh": {
      "command": "mesh",
      "args": ["mcp"],
      "env": {}
    }
  }
}

B. Cursor Rules

<!-- .cursorrules -->
## Task Management
This project uses Flow Mesh. When working on code:
1. Check current tasks: `mesh task list --format json`
2. Pick the highest priority unassigned task
3. When done, close it: `mesh task close TASK_ID`
4. Add notes: `mesh task update TASK_ID --note "Implemented X"`

C. Composer Agent Instructions

Cursor's Composer can be instructed to use Flow Mesh tools. The MCP gateway gives it access to all mesh commands.


🔴 OpenAI Codex — CLI + Instructions

Codex runs in a sandboxed environment with filesystem + shell access.

A. Pre-install in sandbox

# In codex setup
curl -fsSL https://flowme.sh/install | sh
mesh bootstrap --auto

B. Instructions file

<!-- codex instructions -->
Use `mesh` CLI for task management:
- `mesh task list --format json` — see what needs doing
- `mesh task update ID --status in_progress` — claim a task
- `mesh task close ID` — mark complete
- `mesh ask "what should I work on next?"` — AI triage

C. Codex tool definitions (if/when they support custom tools)

{
  "name": "mesh_run",
  "description": "Execute a Flow Mesh command for task management",
  "parameters": {
    "command": { "type": "string", "description": "mesh CLI command" }
  }
}

🟡 Windsurf / Cline / Aider

All follow the same pattern:

  1. MCP where supported (Windsurf, Cline)
  2. CLI via bash/shell tool
  3. Instructions file (.windsurfrules, .clinerules, .aider.conf.yml)

The Killer Feature: Agent Coordination

The real unlock isn't individual agent integration — it's multi-agent coordination through Flow Mesh:

         ┌──────────────────────────────────────────────┐
         │              Flow Mesh                        │
         │                                               │
         │  Task Queue ──── Event Ledger ──── Policies  │
         │       │               │                │      │
         └───────┼───────────────┼────────────────┼──────┘
                 │               │                │
    ┌────────────┼───────────────┼────────────────┼──────────┐
    │            │               │                │          │
    ▼            ▼               ▼                ▼          ▼
┌──────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐  ┌──────┐
│  Pi  │   │ Claude   │   │  Cursor  │   │  Codex   │  │Human │
│      │   │ Code     │   │          │   │          │  │      │
│ code │   │ review   │   │ frontend │   │ backend  │  │Asana │
└──────┘   └──────────┘   └──────────┘   └──────────┘  └──────┘

Scenario: A team uses multiple agents:

  1. Human creates task in Asana: "Add user authentication"
  2. Flow Mesh syncs to Discord + Beads
  3. Pi (via intelligence) decomposes into sub-tasks:
    • "Create auth middleware" (assigned to Codex)
    • "Build login page" (assigned to Cursor)
    • "Write auth tests" (assigned to Claude Code)
  4. Each agent picks up their task via mesh task list --status ready
  5. As each completes: mesh task close → syncs everywhere
  6. Flow Mesh intelligence detects all sub-tasks done → closes parent
  7. Human sees in Asana: "Add user authentication ✅" with full history

This is the product: Flow Mesh as the task orchestration layer for multi-agent development.


Packaging & Distribution per Platform

Pi

Artifact Path Install
Extension npm:pi-flow-mesh pi install npm:pi-flow-mesh
Skill SKILL.md in project Auto-loaded
MCP mcp.json pi-mcp-adapter

Claude Code

Artifact Path Install
MCP config .mcp.json Drop in project root
Plugin .claude/plugins/flow-mesh/ Drop in plugins dir
Instructions CLAUDE.md Auto-loaded

Cursor

Artifact Path Install
MCP config .cursor/mcp.json Drop in project root
Rules .cursorrules Drop in project root

Codex

Artifact Path Install
Binary $PATH curl | sh in sandbox setup
Instructions Task instructions Codex config

Universal

Artifact Description
mesh binary Works everywhere with shell access
--format json All commands output structured JSON
mesh mcp MCP stdio server for any MCP client
AGENTS.md Universal agent instruction file

Implementation Priority

Phase 1: Ship What Works (already done)

  • [x] CLI with --format json (36 commands)
  • [x] MCP gateway with resources
  • [x] SKILL.md for pi
  • [x] AGENTS.md for Claude Code

Phase 2: Native Extensions (HIGH VALUE)

  1. pi-flow-mesh npm extension — auto-context, task tools, commit hooks, /task command
  2. Claude Code .mcp.json template — zero-config MCP setup
  3. Cursor .cursor/mcp.json template — same
  4. Project scaffolding: mesh init generates all config files for detected agents

Phase 3: Deep Integration

  1. Pi SDK delegation — Flow Mesh spawns pi sessions programmatically
  2. Claude Code plugin — full plugin with manifest
  3. Auto-task assignment — intelligence assigns tasks to agents based on capabilities
  4. Cross-agent coordination — event-driven task handoffs

Phase 4: Platform Partnerships

  1. Cursor marketplace integration/listing
  2. Claude Code plugin marketplace submission
  3. Lovable/Bolt templates with Flow Mesh pre-configured
  4. VS Code extension (for Cursor/Windsurf users who don't use MCP)

mesh init — One Command Setup

$ mesh init
Detected: pi, claude-code, cursor

Created:
  .pi/extensions/flow-mesh.ts     — Pi extension (auto-context, task tools)
  .pi/skills/flow-mesh/SKILL.md   — Pi skill (task management guide)
  .mcp.json                       — Claude Code MCP config
  .cursor/mcp.json                — Cursor MCP config
  AGENTS.md                       — Universal agent instructions
  .flow-mesh.yaml                 — Project mesh config

Run: mesh serve
Then ask any agent: "What tasks need work?"

This single command makes Flow Mesh native to every agent in the project.


Revenue Angle

  • Community (free): CLI + MCP + instruction files (AGENTS.md, SKILL.md)
  • Pro ($19/mo): Pi extension auto-context, Claude plugin, commit hooks, intelligence delegation
  • Team ($49/mo): Multi-agent coordination, cross-agent task assignment, team dashboards
  • Enterprise: Custom agent policies, SSO, audit trails, SLA

The native integrations make the paid tiers dramatically more valuable — agents that "just know" what to work on and auto-update status are worth far more than manual CLI calls.

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.