AgentFlow

Pipeline-based orchestration for AI coding agents. Build multi-step task graphs, run them with Claude Code, Codex, Gemini, or Antigravity CLI, and monitor the whole workflow from a visual dashboard or over MCP.

Run it

npx @argustech/agentflow

Open http://localhost:3100. No install, no config — npx pulls the package, builds the runtime, starts the dashboard on port 3100.

You'll also need at least one supported AI CLI on your machine (see Supported Agent CLIs below).

Highlights

• Multi-agent execution for Claude Code, Codex CLI, Gemini CLI, and Antigravity CLI (agy)
• Real-time dashboard for pipeline state, logs, outputs, and git diffs
• MCP server for programmatic pipeline control from compatible clients
• Git worktree isolation so tasks can run without stepping on each other
• Interactive execution for approvals, follow-up questions, and tool access
• Shared pipeline context with built-in persistence on SQLite
• Optional Slack and Telegram notifications

Install

Requirements

• Node.js ^20.19.0 or >=22.12.0
• Git
• At least one supported AI CLI installed locally

From npm (recommended)

# One-shot run, no install (slowest start, no global pollution)
npx @argustech/agentflow

# Global install — provides the `agentflow` command on PATH
npm install -g @argustech/agentflow
agentflow                  # start the dashboard
agentflow --help           # see all commands

A specific version pin:

npx @argustech/agentflow@1.0.0

From source

git clone https://github.com/harun-yardimci/agentflow.git
cd agentflow
npm install
npm run dev

This is the right path if you want to hack on AgentFlow itself, run the unbundled dev server with hot reload, or contribute back.

Storage

AgentFlow stores its shared SQLite database at ~/.agentflow/agentflow.db by default. Override with AGENTFLOW_DB_PATH. Worktrees, attachments, and uploads live under the same directory.

Supported Agent CLIs

Install at least one of these tools before running pipelines:

• Claude Code: npm install -g @anthropic-ai/claude-code
• Codex CLI: npm install -g @openai/codex
• Gemini CLI: npm install -g @google/gemini-cli
• Antigravity CLI (agy): Google's successor to the Gemini CLI — see antigravity.google. The Gemini CLI stops serving free/Google One tiers on June 18, 2026; agy is the migration path.

Antigravity note: agy emits plain-text output only (no token/cost metrics), and this build's --model flag accepts only Google's backend-defined model ids — unrecognized values fall back to the account default. AgentFlow seeds the Gemini 3 family best-effort; model switching firms up as Google stabilizes those ids.

Development Commands

Run from a source checkout (git clone + npm install). End users of the published package don't need any of these — they just npx @argustech/agentflow.

npm run dev          # frontend + backend with hot reload
npm run dev:fe       # frontend only
npm run dev:be       # backend only
npm run lint         # eslint + typecheck
npm run typecheck    # typecheck only
npm test             # vitest run
npm run build        # production bundle
npm run mcp          # MCP server over stdio
npm start            # production server (from source)

MCP Usage

AgentFlow exposes an MCP server so compatible assistants can create and manage pipelines programmatically.

Important runtime notes:

• AGENTFLOW_PORT is the AgentFlow app port, not the internal dev API port
• In development, the UI runs on AGENTFLOW_PORT and the backend on AGENTFLOW_PORT + 1
• By default, npm run dev, npm start, and npm run mcp share the same DB unless AGENTFLOW_DB_PATH is overridden

Claude Code

# Globally installed
claude mcp add agentflow --env AGENTFLOW_PORT=3100 -- agentflow mcp

# Or via npx, no install needed
claude mcp add agentflow --env AGENTFLOW_PORT=3100 -- npx @argustech/agentflow mcp

Claude Desktop / Cursor

Add this to your MCP config file:

{
  "mcpServers": {
    "agentflow": {
      "command": "npx",
      "args": ["@argustech/agentflow", "mcp"],
      "env": {
        "AGENTFLOW_PORT": "3100"
      }
    }
  }
}

Available MCP Tools

Architecture

+------------------+     +-----------------+     +------------------+
|   React Frontend | --> | Express Backend | <-- |   MCP Server     |
|   (Vite + TW v4) |     | (REST API)      |     | (stdio / SSE)    |
+------------------+     +--------+--------+     +--------+---------+
                                  |                        |
                           +------+------+                 |
                           |   SQLite    | <---------------+
                           +------+------+
                                  |
                    +-------------+-------------+
                    |             |             |
              +-----------+ +-----------+ +-----------+
              | Claude CLI| | Codex CLI | | Gemini CLI|
              +-----------+ +-----------+ +-----------+

• Frontend: React 19, TypeScript strict mode, Tailwind CSS v4, Vite 7
• Backend: Express 5, better-sqlite3, Zod validation
• MCP: @modelcontextprotocol/sdk with stdio and SSE transports
• Execution: worker pool that spawns CLI processes inside isolated git worktrees

Configuration

Environment variables are documented in .env.example.

Project Structure

src/             Frontend (React components, hooks, context)
server/          Backend (Express routes, services, execution engine)
  db/            SQLite schema, connection, seed
  engine/        Task runner, worker pool, worktree manager
  executor/      CLI executor, templates, output parser
  routes/        REST API endpoints
  services/      Business logic
  safety/        Output safety checks
mcp/             MCP server
bin/             CLI entry point
tests/           Unit and integration tests

Community

• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Support guidance: SUPPORT.md
• Transfer and publish checklist: docs/release/repo-transfer-and-publish-checklist.md

License

AgentFlow core is licensed under Apache-2.0.