VibeFlow - Workflow Visualization & Debugging CLI

A CLI tool for visualizing, debugging, and tracing Cloudflare Workflows. Connect to any codebase and instantly see your workflows as interactive diagrams.

``bash
npx vibeflow init ./src/workflows
npx vibeflow dev
`

Architecture

`
┌─────────────────────────────────────────────────────────────────┐
│ VIBEFLOW │
│ AI-Powered Workflow Visualization Platform │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Frontend (React + XYFlow) ──▶ Backend (Bun) ──▶ Cloudflare │
│ vibeflow_ui/ src/server.ts Workflows │
│ - Flow visualization - REST API src/workflows/
│ - WebSocket logs - AI generation │
│ - VSCode integration - Wrangler mgmt │
│ │
└─────────────────────────────────────────────────────────────────┘
`

$3

| Layer | Stack |
|-------|-------|
| Runtime | Bun 1.3.5+ |
| Frontend | React 19, XYFlow, Tailwind 4 |
| Backend | Bun.serve() with WebSocket |
| AI | Claude Haiku 4.5 (Anthropic SDK) |
| Workflows | Cloudflare Workers |
| Types | TypeScript 5.9 |

$3

- AI Visualization: TypeScript workflow code → ReactFlow JSON via Claude Haiku
- Live Execution: Run workflows locally with real-time log streaming
- Source Navigation: Click nodes to open source files in VSCode
- Interactive UI: Pan, zoom, and explore workflow graphs

Overview

This project demonstrates a complete Cloudflare Workflows setup with:

- 6-step workflow pipeline: Webhook receiver → Context fetcher → LLM analyzer → Tool executor → LLM evaluator → Response sender
- WhatsApp integration: Receives webhook messages, processes them, and sends responses
- Mocked AI services: Image generation, video generation, and LLM analysis (all simulated locally)
- Type-safe TypeScript: Strict typing throughout with comprehensive interfaces
- Bun-native: Uses Bun for runtime, testing, and package management

Project Structure

`
vibeflow/
├── src/
│ ├── index.ts # Main entry point with fetch handler
│ ├── workflows/
│ │ └── whatsapp-processor.ts # Main workflow orchestration
│ ├── steps/ # Individual workflow steps
│ │ ├── webhook-receiver.ts
│ │ ├── context-fetcher.ts
│ │ ├── llm-analyzer.ts
│ │ ├── tool-executor.ts
│ │ ├── llm-evaluator.ts
│ │ └── response-sender.ts
│ ├── types/ # TypeScript type definitions
│ ├── mocks/ # Mocked external services
│ └── env.d.ts # Environment type definitions
├── test/
│ ├── fixtures/ # Sample webhook payloads
│ └── steps/ # Unit tests
├── wrangler.toml # Cloudflare configuration
└── package.json
`

Installation

`bash
bun install
`

Development

Start the local Cloudflare Workers development server:

`bash
bun run dev
`

This starts the workflow on http://localhost:8787 with hot reloading enabled.

Testing the Workflow

$3

`bash
curl "http://localhost:8787/webhook/whatsapp?hub.mode=subscribe&hub.verify_token=vibeflow_verify_token&hub.challenge=test123"
`

$3

`bash
curl -X POST http://localhost:8787/webhook/whatsapp \
-H "Content-Type: application/json" \
-d @test/fixtures/text-message.json
`

$3

`bash
curl -X POST http://localhost:8787/webhook/whatsapp \
-H "Content-Type: application/json" \
-d @test/fixtures/image-request.json
`

$3

`bash
curl -X POST http://localhost:8787/webhook/whatsapp \
-H "Content-Type: application/json" \
-d @test/fixtures/video-request.json
`

$3

`bash


Use the instanceId returned from the POST request


curl http://localhost:8787/workflow/status/{instanceId}
`

Workflow Pipeline

1. Webhook Receiver - Validates and extracts message data
2. Context Fetcher - Retrieves conversation history (mocked)
3. LLM Analyzer - Analyzes intent and determines if tools are needed (mocked)
4. Tool Executor - Generates images/videos if requested (mocked, conditional)
5. LLM Evaluator - Evaluates results and creates final message (mocked)
6. Response Sender - Sends response back via WhatsApp (mocked)

Running Tests

`bash


Run all tests

bun test

Run tests in watch mode

