# OpenFlow
<div align="center">
<h3>Stop AI from wasting your time</h3>
<p>Real case: Claude Code ran 234 web searches, wasted 45 minutes. OpenFlow prevents this.</p>
</div>
---
<div align="center">
<strong>Before OpenFlow:</strong> AI tasks run unpredictably (5 min or 45 min?)<br/>
<strong>With OpenFlow:</strong> Guaranteed completion time, controlled resource usage
</div>
# 🎯 The Problem
**Last week, a developer asked Claude Code to "research AI trends".**
What happened:
- 🔍 234 web searches (should have been 10)
- ⏱️ 45 minutes wasted (should have been 2 minutes)
- 💰 $47 in API costs (should have been $2)
- ❌ No way to stop it
**This happens more often than you think.** AI agents get stuck in loops, read entire codebases, or recurse infinitely through dependencies.
# ✅ The Solution
OpenFlow prevents runaway AI tasks with strict resource limits:
| Without OpenFlow | With OpenFlow |
| ---------------------- | ---------------------- |
| ❌ 234 searches, 45 min | ✅ Max 10 searches, 60s |
| ❌ Reads entire project | ✅ Max 20 files, 45s |
| ❌ Infinite recursion | ✅ Max 3 levels, 30s |
| ❌ No visibility | ✅ Real-time progress |
| ❌ Can't stop | ✅ Auto-stops at limits |
# 🤖 LLM Quickstart
1. Direct your favorite coding agent (Claude Code, Codex, etc) to [SKILL.md](skills/SKILL.md)
2. Prompt away!
> **Note:** Skills are supported by Claude Code and Codex. For other agents, use the CLI directly.
# 👋 Human Quickstart
**1. Install OpenFlow (Python>=3.10):**
```bash
curl -fsSL https://raw.githubusercontent.com/Done-0/openflow/main/scripts/install.sh | bash
```
**2. Install the Skill (for Claude Code):**
For Claude Code, install the skill to enable AI-assisted flow execution:
```bash
npx skills add https://github.com/Done-0/openflow
```
Or manually:
```bash
mkdir -p ~/.claude/skills/openflow
curl -o ~/.claude/skills/openflow/SKILL.md \
https://raw.githubusercontent.com/Done-0/openflow/main/skills/SKILL.md
```
**How it works:**
- The skill enables Claude Code to discover and use OpenFlow automatically
- When you ask "Search the web for AI trends", Claude reads the skill and invokes `openflow run search_web`
- The CLI and skill are separate - the skill controls the CLI
**3. Run your first flow:**
```bash
openflow run search_web --input '{"topic": "AI trends"}'
```
**4. See the difference:**
```
[OpenFlow] Execution Plan
━━━━━━━━━━━━━━━━━━━━━━━━
Steps: 4 steps, est. 45s
Resource limits: max 10 searches, 60s timeout
━━━━━━━━━━━━━━━━━━━━━━━━
[OpenFlow] Progress
✓ Search information 10.2s (used 10/10 searches)
✓ Analyze sources 12.1s
✓ Compare findings 9.8s
✓ Generate report 7.3s
[OpenFlow] Completed in 39.4s
✓ Task completed within limits
✓ Prevented runaway execution
```
# 🚀 Available Flows
### search_web
**Prevents:** 234+ searches taking 45 minutes
Search the web with hard limits (max 10 searches, 60s timeout). Uses DuckDuckGo Instant Answer API (free) or Brave Search API (set `BRAVE_API_KEY` for better results).
```bash
openflow run search_web --input '{"topic": "AI trends"}'
```
### explore_codebase
**Prevents:** Reading entire project and exhausting tokens
Explore large codebases with file limits (max 20 files, 45s timeout).
```bash
openflow run explore_codebase --input '{"query": "authentication logic", "path": "."}'
```
### check_dependencies
**Prevents:** Infinite recursion through dependency tree
Check dependencies with depth limits (max 50 dependencies, 30s timeout). Supports npm, pip, poetry, cargo, go, bundler.
```bash
openflow run check_dependencies --input '{"path": "."}'
```
# 💻 CLI Commands
```bash
# List available flows
openflow list
# Show flow details
openflow info search_web
# Run a flow
openflow run search_web --input '{"topic": "AI trends"}'
# Run with custom limits
openflow run search_web \
--input '{"topic": "AI trends"}' \
--max-time 60 \
--max-calls 10
```
# 📊 Why Developers Use OpenFlow
**You need OpenFlow if you've ever:**
- ✅ Waited 30+ minutes for an AI task to complete
- ✅ Wondered "is it stuck or still working?"
- ✅ Hit API rate limits from excessive calls
- ✅ Paid unexpected API bills from runaway tasks
- ✅ Had to kill Claude Code because it wouldn't stop
**You especially need OpenFlow if you:**
- Work with large codebases (> 1000 files)
- Use AI for research tasks (web searches)
- Run AI tasks in CI/CD pipelines
- Share AI tools with your team
# 🎬 See It In Action
**Without OpenFlow:**
```bash
# Ask Claude Code: "Search the web for top 50 AI tools"
# Result: 100+ searches, 20+ minutes, $20 in API costs
```
**With OpenFlow:**
```bash
openflow run search_web --input '{"topic": "top 50 AI tools"}'
# Result: 10 searches, 60 seconds, $2 in API costs
```
**The difference:**
- ⏱️ 20 minutes → 60 seconds (20x faster)
- 🔍 100+ searches → 10 searches (10x fewer)
- 💰 $20 → $2 (10x cheaper)
# 🤝 Contributing
We welcome contributions! Please visit [GitHub Issues](https://github.com/Done-0/openflow/issues) to report bugs or suggest features.
# 📄 License
MIT License - see [LICENSE](LICENSE)