omnirun

v1.3.0

Published

6 months ago

Universal project runner for students & beginners. Detects and runs any framework without memorizing commands. Supports 22+ frameworks across Node.js, Python, Flutter, Docker, and Monorepos.

🚀 OmniRun

Stop memorizing commands. Start building.

OmniRun is designed for developers who are learning and exploring new technologies. Whether you're following a tutorial, trying a new framework, or just cloned a project from GitHub — just type omnirun and it figures out the rest.

Perfect for:

🎓 Students learning web development
👨‍💻 Bootcamp graduates exploring new frameworks
🚀 Junior developers joining new codebases
📚 Anyone following tutorials across different technologies
🔄 Developers switching between multiple projects daily

✨ Why OmniRun?

The Learning Problem

Day 1: React tutorial     → npm start? npm run dev? yarn start?
Day 2: Next.js project    → npm run dev? next dev? 
Day 3: Python FastAPI     → python app.py? uvicorn? flask run?
Day 4: Docker project     → docker build? docker-compose up?
Day 5: Monorepo clone     → nx serve? turbo run? pnpm run -r?

The OmniRun Solution

Every project, every time:
$ omnirun
✅ It just works.

✨ Features

🎯 22 Detection Modes: Node.js, Python, Flutter, Docker, Monorepos
🧠 Zero Configuration: Just omnirun — no setup, no config files
📚 Learning Mode: Use --explain to understand what's happening
🔧 Smart Fixes: Detects missing dependencies and offers to fix them
💬 Interactive: Asks before making changes, explains what it's doing
🎨 Clear Output: Color-coded messages you can actually understand

🏁 Quick Start

Installation

npm install -g omnirun

Or try it without installing:

npx omnirun

Basic Usage

Navigate to any project directory and run:

omnirun

That's it! OmniRun will:

🔍 Detect your project type (Next.js, Python, Flutter, Docker, etc.)
🔧 Check for issues (missing dependencies, etc.)
▶️ Run the appropriate command

Learning Mode

Want to understand what's happening?

omnirun --explain

This shows you:

✅ What type of project was detected
📊 How confident OmniRun is (percentage)
🎯 Why it chose that detection
📝 What command it will run

Perfect for learning! See how different projects are structured and what makes them unique.

Command Line Options

omnirun [directory] [options]

Options:
  -d, --dry-run     Show what would be executed without running it
  -e, --explain     Show detailed explanation of detection
  -s, --select      Interactively select from multiple detections
  -v, --verbose     Show verbose output
  -y, --yes         Auto-confirm all prompts
  --no-fix          Skip automatic fixes
  -V, --version     Output the version number
  -h, --help        Display help for command

Real-World Examples

# Following a tutorial? Just cloned a repo?
cd my-new-project
omnirun

# Want to understand what's happening? (Learning mode!)
omnirun --explain

# Not sure if it will work? (Safe mode - shows plan but doesn't execute)
omnirun --dry-run

# See everything (Great for debugging)
omnirun --verbose

# Working on a specific project
omnirun ~/path/to/my-project

# Skip confirmation prompts (for automation)
omnirun --yes

👋 New to Development?

OmniRun is made for you! Here's how to use it:

Scenario 1: Following a Tutorial

# Tutorial says: "Clone this repo and run it"
git clone https://github.com/someone/cool-tutorial
cd cool-tutorial
omnirun --explain          # Learn what type of project it is
omnirun                    # Run it!

Scenario 2: Trying Multiple Frameworks

# Monday: Learning React
cd my-react-app
omnirun                    # Runs: npm run dev

# Tuesday: Trying Next.js
cd my-nextjs-app
omnirun                    # Runs: npm run dev

# Wednesday: Exploring Python
cd my-fastapi-app
omnirun                    # Runs: uvicorn main:app --reload

# Thursday: Flutter time
cd my-flutter-app
omnirun                    # Runs: flutter run

# Friday: Docker project
cd my-docker-app
omnirun                    # Runs: docker compose up

No need to remember different commands for different technologies!

Scenario 3: Joining a Team Project

# First day at new job/bootcamp
git clone <team-repo>
cd team-repo
omnirun --explain          # Understand the project
omnirun                    # Start working!

✨ Phase 5 Features (v1.3) - Plugin API & Community Ecosystem ✨ Current

Plugin System

