AgentFlow is an autonomous multi-agent task runner that bridges the gap between high-level user intent and executable work. Users submit a goal in natural language; an orchestrator agent decomposes it into structured sub-tasks, dispatches t
Master briefing file with problem statement, dev commands, and architecture principles.
AgentFlow is an autonomous multi-agent task runner that bridges the gap between high-level user intent and executable work. Users submit a goal in natural language; an orchestrator agent decomposes it into structured sub-tasks, dispatches them to specialized worker agents, and streams live telemetry — progress, intermediate results, and final outputs — back to the user in real time.
Problem solved: Complex multi-step tasks currently require manual decomposition, sequential execution, and status tracking. AgentFlow automates the entire pipeline — planning, routing, execution, and observability — in a single deterministic TypeScript runtime with no Python dependencies or ML framework abstractions.
Key capabilities:
| User Segment | Value Proposition |
|---|---|
| Developers | Describe a feature or bug fix; agents generate, test, and review code autonomously with full traceability. |
| Product Managers | Define a product goal; agents research competitors, draft specs, and generate action plans without manual coordination. |
| DevOps / SREs | Specify an operational task (e.g., "investigate latency spike"); agents gather metrics, analyze logs, and produce remediation steps. |
| Content / Research Teams | Outline a deliverable; agents gather sources, draft content, and review for quality in a streaming workflow. |
Differentiators:
| Layer | Technology | Rationale |
|---|---|---|
| Framework | Next.js 16 (App Router) | Native streaming support via streamResponse and Route Handlers for SSE; Server Actions for mutations; zero-config TypeScript. |
| Language | TypeScript (strict mode) | Deterministic agent logic demands type safety end-to-end: from task schemas to agent outputs. |
| Styling | Tailwind CSS v4 | Utility-first, zero-runtime CSS via @tailwindcss/vite plugin; rapid UI iteration for dashboard. |
| LLM Provider | OpenRouter API | Unified endpoint for multiple models (GPT-4o, Claude, Gemini); simple fetch-based integration; no SDK dependency. |
| Database | MongoDB + Mongoose | Flexible schema for heterogeneous task metadata, agent state snapshots, and telemetry history. |
| Streaming | Server-Sent Events (SSE) | Native browser support, simpler than WebSockets for unidirectional telemetry, first-class support in Next.js Route Handlers. |
| Runtime | Node.js 22+ | Native fetch, ReadableStream, and EventSource support; no bundler polyfills needed. |
The project philosophy is explicit control flow. Agent behavior is defined by typed state machines and decision functions in TypeScript — not by framework-managed chains. Every if/else, every task routing rule, every retry policy is visible and testable in source code.
git clone <repo-url> agentflow && cd agentflow
pnpm install
.env.local)# OpenRouter
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
DEFAULT_MODEL=anthropic/claude-3.5-sonnet-20241022
# MongoDB
MONGODB_URI=mongodb://localhost:27017/agentflow
# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
pnpm dev # Start Next.js dev server (port 3000)
pnpm dev:db # Start MongoDB via Docker (port 27017) — requires Docker
pnpm typecheck # Run tsc --noEmit for type validation
pnpm test # Run Vitest unit tests
pnpm test:coverage # Run tests with coverage report
| Service | Port |
|---|---|
| Next.js App | 3000 |
| MongoDB | 27017 |
| E2E Tests (Playwright) | 3001 |
agentflow/
├── app/ # App Router pages & API routes
│ ├── page.tsx # Dashboard UI (goal input + telemetry feed)
│ ├── layout.tsx # Root layout with Tailwind providers
│ ├── api/
│ │ ├── tasks/route.ts # POST new goal → create task
│ │ ├── tasks/[id]/stream/route.ts # SSE telemetry endpoint
│ │ └── tasks/[id]/route.ts # GET task status & results
│ └── dashboard/
│ └── page.tsx # Task history & analytics view
├── agents/ # Agent logic (pure TypeScript)
│ ├── orchestrator/
│ │ ├── index.ts # Entry point: receives goal, returns task plan
│ │ ├── decompose.ts # Goal → sub-task decomposition logic
│ │ └── router.ts # Sub-task → worker assignment
│ ├── workers/
│ │ ├── base.ts # BaseWorker: common LLM call + retry logic
│ │ ├── code-executor.ts # Worker: writes/runs code
│ │ ├── researcher.ts # Worker: gathers information
│ │ ├── synthesizer.ts # Worker: combines outputs
│ │ └── reviewer.ts # Worker: quality checks
│ └── types.ts # Shared agent type definitions
├── lib/ # Infrastructure utilities
│ ├── openrouter.ts # OpenRouter fetch wrapper
│ ├── mongodb.ts # Mongoose connection + helpers
│ ├── stream.ts # SSE stream helper for Route Handlers
│ └── retry.ts # Deterministic retry policy
├── models/ # Mongoose schemas
│ ├── Task.ts # Task document (goal, status, sub-tasks)
│ ├── Telemetry.ts # Telemetry event document
│ └── AgentRun.ts # Agent execution snapshot
├── components/ # UI components
│ ├── TelemetryFeed.tsx # Live SSE consumer (React hook)
│ ├── TaskPanel.tsx # Task creation + status card
│ └── AgentLog.tsx # Individual agent output display
├── tests/ # Vitest test suites
│ ├── orchestrator.test.ts
│ ├── workers.test.ts
│ └── stream.test.ts
├── package.json
├── tsconfig.json
├── tailwind.config.ts
└── vite.config.ts
BaseWorker (3 methods: execute(), validate(), formatOutput()) and is independently testable without spinning up a server.AgentMessage objects (success, failure, progress) consumed by the orchestrator — no shared mutable state between agents.