🌊 Flux Flow
<p align="left" <a href="https://github.com/KushalRoyChowdhury/fluxflow-cli"<img src="https://img.shields.io/badge/FluxFlow-v3-blue?style=plastic" alt="FluxFlow Version"</a <a href="https://opensource.org/licenses/MIT"<img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=plastic" alt="License MIT"</a <a href="https://nodejs.org"<img src="https://img.shields.io/badge/Node-%3E%3D20-green?style=plastic" alt="Node Compatibility"</a </p
A Beautiful, Autonomous Terminal AI Agent
📖 Official Documentation
Flux Flow is an advanced, fully autonomous AI agent that lives directly in your terminal. Built with Node.js and Ink (React for interactive command-line apps), it provides a highly responsive, component-based UI powered by a sophisticated dual-model AI architecture.
Whether you need a conversational partner or an autonomous developer that can write code, run shell commands, and read your project files, Flux Flow adapts to your needs.
---
✨ Features
- Multi-Provider Support: Choose your preferred engine!
- Google GenAI (Gemini & Gemma models)
- DeepSeek (Native DeepSeek API)
- OpenRouter (Access to hundreds of models; Experimental)
- NVIDIA (Access to many models)
- Mistral (Access to selected models; Experimental)
- High-Fidelity IDE Companion: Flux Flow now pairs with a dedicated VS Code extension to bridge the gap between terminal and editor:
- Surgical Diagnostic Sync: The agent has "Red Squiggle Radar"—it proactively detects errors across your entire workspace and offers a "Magic Wand" fix button.
- Live Status Heartbeat: Real-time telemetry in the VS Code Status Bar shows exactly what the agent is doing (e.g., Thinking..., Reading file.js..., Patching app.jsx...).
- Clickable Terminal Links: All file paths and line numbers printed in the terminal are live links; click them to jump straight to that code in your IDE.
- Selection-Driven Reasoning: Select code and right-click - "Chat with FluxFlow" to instantly focus the agent with full context.
- Smart Context Awareness: The agent knows your cursor position, active selection, and even errors in files you don't have open.
- Universal Compatibility: Works flawlessly with VS Code, Cursor, VSCodium, Trae, and Antigravity.
- Native Multimodality: Flux Flow can now see! Analyze images (JPG, PNG) and PDF documents natively through the ReadFile tool with high-fidelity context retention (Only on supported models).
- Document Engineering Suite: Generate professional, branded PDF, DOCX documents on the fly. Features native HTML-to-Office translation for selectable text, high-performance rendering, and automatic watermarking.
- Codebase Time Travel (Git-less Reversion): Refactor and build with absolute fearlessness. Flux Flow maintains transaction-based secure snapshots of files before they are generated or edited:
- Instant Rollback: Revert your workspace files (source code, generated documents, images) to their exact state prior to any selected prompt in the history.
- Double-ESC Shortcut: Press ESC twice while idle to pop open a sleek selection modal.
- /revert Command: Run the /revert command directly in the chat to open the checkpoint viewer.
- External Data Sanctuary: Redirect your logs, history, and memories to any external path for maximum portability and privacy.
- Responsive Terminal UI: A gorgeous, reactive interface built with React and Ink, featuring multi-line input, status bars, modals, and diff views.
- Dual-Model Architecture: A primary agent interacts with you and executes tasks, while a silent background "Janitor" model handles chat summarization and long-term memory extraction without blocking the main UI.
- Two Operating Modes:
- Flux (Dev Mode): Full system access. The agent can read/write files, execute shell commands, and run autonomous agentic loops (up to 45 iterations) to solve complex coding tasks.
- Flow (Chat Mode): Focused on conversation and web research, with limited agentic loops for faster response times.
- Advanced Memory System: Features both temporary session context and persistent, cross-session user memories encrypted locally on your machine.
- Agentic Tooling: Built-in tools for smart file patching, web scraping, web searching, terminal execution and high-fidelity Office document generation (PDF/DOCX).
- Autonomous Project Alignment: Automatically detects and adheres to project-specific instructions in Agent.md, Skills.md, and Fluxflow.md for high-fidelity coding standards and complex workflows.
- Customizable "Thinking" Levels: Adjust the depth of the model's reasoning process (from Fast to xHigh).
- Autonomous Subagent System: Spawns subagents in either blocking mode (invokeSync) or asynchronous mode (invoke) to offload tasks. Runs with a permanent suite of 10 system tools (e.g. ReadFile, PatchFile, WebSearch, WritePDF), excluding shell commands (Run is disabled). Telemetry is quietly tracked in the CLI's active subagents UI block and backed up in transaction-safe restoration records.
- High-Reliability Fallback: Automatic failover to a lighter, high-concurrency model (Gemini 3.1 Flash Lite) during peak traffic to ensure 100% session persistence.
🚀 Quick Start
Prerequisites
- Node.js (v18 or higher recommended)
- npm, yarn, or pnpm