bun run test:watch
`

API Endpoints

- GET /webhook/whatsapp - WhatsApp webhook verification
- POST /webhook/whatsapp - Receive WhatsApp messages (triggers workflow)
- GET /workflow/status/:id - Check workflow instance status
- GET / - API information

Mock Services

All external services are mocked for local development:

- WhatsApp API: Simulated send/receive with rate limiting
- LLM Analysis: Intent detection based on keywords
- Image Generation: Returns placeholder images (3-5s delay)
- Video Generation: Returns sample video (5-10s delay)

Workflow Configuration

Each step has specific retry and timeout policies:

| Step | Retries | Backoff | Timeout |
|------|---------|---------|---------|
| webhook-receiver | 0 | - | - |
| context-fetcher | 3 | exponential | 30s |
| llm-analyzer | 2 | exponential | 60s |
| tool-executor | 1 | exponential | 5min |
| llm-evaluator | 2 | exponential | 60s |
| response-sender | 3 | exponential | 30s |

Technologies

- Runtime: Bun v1.3.5+
- Framework: Cloudflare Workflows
- Language: TypeScript 5+
- Testing: bun:test
- Development: Wrangler 4.54+

Deployment

`bash


Generate type definitions

bun run types

Deploy to Cloudflare Workers

bun run deploy
`

CLI Commands (Planned)

`bash


Initialize vibeflow for an existing project

vibeflow init /path/to/workflows
→ Scans for workflow patterns
→ Generates vibeflow.config.ts
→ Creates workflow visualizations

Start development server + UI

vibeflow dev [--workflow ] [--port 3001]
→ Starts wrangler dev
→ Launches visualization UI
→ Streams logs with tracing

Generate/regenerate visualization

vibeflow generate [--workflow ] [--all]
→ AI-powered flow generation
→ Validates structure

List discovered workflows

vibeflow list
→ Shows all workflows with metadata

Validate workflow structure

vibeflow validate [--workflow ]
→ Checks imports resolve
→ Verifies step implementations
`

$3

`typescript
export default {
workflowsDir: "./src/workflows",
stepsDir: "./src/steps",
port: 3001,
wranglerConfig: "./wrangler.toml",
tracing: {
enabled: true,
captureInputs: true,
captureOutputs: true,
}
}
`

---

Workflow Development Pain Points (Why This Tool Exists)

$3

- Silent step failures with no centralized error tracking
- Console.log disappears after execution
- Can't see which step is running during long operations
- No request tracing across steps

$3

- Complex decisions buried in step functions
- No visualization of decision trees
- Unclear why workflow terminated early

$3

- No execution metrics per step
- Can't identify bottleneck steps

$3

- No unified error response format
- Retry behavior is invisible

---

DX Features Roadmap

$3

- [ ] vibeflow init - Project scanning & config generation
- [ ] vibeflow dev - Server + wrangler integration
- [ ] vibeflow list - Workflow discovery
- [ ] Bundle UI with CLI

$3

- [ ] Step execution timeline visualization
- [ ] Decision path visualization
- [ ] State snapshots (input/output per step)
- [ ] trace() wrapper for opt-in rich tracing

`typescript
import { trace } from 'vibeflow/trace';
const result = await trace(step.do("my-step", () => myFunction()));
`

$3

- [ ] Error reconstruction with breadcrumbs
- [ ] Performance profiler
- [ ] Replay mode (re-run with captured inputs)

$3

- [ ] Workflow composition (chain workflows)
- [ ] Workflow templates
- [ ] Hot reload for steps

---

Future Vision: SaaS Platform

`
vibeflow.dev/github/username/repo
`

- GitHub Integration: Connect repos, auto-detect workflows, generate on push
- Hosted Visualization: Share diagrams via URL, embed in docs
- Cloud Execution: Trigger workflows from UI, view traces
- Analytics: Execution metrics, error rates, performance trends

`
┌─────────────────────────────────────────────────────────────┐
│ vibeflow.dev (SaaS) │
├─────────────────────────────────────────────────────────────┤
│ GitHub App → Worker (Clone & Parse) → D1 (Metadata) │
│ ↓ │
│ R2 (Generated Assets) │
│ ↓ │
│ Pages (Hosted UI) │
└─────────────────────────────────────────────────────────────┘
`

---

Current Limitations

- Mock Services: LLM analysis, image/video generation, and WhatsApp API are mocked
- No Authentication: API endpoints are currently unprotected
- In-Memory Storage: Rate limiting and conversation data lost on restart
- Read-Only Visualization: Workflow graphs generated from code, not editable in UI

---

Project created using Bun

This project was created using bun init` and follows Bun best practices. Bun is a fast all-in-one JavaScript runtime.

The error indicates your npm access token has expired. You need to log in again:

npm login
After logging in, run the publish command again:

bun run publish:patch
Note: Since the version was already bumped to 0.3.0, you may want to publish directly without bumping again:

npm publish --access public