🔌 Custom Detectors: Create and share your own framework detectors
📦 npm Integration: Install plugins via npm install omnirun-plugin-rust
📁 Local Development: Test plugins from local file paths
⚙️ Configuration: Manage plugins with .omnirunrc.json
🎯 Type-Safe API: Full TypeScript support for plugin development
🔄 Lifecycle Hooks: Optional init/cleanup methods
✅ Validation: Automatic plugin validation and error handling

Community

📚 Plugin Guide: Complete guide for building custom detectors
🤝 Contributing: Clear guidelines for community contributions
🎓 Examples: Reference implementation (Rust detector)
🌐 Ecosystem Ready: Foundation for community-driven expansion

Getting Started with Plugins:

# Install a plugin
npm install omnirun-plugin-rust

# Configure in .omnirunrc.json
{
  "plugins": {
    "omnirun-plugin-rust": { "enabled": true }
  }
}

# Run as normal
omnirun

See PLUGIN_GUIDE.md for creating your own plugins!

✨ Phase 4 Features (v1.2) - Docker & Monorepo Support

Docker Support

🐳 Dockerfile detection: Auto-generates image names and build commands
🎼 docker-compose.yml support: Detects multi-service setups
📦 Service extraction: Identifies all services in compose files
🔧 Smart commands: docker build or docker compose up based on project structure

Monorepo Support

📦 Nx Workspaces: Auto-detect apps and generate nx serve commands
⚡ Turborepo: Supports turbo run dev for all packages
🔗 PNPM Workspaces: Recursive package execution with pnpm run -r
🧶 Yarn Workspaces: Multi-package support via yarn workspaces foreach
📋 npm Workspaces: Native npm workspace detection
🦄 Lerna: Legacy monorepo tool support
🎯 Smart selection: Always suggests --select for choosing specific apps/packages

✨ Phase 3 Features (v1.1) - Cross-Language Support

Python Support

🐍 Auto-detect Python frameworks: Streamlit, FastAPI, Flask, Django
📦 Virtual environment detection: venv, pipenv, poetry, conda
📄 Dependency file support: requirements.txt, pyproject.toml, Pipfile
🎯 Smart entry point detection: main.py, app.py, manage.py

Flutter Support

📱 Platform detection: Android, iOS, Web
📦 pubspec.yaml validation
🎯 Target-specific commands: Auto-selects chrome for web-only projects
⚡ Hot reload ready: Uses flutter run with proper device targeting

✨ Phase 2 Features (Beta)

Smart Fixes

🔍 Auto-detect Issues: Finds missing dependencies, port conflicts, environment files
🔧 One-Click Fixes: Interactive prompts to fix issues before running
🎯 Smart Suggestions: Suggests alternative ports, config generation, and more

Enhanced Confidence System

📊 Weighted Scoring: Multi-factor analysis for better detection accuracy
🎚️ Confidence Levels: Very High, High, Medium, Low indicators
🔄 Adaptive Detection: Learns from project structure patterns

Better UX

💬 Interactive Prompts: Confirm fixes before applying
🎨 Progress Indicators: Spinners for long-running operations
🎯 Selection Mode: Choose from multiple detection results (--select)
⚡ Auto-confirm Mode: Skip prompts with --yes flag

🎯 Supported Projects

Node.js Web Frameworks

✅ Next.js
✅ Vite
✅ Create React App
✅ Angular
✅ Vue CLI

Node.js API Frameworks

✅ Express
✅ Fastify
✅ Koa
✅ NestJS
✅ Hapi

Python Frameworks

✅ Streamlit (data apps)
✅ FastAPI (modern APIs)
✅ Flask (web apps)
✅ Django (full-stack)

Mobile & Cross-Platform

✅ Flutter (iOS, Android, Web)

Docker & Containers ✨ New in v1.2

✅ Dockerfile projects
✅ docker-compose (multi-service)

Monorepos ✨ New in v1.2

✅ Nx Workspaces
✅ Turborepo
✅ PNPM Workspaces
✅ Yarn Workspaces
✅ npm Workspaces
✅ Lerna

🛠️ Development

Prerequisites

Node.js >= 18.0.0
npm, yarn, pnpm, or bun

Setup

# Clone the repository
git clone <repository-url>
cd omnirun

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

Project Structure

