Buildflow
Turn interesting links into working code. Browser extension + Telegram bot that sends URLs to OpenCode for automated research and implementation.
Install / Use
/learn @BowTiedSwan/BuildflowREADME
🔨 BuildFlow
Turn interesting links into working code. A browser extension + Telegram bot that sends URLs and X/Twitter posts to OpenCode for automated research, implementation, and report generation.
Found an interesting tutorial? Click a button. See a cool project on X? One click. BuildFlow sends it to OpenCode, which researches, implements key examples, runs tests, and generates a comprehensive report.
What It Does
┌──────────────────────────────────────────────────────────────────┐
│ YOU DISCOVER │
│ │
│ 📄 Interesting article 🐦 Cool X post 📦 GitHub repo │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ ONE CLICK │
│ │
│ 🔘 Browser extension popup 🔨 Button on X tweets │
│ 📱 Send URL to Telegram bot │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ OPENCODE WORKS │
│ │
│ 📖 Reads the content │
│ 💡 Identifies key concepts │
│ 🛠️ Implements examples │
│ 🧪 Runs tests │
│ 📝 Generates report │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ YOU GET │
│ │
│ research/ │
│ └── project-name-abc123/ │
│ ├── REPORT.md # What it is, how it works │
│ ├── src/ # Working implementation │
│ └── repo/ # Cloned repositories │
└──────────────────────────────────────────────────────────────────┘
Architecture
┌─────────────────────┐ ┌─────────────────────┐
│ Chrome Extension │ │ Telegram Bot │
│ │ │ │
│ • Popup button │ │ • Send any URL │
│ • X.com injection │ │ • /status command │
│ (🔨 on tweets) │ │ • /history command │
└──────────┬──────────┘ └──────────┬──────────┘
│ │
│ POST /api/learn │
└─────────────┬─────────────┘
▼
┌─────────────────────────┐
│ Backend Server │
│ (localhost:3456) │
│ │
│ • Express API │
│ • SQLite history │
│ • Session polling │
│ • Notifications │
└─────────────┬───────────┘
│
▼
┌─────────────────────────┐
│ OpenCode Server │
│ (localhost:4096) │
│ │
│ • Creates session │
│ • Runs research agent │
│ • Generates output │
└─────────────┬───────────┘
│
▼
┌─────────────────────────┐
│ ./research/[slug]/ │
│ │
│ REPORT.md │
│ src/ │
│ repo/ │
└─────────────────────────┘
Packages
| Package | Description |
|---------|-------------|
| @build-learn/shared | Shared types, prompt templates, utilities |
| @build-learn/chrome-extension | Chrome Extension (Manifest V3) |
| @build-learn/telegram-bot | Telegram bot (Telegraf) |
| @build-learn/backend | Express server with SQLite |
Prerequisites
- Node.js 20+
- pnpm 9+
- OpenCode - AI-powered coding assistant (required)
- Sisyphus Agent - Enhanced agentic experience (recommended)
- Telegram Bot Token (optional, for Telegram integration)
Installing OpenCode
OpenCode is the core AI engine that powers BuildFlow's research capabilities.
# Install OpenCode
curl -fsSL https://opencode.ai/install | bash
# Or via npm
npm install -g opencode
After installation, configure your AI provider (Anthropic, OpenAI, etc.) by running opencode and following the setup prompts.
For more details, visit opencode.ai.
Installing Sisyphus Agent (Recommended)
For the best agentic experience, install the Sisyphus agent from oh-my-opencode. Sisyphus provides enhanced orchestration capabilities, parallel task execution, and smarter delegation patterns.
# Clone oh-my-opencode
git clone https://github.com/code-yeongyu/oh-my-opencode.git ~/.opencode/oh-my-opencode
# The agent files will be available in your OpenCode configuration
Visit the oh-my-opencode repository for detailed setup instructions and available agents.
Installation
1. Clone and install
git clone https://github.com/BowTiedSwan/buildflow.git
cd buildflow
pnpm install
2. Build all packages
pnpm build
3. Configure environment
cp .env.example .env
Edit .env:
# Required for Telegram bot (optional feature)
TELEGRAM_BOT_TOKEN=your_token_from_botfather
# OpenCode server URL (default works if running locally)
OPENCODE_URL=http://localhost:4096
# Backend port
PORT=3456
Running
Step 1: Start OpenCode
OpenCode must be running for research to work. Start it in the directory where you want research outputs:
cd ~/my-research-workspace
opencode serve --port 4096
Or run the full TUI (includes server):
cd ~/my-research-workspace
opencode
Important: Research outputs (
./research/[slug]/) are created relative to OpenCode's working directory.
⚠️ Multiple OpenCode Instances: If you have multiple OpenCode TUI windows open, only ONE can serve port 4096. Sessions created via the API will be bound to whichever instance owns the port. For best results, use a single dedicated OpenCode instance for BuildFlow. See Troubleshooting if sessions don't appear.
Step 2: Start the Backend
pnpm backend
You should see:
🚀 BuildFlow Backend
========================
📡 Server: http://localhost:3456
🔗 OpenCode: http://localhost:4096
Endpoints:
GET /api/health - Health check
POST /api/learn - Start new research
GET /api/learn - List research sessions
GET /api/learn/:id - Get session details
Step 3: Load Chrome Extension
- Open
chrome://extensions - Enable Developer mode (top right)
- Click Load unpacked
- Select
packages/chrome-extension/dist/
Step 4: Start Telegram Bot (optional)
pnpm bot
Usage
Chrome Extension - Any Website
- Navigate to any webpage (article, tutorial, GitHub repo)
- Click the BuildFlow extension icon
- Click "Research & Build"
- Check OpenCode for progress
Chrome Extension - X/Twitter
- Browse X.com (twitter.com)
- Find an interesting tweet
- Click the 🔨 button next to the tweet's timestamp
- The tweet text and any URLs are sent for research
Telegram Bot
- Start a chat with your bot
- Send any URL:
https://example.com/interesting-article - Or forward/paste an X post URL
- Bot confirms and notifies when complete
Commands:
/start- Welcome message/status- Check if backend is running/history- View recent research sessions
Research Output
Each research task creates a folder:
research/
└── article-title-abc123/
├── REPORT.md # Comprehensive report
│ ├── Summary
│ ├── Key Concepts
│ ├── Implementation Details
│ ├── Test Results
│ ├── Applications
│ └── Assessment
│
├── src/ # Implemented examples
│ └── example.ts
│
└── repo/ # Cloned repositories (if applicable)
└── cloned-repo/
Sample REPORT.md
# Research Report: React Server Components Guide
## Summary
A comprehensive guide to React Server Components, explaining the
mental model, use cases, and implementation patterns.
## Key Concepts
- Server Components run only on the server
- Client Components are marked with "use client"
- Data fetching happens at the component level
## Implementation Details
### What I Built
A demo app showing server/client component interaction.
### Key Files
- `src/app/page.tsx` - Server component with data fetching
- `src/components/Counter.tsx` - Client component with state
### How to Run
cd src && npm install && npm run dev
## Test Results
- [x] Server component renders correctly
- [x] Client component hydrates properly
- [ ] Streaming not tested (requires specific setup)
## Assessment
**Quality:** ⭐⭐⭐⭐⭐
**Usefulness:** ⭐⭐⭐⭐
**Recommendation:** Essential reading for React developers
