Cloudflare Workflows development tool
npm install @bruslan/vibeflowA 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
``
┌─────────────────────────────────────────────────────────────────┐
│ 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 │
│ │
└─────────────────────────────────────────────────────────────────┘
| 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 |
- 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
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
``
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
`bash`
bun install
Start the local Cloudflare Workers development server:
`bash`
bun run dev
This starts the workflow on http://localhost:8787 with hot reloading enabled.
`bash`
curl "http://localhost:8787/webhook/whatsapp?hub.mode=subscribe&hub.verify_token=vibeflow_verify_token&hub.challenge=test123"
`bash`
curl -X POST http://localhost:8787/webhook/whatsapp \
-H "Content-Type: application/json" \
-d @test/fixtures/text-message.json
`bash`
curl -X POST http://localhost:8787/webhook/whatsapp \
-H "Content-Type: application/json" \
-d @test/fixtures/image-request.json
`bash`
curl -X POST http://localhost:8787/webhook/whatsapp \
-H "Content-Type: application/json" \
-d @test/fixtures/video-request.json
`bash`Use the instanceId returned from the POST request
curl http://localhost:8787/workflow/status/{instanceId}
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)
`bashRun all tests
bun test
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 informationMock 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 typesDeploy 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 visualizationsStart development server + UI
vibeflow dev [--workflow ] [--port 3001]
→ Starts wrangler dev
→ Launches visualization UI
→ Streams logs with tracingGenerate/regenerate visualization
vibeflow generate [--workflow ] [--all]
→ AI-powered flow generation
→ Validates structureList discovered workflows
vibeflow list
→ Shows all workflows with metadataValidate 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