AgentFlow is a lightweight observability layer for OpenCode agent workflows. It captures every tool invocation — task delegations, file edits, shell commands — and surfaces a real-time, structured trace through a browser dashboard.

No database. No external services. One Bun process, file-based storage, live SSE streaming.

Why AgentFlow?

When running multi-agent OpenCode sessions, understanding what happened and why becomes critical. AgentFlow answers:

• What did each agent do? — Hierarchical task tree of every invocation
• How long did it take? — Chronological timeline with durations
• Who delegated to whom? — Agent dependency graph with critical path analysis
• What evidence supports each step? — Raw inputs, outputs, and errors per trace node

Features

• ⚡ Real-time capture — Zero-dependency OpenCode plugin writes every tool event (task, bash, write, edit) to append-only JSONL files as they execute
• 🔄 Live SSE streaming — Two modes: raw event firehose by session, or typed PatchEnvelope events by run with sequence-based replay (after=N)
• 🌳 Trace engine — In-process pipeline normalizes raw events into structured RunSnapshot records: a task tree (TraceNode[]), a chronological log (TimelineItem[]), and an agent dependency graph (SessionGraph)
• 📊 Dashboard UI — React 18 + ReactFlow + Tailwind with three panels: Work Trace (tree/graph toggle), Evidence Panel, and Timeline
• 🧩 Critical path analysis — Computes the longest-duration chain through the agent graph, highlighting bottlenecks
• 🔌 Zero external dependencies — Bun native HTTP, no Express, no Redis, no Postgres. Everything is file-based (JSONL + JSON snapshots)
• 📁 File-based persistence — Runs, snapshots, and patches stored as plain JSON/JSONL in .agentflow/runs/. Raw events are always the source of truth

Quick Start

# Install
npm install @sferralove/agentflow

# Initialize — creates .agentflow/ + copies plugin to OpenCode
npx agentflow init

# Build TypeScript + dashboard
npm run build

# Start server (default :3001)
npx agentflow serve

# Open the dashboard
open http://localhost:3001

With the plugin enabled in OpenCode, every agent session emits events that appear live on the dashboard — no configuration required.

Requirements

• Bun ≥ 1.2.0 (required runtime — Node.js is not supported)
• OpenCode ≥ 1.x (for plugin integration)
• npm (for dashboard build)

Architecture

| Layer | Responsibility | |-------|---------------| | Event normalizer | Classifies each raw AgentEvent into a semantic NormalizedEventKind (e.g. delegation.started, command.executed, file.changed) | | Trace projector | Incrementally builds a RunSnapshot — trace nodes, timeline items, and the agent graph — from the event stream. Deduplication is handled by event ID | | Run store | Persists snapshots and patch history to .agentflow/runs/{runId}/ as plain JSON/JSONL files | | SSE hub | Maintains an in-memory patch history per run and registers connected clients. Replays missed patches on connect via the after=N cursor |

All four layers run in-process with zero additional dependencies. Persistence is fire-and-forget; the event pipeline never blocks.

CLI

| Command | Description | |---------|-------------| | agentflow init | Initialize .agentflow/ directories and copy the OpenCode plugin | | agentflow serve [port] | Start the Bun HTTP server (default: 3001) | | agentflow stop | Gracefully stop the running server via PID file | | agentflow status | Check if the server is running or stopped |

API

Run-first endpoints (v1)

GET /health

Health check. Returns server status, connected SSE clients, and tracked sessions.

{ "status": "ok", "clients": 2, "sessions": 1 }

GET /api/runs/current

Full RunSnapshot from the in-memory projector — trace nodes, timeline, graph, raw events.

{
  "run": { "id": "run_session_1", "status": "running", ... },
  "traceNodes": [...],
  "timelineItems": [...],
  "graph": { "nodes": [...], "edges": [...] },
  "rawEvents": [...]
}

GET /api/runs

List of active runs.

{ "runs": [{ "id": "run_session_1", "status": "running", ... }] }

GET /api/runs/:runId/snapshot

Persisted RunSnapshot for a specific run ID, loaded from disk.

GET /api/stream?run=current&after=0

SSE stream of typed PatchEnvelope events. Named SSE events per patch type:

| Event Name | Payload | Trigger | |------------|---------|---------| | raw.event | AgentEvent | Every raw event ingested | | trace.node.upserted | TraceNode | Node created or status changed | | trace.node.completed | TraceNode | Node reaches completed/failed | | timeline.item.upserted | TimelineItem | Timeline entry added | | graph.node.upserted | AgentNode | Graph node created or updated | | graph.edge.upserted | AgentEdge | Graph edge created | | run.updated | Run | Run metadata changed |

event: trace.node.upserted
id: 3
data: {"id":"patch_3","runId":"run_session_1","sequence":3,"type":"trace.node.upserted","payload":{...}}

Legacy endpoints (pre-v1)

| Endpoint | Description | |----------|-------------| | GET /api/stream?session=X | SSE stream of raw JSONL events for a session | | GET /api/events?session=X&since=TS&tree=true | JSON events (all sessions when tree=true) | | GET /api/agents/X?tree=true | Agent graph with nodes and edges | | GET /api/sessions | List of available sessions |

Dashboard

The dashboard provides three integrated panels:

1. Work Trace — Hierarchical task tree of trace nodes. Each node shows status, kind, confidence, and evidence count. Toggle to AgentGraph view for the ReactFlow dependency graph with critical path highlighting.
2. Evidence Panel — Select a trace node to inspect its backing raw events: inputs, outputs, errors, and timestamps.
3. Timeline — Chronological log of all events. Click any entry to jump to the corresponding trace node.

Development mode

# Vite HMR dev server on :3000
npm -C dashboard run dev

# API server on :3001 (separate terminal)
npx agentflow serve 3001

Development

npm run build          # TypeScript + dashboard (order matters)
npm test               # Full test suite (bun:test)
npx tsc --noEmit       # TypeScript check only

Project structure

src/
  cli.ts, plugin.ts, server.ts, types.ts, index.ts
  trace/             # Trace engine (normalizer, projector, graph builder)
  run/               # Persistence (run store)
  stream/            # SSE delivery (hub)
dashboard/
  src/hooks/          # useRunTrace, useSSE
  src/components/     # AgentGraph, TraceTree, TraceEvidencePanel, TraceTimeline, Header ...
  src/utils/          # Critical path computation, timeline filtering
test/                 # 10 test files (bun:test)

License

MIT