@chirag127/agentflow

Parallel AI agent orchestrator powered by LangGraph, Git worktrees, Mem0, and MCP servers.

Agentflow decomposes complex tasks into independent subtasks and executes them in parallel using isolated AI agents. Each agent runs in its own Git worktree, integrates optional persistent memory via Mem0, and accesses 16 MCP servers for powerful tool capabilities.

Installation

Global Install

npm install -g @chirag127/agentflow
agentflow --version

With npx

npx @chirag127/agentflow deploy -t "Build a REST API" -n 5

Quick Start

1. Create .env

npx @chirag127/agentflow init
cp .env.example .env

Edit .env and add your API keys:

# Required
NVIDIA_API_KEY=nvapi-...

# Optional
MEM0_API_KEY=m0-...
BRAVE_API_KEY=...
EXA_API_KEY=...
LINKUP_API_KEY=...
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...
POSTGRES_CONNECTION_STRING=postgresql://...
SLACK_BOT_TOKEN=xoxb-...
GOOGLE_MAPS_API_KEY=...

2. Run Deployment

agentflow deploy -t "Build a REST API with Express.js" -n 5

3. Check Results

Results table shows each task's status (✓/✗) and truncated output.

Commands

agentflow deploy

Deploy and execute the orchestration.

Flags:

• -t, --task <task> (required) — Main task description
• -n, --count <count> (required) — Number of agents to spawn
• --dry-run — Run planning phase only (show task decomposition)
• --verbose — Verbose logging
• --timeout <minutes> — Execution timeout (default: 10 minutes)

Example:

agentflow deploy -t "Implement OAuth2 flow" -n 3
agentflow deploy -t "Audit code" -n 2 --dry-run
agentflow deploy -t "Build API" -n 5 --timeout 30 --verbose

agentflow init

Generate .env.example template.

agentflow init

agentflow status

List active agent worktrees.

agentflow status

agentflow clean

Remove all agent worktrees and branches.

agentflow clean

Architecture

State Machine

START → Supervisor (Plan) → (decide) → Workers (Execute) → Supervisor → ... → END

1. Supervisor (Plan Phase): Uses LLM to decompose the main task into 3–7 independent subtasks (JSON array).
2. Workers (Execute Phase): Each worker runs a task in its own Git worktree:
   • Spawns worktree with unique branch name (includes timestamp to prevent collisions)
   • Adds task to optional Mem0 memory store
   • Runs manual 5-iteration agentic loop:
     • Bind LLM with MCP tools
     • Call LLM with task + memories
     • Parse tool calls and execute them
     • Accumulate results as ToolMessage
     • Continue until LLM outputs no more tools or iteration limit reached
   • Detects spawned subtasks via <new_tasks>["task1","task2"]</new_tasks> marker
   • Returns result (success/error/spawned tasks)
3. Recursion: All workers complete → Supervisor checks if done → If more tasks exist, loop back to Workers

Why Replacement Reducers?

All state annotations use Annotation({ value: (_x, y) => y }) to ensure replacement, never accumulation. This prevents bugs where old state accidentally persists.

Why Manual Tool Loop?

No createReactAgent — manual iteration is explicit, testable, and supports custom post-processing (e.g., spawned tasks detection).

Workspace Isolation

Each agent task runs in a separate Git worktree, ensuring:

• No file conflicts (independent file systems)
• Clean rollback (delete worktree on completion)
• Reproducibility (consistent starting state)

MCP Servers (16)

| Server | Type | Required Env Var | Optional | Transport | |--------|------|------------------|----------|-----------| | filesystem | local files & dirs | – | No | stdio | | git | git operations | – | No | stdio | | fetch | HTTP requests | – | No | stdio | | memory | key-value store | – | No | stdio | | sequential-thinking | reasoning | – | No | stdio | | sqlite | local DB | – | No | stdio | | puppeteer | browser automation | – | No | stdio | | time | system time | – | No | stdio | | everything | general utilities | – | No | stdio | | brave-search | web search | BRAVE_API_KEY | Yes | stdio | | exa | semantic search | EXA_API_KEY | Yes | streamable-http | | linkup | link fetching | LINKUP_API_KEY | Yes | streamable-http | | github | GitHub API | GITHUB_PERSONAL_ACCESS_TOKEN | Yes | stdio | | postgres | PostgreSQL | POSTGRES_CONNECTION_STRING | Yes | stdio | | slack | Slack messaging | SLACK_BOT_TOKEN | Yes | stdio | | google-maps | maps & routing | GOOGLE_MAPS_API_KEY | Yes | stdio |

Optional servers are silently skipped if their env var is not set.

Troubleshooting

Error: NVIDIA_API_KEY is required

Solution: Set NVIDIA_API_KEY in your .env file.

echo "NVIDIA_API_KEY=nvapi-xxx" > .env

Error: GraphRecursionError — Recursion limit exceeded

Cause: Supervisor gets stuck in infinite loop (task never completes or new tasks spawn faster than completion). Solution:

• Increase --timeout if tasks are legitimately long
• Check Supervisor prompt for infinite task spawning
• Investigate worker logs with --verbose

Error: HTTP 405 from Exa/Linkup

Cause: Using wrong transport (likely "sse" instead of "streamable-http"). Solution: Verify agents_mcp_config.json has "transport": "streamable-http" for Exa and Linkup.

Error: fatal: pathspec '...' did not match any files

Cause: Git worktree branch collision (likely from previous crashed run). Solution: Clean up:

agentflow clean
git worktree prune

Error: ENOENT: no such file or directory, open '.agents/memory.db'

Cause: SQLite server needs directory to exist. Solution: Manually create or let agentflow do it:

mkdir -p .agents

Contributing

Contributions welcome! Fork the repo, create a branch, and submit a PR.

License

MIT — see LICENSE file

Get started now:

npm install -g @chirag127/agentflow
agentflow init
agentflow deploy -t "Write a hello world Express server" -n 3 --dry-run