Content
# agentflow
<p align="center">
<strong>Lightweight Orchestration Engine — Built for AI Agent Teams</strong>
<br>
<em>Lightweight orchestration engine — built for AI Agent teams</em>
</p>
---
<p align="center">
<a href="#background">Background</a>
</p>
---
## Background
### The Problem
When an AI Agent leads a software project, chaos emerges fast:
1. **State drift** — multiple sub-agents executing, no one knows who is doing what
2. **Role confusion** — Leader writes code, Worker doesn't submit, Reviewer skips
3. **Hidden dependencies** — Task B starts before Task A finishes → cascade failure
4. **Cross-DAG conflicts** — same Worker busy on two branches, no coordination
5. **Invisible progress** — is it 50% or 80%? Nobody knows.
### Solution
agentflow is a **lightweight, MCP-native, embeddable orchestration engine**. It is not a SaaS — just a Go binary + SQLite.
### 24 MCP Tools
```
Namespace/DAG/Task management task_create, task_get, task_list,
task_transition, task_history,
task_query, task_create_batch
DAG lifecycle dag_create, dag_get, dag_list,
dag_update, dag_report, dag_flowchart
Worker registry worker_register, worker_get,
worker_list, worker_update, worker_status
Project queries project_next_tasks, project_blockers,
project_report
Health flow_ping, namespace_create,
namespace_list
```
### State Machine
```
assigned ──start──→ executing ──submit──→ review_pending ──pass──→ done
↑ ↑
resume──┐ reassign
│ │
rework_needed ←─rework─┘
│
reassign → assigned
cancel → cancelled
```
| Role | Allowed Transitions |
|------|-------------------|
| **Leader** | `start`, `resume`, `reassign`, `cancel` |
| **Worker** | `submit` |
| **Reviewer** | `pass`, `rework` |
### Architecture
```
Claude Code ──MCP stdio──→ agentflow (Go binary)
│
SQLite (file)
```
### Getting Started
```bash
go build -o agentflow ./cmd/agentflow/
./agentflow stdio
```
## Quick Start
```bash
go build -o agentflow ./cmd/agentflow/
./agentflow stdio # MCP Mode
```
Integrate with Claude Code's `.claude.json`:
```json
{
"mcpServers": {
"agentflow": {
"command": "./agentflow",
"args": ["stdio"],
"type": "stdio"
}
}
}
```
### Testing
```bash
go test ./pkg/...
go run ./smoke/mcp_comm_check.go
```
## Engineering Structure
```
pkg/
engine/ ← Core Engine (State Machine, DAG, Worker, SQLite)
engine.go — State Machine + CRUD
dag.go — DAG Type + CRUD + Report
worker.go — Worker Type + CRUD + State
project.go — Project-level Queries (next_tasks, blockers)
batch.go — Batch Create Task
flowchart.go — Mermaid Flowchart
store.go — SQLite Persistence
store_dag_worker.go — DAG/Worker Persistence
server/ ← MCP Protocol Layer
mcp.go — Tool Registration + Request Dispatch
handlers_ext.go — All MCP Handlers
sync.go — Hub Sync Interface
```
## Results
*Two-hour complete project research consumes only ~160,000 tokens, Leader remains clear-sighted.*
In a simulated project (Diary CLI) test:
| Metric | Result |
|------|------|
| Create DAG | 1 call |
| Register Worker | 3 calls |
| Create Task (with dependencies) | 1 batch call / 3 tasks |
| Execute + review + pass complete cycle | ~30 seconds |
| Cross-DAG Worker Conflict Detection | Automatic |
| Mermaid Visualization | One dag_flowchart call |
## License
MIT
