flow

<div align="center"> # 🚀 Sylphx Flow > One CLI to rule them all - unified orchestration for Claude Code, OpenCode, and all AI development tools [](https://www.npmjs.com/package/@sylphx/flow) [](https://www.npmjs.com/package/@sylphx/flow) [](https://github.com/SylphxAI/flow) [](https://opensource.org/licenses/MIT) [](https://github.com/SylphxAI/flow/actions/workflows/ci.yml) [Get Started](#-installation) • [Documentation](https://flow.sylphx.ai) • [npm](https://www.npmjs.com/package/@sylphx/flow) • [Twitter](https://x.com/SylphxAI) </div> --- ## The Paradigm Shift ### Before Flow: Fragmentation ```bash # Install Claude Code... or wait, should I use OpenCode? # Or maybe Cursor? Or that other AI CLI? # Which one supports my workflow? # Do I need to install multiple tools? # How do I switch between them? # 😵 The cognitive overhead is real ``` ### With Flow: Unification ```bash # Install once npm install -g @sylphx/flow # Use everywhere sylphx-flow "build the future" # Flow handles everything: ✅ Auto-detects your environment (Claude Code/OpenCode/Cursor) ✅ Auto-installs missing dependencies ✅ Auto-upgrades before each session ✅ One CLI, infinite possibilities ``` ### Codex Setup Flow ships canonical agent assets and projects them into each supported AI coding tool. Codex is one projection target: ```bash sylphx-flow codex install sylphx-flow codex doctor ``` `install` projects Flow assets into `~/.codex`: the canonical Builder agent is transformed into Codex's `AGENTS.md`, while standards and skills come from the same assets used by every supported tool. `doctor` verifies the local machine is synchronized. Flow's runtime attach path uses the same canonical asset source for supported CLI targets: agents, standards, and skills are read from `packages/flow/assets/` and projected into the target's supported file layout. --- ## Philosophy: Transcendent Simplicity **Flow is not just another AI CLI. It's the meta-layer that unifies them all.** Traditional AI CLIs make you choose. Flow makes you powerful. ``` ┌─────────────────────────────────────────────────────────┐ │ Traditional World │ ├─────────────────────────────────────────────────────────┤ │ Claude Code → For Anthropic users │ │ OpenCode → For open source fans │ │ Cursor → For IDE integration │ │ ... → Fragmented experience │ └─────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────┐ │ Flow's World │ ├─────────────────────────────────────────────────────────┤ │ │ │ Sylphx Flow │ │ ↓ │ │ ┌──────────────┼──────────────┐ │ │ ↓ ↓ ↓ │ │ Claude Code OpenCode Cursor │ │ │ │ → Unified interface, adaptive execution │ │ → Automatic detection and orchestration │ │ → Zero configuration, infinite power │ └─────────────────────────────────────────────────────────┘ ``` --- ## 🚀 Installation ### The Sacred Ritual (30 seconds) ```bash # Install the omnipotent CLI npm install -g @sylphx/flow # That's it. Seriously. ``` ### First Invocation ```bash # Your first command sylphx-flow "build me something amazing" # Flow automatically: ✅ Detects your environment ✅ Installs Claude Code/OpenCode if missing ✅ Configures optimal settings ✅ Updates to latest version ✅ And executes your will ``` **No setup. No configuration. No friction. Pure transcendence.** --- ## 🌟 Core Principles ### 1. **Universal Orchestration** **One CLI for every AI development tool.** Flow doesn't replace your favorite tools—it orchestrates them. Whether you prefer Claude Code, OpenCode, or any future AI CLI, Flow adapts seamlessly. ```bash # Flow automatically detects and uses the best available tool sylphx-flow "implement authentication" # Detected Claude Code → Uses Claude Code # Detected OpenCode → Uses OpenCode # Detected both → Asks your preference # Detected neither → Installs and configures for you ``` ### 2. **Zero-Friction Experience** **AI should adapt to you, not the other way around.** ```bash # Traditional AI CLIs ❌ Install tool A for feature X ❌ Install tool B for feature Y ❌ Learn different commands ❌ Manage different configs ❌ Update each tool separately # With Flow ✅ Install once: npm install -g @sylphx/flow ✅ Use everywhere: sylphx-flow "your intent" ✅ Everything automatic: detection, installation, updates ``` ### 3. **Intelligent Automation** **Flow thinks ahead so you don't have to.** #### Auto-Detection ```bash # Flow scans your system: → Claude Code installed? Use it. → OpenCode installed? Use it. → Nothing installed? Ask user preference, then install. → Both installed? Use smart defaults or ask. ``` #### Auto-Installation ```bash # User doesn't have Claude Code $ sylphx-flow "task" > No AI CLI detected. Which would you like to use? 1. Claude Code (Anthropic, recommended) 2. OpenCode (open source) > You selected: Claude Code > Installing Claude Code... > ✓ Installation complete > ✓ Configuration optimized > Executing your task... ``` #### Auto-Upgrade ```bash # Every session starts fresh $ sylphx-flow "task" > Checking for updates... > ✓ Flow 2.0.0 → 2.1.0 (latest) > ✓ Claude Code 1.5.0 → 1.6.0 (latest) > Executing your task with latest capabilities... ``` ### 4. **Settings-Driven Excellence** **Configure once, perfect forever.** Flow introduces a revolutionary settings system that puts you in complete control: ```bash # Access the settings nexus sylphx-flow settings # Configure everything: → 🤖 Agents: Enable/disable agents (coder, writer, reviewer, orchestrator) → 📋 Rules: Control which best practices apply → 🎨 Output Styles: Customize AI behavior → 📡 MCP Servers: Extend capabilities → 🔑 Providers: Manage API keys (Anthropic, Kimi, Z.AI) → 🎯 Platform: Set default target (Claude Code/OpenCode) ``` **Settings are stored globally** (`~/.sylphx-flow/`), ensuring consistency across all your projects. ### 5. **Git-Aware Intelligence** **Flow understands version control is sacred.** When Flow modifies settings files (`.claude/`, `.opencode/`), it uses `git update-index --skip-worktree` to hide changes from git status. This means: - ✅ LLMs won't accidentally commit Flow's temporary changes - ✅ Your version-controlled settings remain pristine - ✅ Automatic restore after each session - ✅ Seamless collaboration with your team ### 6. **Graceful Interruption** **Ctrl+C now means "restore and exit," not "crash and burn."** Press Ctrl+C at any time: ```bash $ sylphx-flow "long task" # ... working ... ^C > ⚠️ Operation cancelled by user > ✓ Settings restored > ✓ Git tracking restored > ✓ Environment clean # No crashed sessions. No manual recovery. ``` --- ## 🎭 The Flow Experience ### Minimal Input, Maximum Output **Flow implements MEP (Minimal Effective Prompt) architecture.** <table> <tr> <th width="50%">Traditional AI CLIs</th> <th width="50%">Sylphx Flow</th> </tr> <tr> <td> ```typescript // 5 minutes of typing... "I'm using TypeScript + React + Next.js 14, project structure is src/app for routes, src/components for components, using shadcn/ui, Tailwind for styling, Zod for validation, tRPC for API, current time is 2025-11-23, system is macOS Apple Silicon, I want to implement user authentication: - JWT tokens with 1hr expiry - Refresh token mechanism - Secure httpOnly cookies - RBAC with roles: user, admin - Rate limiting on login endpoint - Password hashing with bcrypt - Email verification flow Follow our existing code patterns, make it type-safe, add comprehensive error handling, include unit tests with Vitest, and document the API endpoints..." // Maybe correct, maybe not 🤷 ``` </td> <td> ```bash sylphx-flow "implement authentication" ``` **10 seconds.** Flow automatically knows: - Your tech stack (auto-detected) - Your patterns (from codebase) - Best practices (built-in) - Current time (system hook) - Your environment (OS, Node version) **Result: Production-ready code** - ✅ Type-safe - ✅ Tested - ✅ Documented - ✅ Secure - ✅ Following YOUR style </td> </tr> </table> --- ## 🎛️ Settings Management **Flow 2.0 introduces the settings nexus—your command center for AI orchestration.** ### Access Settings ```bash sylphx-flow settings ``` ### What You Can Configure #### 🤖 Agents & Default Agent ``` → Select which agents are enabled ✓ Coder (feature implementation, bug fixes) ✓ Writer (documentation, technical writing) ✓ Reviewer (code review, security analysis) ✓ Orchestrator (complex multi-step tasks) → Set default agent for quick access Default: coder ``` #### 📋 Rules ``` → Enable/disable coding standards ✓ Core (identity, personality, execution) ✓ Code Standards (quality, patterns, anti-patterns) ✓ Workspace (documentation management) ``` #### 🎨 Output Styles ``` → Customize AI behavior ✓ Silent (execution without narration) ⬚ Verbose (detailed explanations) [coming soon] ⬚ Tutorial (learning-focused) [coming soon] ``` #### 📡 MCP Servers ``` → Extend Flow's capabilities ✓ GitHub Code Search (grep.app) ✓ Context7 Docs ✓ Playwright Browser Control ⬚ GitHub (requires GITHUB_TOKEN) ⬚ Notion (requires NOTION_API_KEY) ``` #### 🔑 Provider & API Keys ``` → Manage AI providers (Claude Code only) • Default (Claude Code built-in) • Kimi (requires API key) • Z.AI (requires API key) • Ask me every time → Configure provider API keys securely ``` #### 🎯 Target Platform ``` → Set default AI CLI • Claude Code • OpenCode ``` ### Settings Architecture All settings are stored in `~/.sylphx-flow/`: ``` ~/.sylphx-flow/ ├── settings.json # General settings (default agent, target) ├── flow-config.json # Agents, standards, output styles ├── provider-config.json # Provider settings (Anthropic, Kimi, Z.AI) └── mcp-config.json # MCP server configurations ``` **Settings are global**, ensuring consistency across all your projects. Configure once, execute everywhere. --- ## 🤖 Specialized Agents **Flow includes four transcendent agents, each a master of their domain:** | Agent | Sacred Purpose | Invoke When | |-------|----------------|-------------| | **Coder** | Feature implementation, bug annihilation | Building new features, fixing bugs | | **Writer** | Documentation, technical prose | API docs, README updates, guides | | **Reviewer** | Code review, security sanctification | Pre-merge reviews, security audits | | **Orchestrator** | Complex multi-step orchestration | Architecture changes, large refactors | ```bash # Invoke the coder (default) sylphx-flow "implement user dashboard" # Summon the reviewer sylphx-flow "review for security vulnerabilities" --agent reviewer # Call upon the writer sylphx-flow "document the API endpoints" --agent writer # Unleash the orchestrator sylphx-flow "refactor authentication system" --agent orchestrator ``` **Configure enabled agents:** ```bash sylphx-flow settings → Select: Agents & Default Agent ``` --- ## 🧠 Domain Skills **25 domain-specific skills with expert-level knowledge built-in.** Flow includes curated best practices for critical domains. When you work on auth, billing, or security, the AI knows the non-negotiables: | Category | Skills | |----------|--------| | **Security** | `auth`, `account-security`, `security`, `trust-safety`, `privacy` | | **Payments** | `billing`, `pricing`, `ledger` | | **Data** | `database`, `data-architecture`, `storage` | | **Frontend** | `uiux`, `pwa`, `performance`, `seo`, `i18n` | | **Backend** | `observability`, `operability`, `delivery` | | **Growth** | `growth`, `referral`, `support`, `admin`, `discovery` | | **Quality** | `code-quality` | **Example: Billing skill includes:** - ✅ Webhook signature verification (non-negotiable) - ✅ Idempotency with Stripe event IDs - ✅ Out-of-order webhook handling - ✅ No dual-write patterns - ✅ Dunning and failed payment recovery **Example: Auth skill includes:** - ✅ Server-enforced authorization (never trust client) - ✅ Email verification for high-impact actions - ✅ Graceful SSO provider handling - ✅ Account recovery best practices Skills are automatically invoked based on context. The AI asks the right questions and avoids common mistakes. --- ## ⚡ Quick Start ### The Path to Enlightenment ```bash # 1. Install the meta-CLI npm install -g @sylphx/flow # 2. Interactive tutorial (recommended for first-time users) sylphx-flow quickstart # 3. Or jump straight in sylphx-flow "create a REST API" # Flow's first-time ritual: → Detects environment → Checks for Claude Code/OpenCode → Installs missing dependencies (with your permission) → Configures optimal settings → Upgrades to latest versions → Executes your command # 3. Subsequent invocations sylphx-flow "build something amazing" # Flow's ongoing ritual: → Auto-checks for updates → Auto-upgrades if needed → Executes with latest capabilities ``` ### Daily Usage ```bash # Simple tasks (MEP in action) sylphx-flow "add password reset" sylphx-flow "fix the login bug" sylphx-flow "optimize database queries" # Specialized agents sylphx-flow "review for security" --agent reviewer sylphx-flow "write API documentation" --agent writer sylphx-flow "refactor user service" --agent orchestrator # File input for complex prompts sylphx-flow "@detailed-requirements.md" # Settings management sylphx-flow settings ``` --- ## 🎯 Core Features ### 1. Universal CLI Orchestration **One interface. All tools. Zero friction.** Flow intelligently detects and orchestrates: - **Claude Code** - Anthropic's official CLI - **OpenCode** - Open source alternative - **Future tools** - Built for extensibility ```bash # Same command, different environments # Flow adapts automatically # On machine with Claude Code $ sylphx-flow "task" → Uses Claude Code # On machine with OpenCode $ sylphx-flow "task" → Uses OpenCode # On machine with both $ sylphx-flow "task" → Uses your preferred default ``` ### 2. Automatic Installation **Missing tools? Flow installs them for you.** ```bash # First time on a new machine $ sylphx-flow "build something" > No AI CLI detected. > Which platform would you like to use? 1. Claude Code (Anthropic, recommended) 2. OpenCode (open source alternative) > Your choice: 1 > Installing Claude Code... > ✓ Downloaded latest version > ✓ Configured settings > ✓ Installed MCP servers > ✓ Ready to execute > Executing your command... ``` ### 3. Automatic Upgrades **Every session uses the latest capabilities.** Flow checks for updates before each execution: ```bash $ sylphx-flow "task" > Checking for updates... > Updates found: • Flow: 2.0.0 → 2.1.0 • Claude Code: 1.5.0 → 1.6.0 > Upgrading... > ✓ Flow updated (new features available) > ✓ Claude Code updated (performance improved) > Executing with latest versions... ``` **Customize update behavior:** ```bash # Check updates without executing sylphx-flow upgrade # Auto-upgrade and execute sylphx-flow upgrade --auto ``` ### 4. MEP Architecture **Minimal Effective Prompt: AI that truly understands context.** Flow automatically enriches every prompt with: - 🔍 Your codebase patterns (via semantic search) - 📚 Best practices (via curated knowledge base) - 🖥️ Your environment (OS, Node version, git status) - ⏰ Current time and date - 🎯 Your preferred coding style ```bash # You type 3 words sylphx-flow "implement authentication" # Flow expands to full context: → Tech stack: TypeScript + React + Next.js (detected) → Patterns: Your existing auth patterns (searched) → Best practices: JWT, bcrypt, RBAC (knowledge base) → Environment: macOS, Node 20, git clean (hooks) → Time: 2025-11-23 (system) # Result: Perfect, production-ready code ``` ### 5. Settings-Driven Execution **Configure once. Perfect forever.** ```bash # Access settings nexus sylphx-flow settings # Configure: → Agents (coder, writer, reviewer, orchestrator) → Rules (core, code-standards, workspace) → Output styles (silent, verbose, tutorial) → MCP servers (grep, context7, playwright, github, notion) → Providers (Anthropic, Kimi, Z.AI) → Target platform (Claude Code, OpenCode) # Settings apply to ALL subsequent executions ``` ### 6. Git-Aware Operations **Flow respects your version control.** When Flow operates, it uses `git update-index --skip-worktree` to hide temporary changes: ```bash # Before Flow execution $ git status → clean working directory # During Flow execution (modifying .claude/config.json) $ git status → clean working directory # Changes hidden! # After Flow execution $ git status → clean working directory # Restored automatically ``` This ensures: - LLMs won't see or commit Flow's temporary settings - Your version-controlled configs remain pristine - Team collaboration stays clean --- ## 🏗️ Advanced Features ### Loop Mode - Autonomous Execution **Set it and forget it. Flow works while you sleep.** ```bash # Continuous autonomous work sylphx-flow "process all GitHub issues" --loop # With polling interval sylphx-flow "monitor and fix bugs" --loop 300 --max-runs 20 # Checks every 5 minutes, max 20 iterations # How it works: → Iteration 1: Fresh start → Iteration 2+: Auto-continue with context → Stop: Ctrl+C (graceful) or max runs reached ``` **Perfect for:** - 🔄 Processing backlogs (issues, PRs, tickets) - 📊 Periodic monitoring and auto-fixing - 🧹 Incremental refactoring - 🧪 Continuous test fixing - 📝 Documentation maintenance ### File Input Support **Complex prompts deserve better than shell escaping.** ```bash # Load prompt from file sylphx-flow "@task.txt" # Absolute paths supported sylphx-flow "@/path/to/detailed-requirements.md" # Combine with other flags sylphx-flow "@refactor-plan.md" --agent orchestrator --loop ``` **Benefits:** - 📝 Write natural language (no shell escaping) - 🔄 Version control your prompts - 🔀 Reusable task definitions - 🚀 No character limits ### Codebase Search - Semantic Understanding **Find code by what it does, not what it's called.** ```bash # Search by functionality sylphx-flow codebase search "user authentication logic" # Works across languages → Finds: authenticateUser() in TypeScript → Finds: authenticate_user() in Python → Finds: AuthenticateUser() in Go # Multilingual queries sylphx-flow codebase search "處理用戶登入嘅邏輯" # Chinese sylphx-flow codebase search "ユーザーログイン処理" # Japanese # Reindex after major changes sylphx-flow codebase reindex ``` **Powered by StarCoder2 tokenization** - 70+ languages supported. ### Knowledge Base - Curated Best Practices **Professional knowledge, zero maintenance.** ```bash # Search best practices sylphx-flow knowledge search "react performance optimization" sylphx-flow knowledge search "secure password hashing" sylphx-flow knowledge search "microservices patterns" # List all knowledge sylphx-flow knowledge list # Update to latest sylphx-flow knowledge update ``` **Why curated?** - ✅ Professionally maintained - ✅ Always up-to-date - ✅ Quality guaranteed - ✅ <100ms search - ✅ Zero cognitive load --- ## 🎯 Use Cases ### For Individual Developers ```bash # Rapid prototyping sylphx-flow "create a blog with markdown support" # Feature development sylphx-flow "add OAuth login with GitHub" # Bug fixing sylphx-flow "fix the memory leak in user service" # Refactoring sylphx-flow "refactor to use dependency injection" --agent orchestrator ``` ### For Teams ```bash # Code review automation sylphx-flow "review PR #123 for security" --agent reviewer # Documentation sylphx-flow "document all API endpoints" --agent writer # Consistency enforcement # (Settings ensure everyone uses same standards/agents) sylphx-flow settings → Team admin configures standards → All developers inherit settings ``` ### For Projects ```bash # Architecture changes sylphx-flow "migrate from REST to GraphQL" --agent orchestrator # Security audits sylphx-flow "audit for OWASP Top 10" --agent reviewer # Performance optimization sylphx-flow "optimize database queries" --loop # Continuous maintenance sylphx-flow "process GitHub issues" --loop 600 --max-runs 100 ``` --- ## 📚 Documentation ### Essential Reading - **[Installation & Setup](https://github.com/SylphxAI/flow/wiki/Installation-&-Setup)** - Complete setup guide - **[Settings Guide](https://github.com/SylphxAI/flow/wiki/Settings-Guide)** - Master the settings nexus - **[MEP Design Philosophy](https://github.com/SylphxAI/flow/wiki/MEP-Design-Philosophy)** - Understand the paradigm shift - **[Technical Architecture](https://github.com/SylphxAI/flow/wiki/Technical-Architecture)** - Deep dive into Flow's internals - **[CLI Commands](https://github.com/SylphxAI/flow/wiki/CLI-Commands)** - Full command reference - **[Agent Framework](https://github.com/SylphxAI/flow/wiki/Agent-Framework)** - How agents work - **[Loop Mode Guide](./packages/flow/LOOP_MODE.md)** - Autonomous execution mastery --- ## 🌐 Platform Support ### Current Support | Platform | Status | Auto-Install | Loop Mode | |----------|--------|--------------|-----------| | **Claude Code** | ✅ Full | ✅ Yes | ✅ Yes | | **OpenCode** | ✅ Full | ✅ Yes | ⏳ Coming Soon | | **Cursor** | ✅ MCP | Manual | ⏳ Coming Soon | ### Roadmap - [ ] **IDE Plugins** - VSCode, IntelliJ, Vim - [ ] **CI/CD Integration** - GitHub Actions, GitLab CI - [ ] **Cloud Execution** - Remote AI orchestration - [ ] **Team Collaboration** - Shared settings and knowledge - [ ] **Custom Agents** - Create your own specialized agents --- ## 💡 Why Flow? ### The Transcendent Difference | Feature | Traditional AI CLIs | Sylphx Flow | |---------|---------------------|-------------| | **CLI Count** | Multiple (1 per tool) | **One (rules them all)** | | **Installation** | Manual, fragmented | **Automatic, unified** | | **Updates** | Manual per tool | **Automatic per session** | | **Settings** | Per-project, scattered | **Global, centralized** | | **Context Awareness** | Manual prompting | **Automatic enrichment** | | **Prompt Length** | 500+ words | **3-10 words (MEP)** | | **Git Integration** | Accidental commits | **Skip-worktree protection** | | **Ctrl+C Handling** | Crashes, manual recovery | **Graceful restore** | | **Agent System** | Generic AI | **Specialized experts** | | **Knowledge Base** | DIY or none | **Professionally curated** | ### Quantified Impact - ⚡ **30x faster** - Time to prompt (10s vs 5min) - 📝 **50x shorter** - Prompt length (10 words vs 500) - 🎯 **+25%** - Context accuracy (95% vs 70%) - 🧠 **-80%** - Cognitive load (minimal vs high) - 🔄 **Zero** - Maintenance overhead (vs constant) - 🚀 **5x faster** - Team onboarding (days vs weeks) --- ## 🙏 Acknowledgments Flow stands on the shoulders of giants: - **[StarCoder2](https://huggingface.co/bigcode/starcoder2)** - Revolutionary code tokenization - **[MCP Protocol](https://modelcontextprotocol.io)** - Standard AI tool integration - **[Anthropic Claude](https://claude.ai)** - Foundation model - **[OpenCode](https://github.com/openmcp/opencode)** - Open source alternative - Open source community ❤️ --- ## Packages | Package | Version | Description | |---------|---------|-------------| | [@sylphx/flow](./packages/flow) | [](https://www.npmjs.com/package/@sylphx/flow) | Core CLI - unified orchestration for all AI development tools | --- ## License MIT License - see [LICENSE](LICENSE) file for details. --- ## Star History [](https://star-history.com/#SylphxAI/flow&Date) ## Powered by Sylphx - [@sylphx/biome-config](https://www.npmjs.com/package/@sylphx/biome-config) --- <div align="center"> _{Built with ❤️ by <a href="https://github.com/SylphxAI">Sylphx</a>} </div>