/omnirun
 ├── src
 │   ├── cli/           # CLI entry point
 │   ├── core/          # Core orchestration logic
 │   ├── detectors/     # Framework detectors
 │   ├── utils/         # Utility helpers
 │   ├── types/         # TypeScript definitions
 │   └── tests/         # Tests and fixtures
 ├── package.json
 ├── tsconfig.json
 └── README.md

🎓 For Educators & Bootcamps

OmniRun is perfect for coding education:

Reduce Setup Time: Students spend less time on tooling, more on learning
Universal Command: One command works across your entire curriculum
Learning Tool: --explain mode teaches project structure recognition
Fewer Support Questions: No more "how do I run this?" in office hours

Quick Integration

Add to your course materials:

## Running Your Project

Instead of remembering different commands, just use:
```bash
omnirun

Works for all course projects!


---

## 📋 Roadmap

- [x] **Phase 1**: MVP with Node.js support (v1.0-alpha)
- [x] **Phase 2**: Smart fixes & confidence system (v1.0-beta)
- [x] **Phase 3**: Python & Flutter support (v1.1)
- [x] **Phase 4**: Docker & Monorepo support (v1.2)
- [x] **Phase 5**: Plugin API & community ecosystem ✨ **Current** (v1.3)
- [ ] **Phase 6**: Enhanced CI/CD integration & advanced features

**Total Detection Coverage**: 22 built-in modes + unlimited via plugins (Node.js, Python, Flutter, Docker/Monorepos + Community)

**Vote for features:** [GitHub Discussions](https://github.com/your-repo/discussions)

## ❓ FAQ

### "Will this work with my project?"
Probably! OmniRun supports 22+ detection modes and is constantly adding more. Try `omnirun --dry-run` to see what it detects without running anything.

### "Is it safe to use?"
Yes! OmniRun:
- Always asks before installing dependencies
- Shows you what it will run before executing
- Never modifies your code
- Open source (Apache 2.0 license)

### "What if it doesn't detect my project?"
OmniRun will tell you it couldn't detect the project type. You can:
1. Check if your project has the necessary files (package.json, requirements.txt, Dockerfile, etc.)
2. Run with `--verbose` to see what it's looking for
3. Open an issue — we're always adding new framework support!

### "Do I need to learn new commands?"
Nope! Just `omnirun` for basic use. The flags (`--explain`, `--dry-run`, etc.) are optional extras.

### "Can I use this in production?"
OmniRun is designed for development environments. For production, use explicit commands in your deployment scripts.

---

## 🤝 Contributing

We welcome contributions! Especially:
- **New detectors**: Build a plugin! See [PLUGIN_GUIDE.md](./PLUGIN_GUIDE.md)
- **Built-in detectors**: For widely-used frameworks (see [CONTRIBUTING.md](./CONTRIBUTING.md))
- **Better error messages**: Help beginners understand what's happening
- **Documentation**: Improve guides, fix typos, add examples
- **Bug reports**: Help us improve reliability

**Read our guides:**
- [CONTRIBUTING.md](./CONTRIBUTING.md) - How to contribute to OmniRun
- [PLUGIN_GUIDE.md](./PLUGIN_GUIDE.md) - How to create plugins

**Creating a Plugin?**
Start with our example: [examples/plugins/rust-detector/](./examples/plugins/rust-detector/)

## 📄 License

Apache-2.0 - see [LICENSE](LICENSE) for details.

Copyright © 2025 MadeByTatwa LLC

## 🙏 Acknowledgments

Built with:
- [Commander](https://github.com/tj/commander.js) - CLI framework
- [execa](https://github.com/sindresorhus/execa) - Process execution
- [fast-glob](https://github.com/mrmlnc/fast-glob) - File pattern matching
- [picocolors](https://github.com/alexeyraspopov/picocolors) - Terminal colors

---

## 💙 Built for Learners, by Developers

OmniRun was created to solve a real problem: the overwhelming number of commands across different technologies makes learning harder than it should be. We believe that tooling should help you learn, not get in your way.

**Our mission:** Every student, every developer, every learner should be able to `git clone` any project and just run it — without needing to hunt through documentation for the right command.

---

**Current Version**: v1.3.0  
**Built-in Detection Modes**: 22 across 4 ecosystems  
**Plugin Support**: ✅ Unlimited community detectors  
**License**: Apache-2.0

Made with ❤️ by MadeByTatwa, LLC

**Star us on GitHub!** ⭐ Help other learners discover OmniRun.