fluxflow-cli 3.0.16 → 3.0.17

package/.puppeteerrc.cjs

@@ -0,0 +1,13 @@
+const { join } = require('path');
+
+/**
+ * @type {import("puppeteer").Configuration}
+ */
+module.exports = {
+    // Pin the precise version of Chrome you need
+    chrome: {
+        version: '148.0.7778.178',
+    },
+    // Use the home directory for the browser cache to keep the project folder clean
+    cacheDirectory: join(require('os').homedir(), '.cache', 'puppeteer'),
+};

package/README.md

@@ -1,5 +1,5 @@
-# 🌌 Flux Flow (`fluxflow-cli`)
-![Flux Flow Logo](https://github.com/KushalRoyChowdhury/fluxflow-cli/blob/main/fluxflow.png)
+# 🌊 Flux Flow
+![Flux Flow Hero](./fluxflow.png)
 
 <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>
@@ -7,100 +7,94 @@
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-%3E%3D20-green?style=plastic" alt="Node Compatibility"></a>
 </p>
 
-### *The High-Fidelity Agentic CLI with Sub-Agents for the Flux Era.*
+**A Beautiful, Autonomous Terminal AI Agent**
 
-📖 **[Official Documentation](https://fluxflow-cli.onrender.com/)**
+📖 **[Official Documentatio]n(https://fluxflow-cli.onrender.com/)**
 
-**Flux Flow** is not just another CLI—it's a high-speed, sassy, and goal-oriented CLI AI Agent powered by the latest Gemini/Gemma frontier models. Designed for developers who demand a premium UI/UX while managing complex file-system tasks, web research, and autonomous workflows.
+Flux Flow is an advanced, fully autonomous AI agent that lives directly in your terminal. Built with Node.js and [Ink](https://github.com/vadimdemedes/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.
 
-## 🚀 Instant Ignition (No Setup Required)
-You don't even need to install it. Just fire up your terminal and run:
+---
 
-```bash
-# Run instantly (Zero Setup)
-npx fluxflow-cli
+## ✨ Features
 
-# OR Install Globally
-npm install -g fluxflow-cli
-fluxflow-cli
-```
-
-*The agent will prompt you for your API Key on the first run and store it securely in an encrypted vault.* Choose from multiple supported AI providers:
+- **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 selected models)
 
----
-
-## ✨ Why Flux Flow?
-
-### 🎨 **Premium Visual Sovereignty**
-Experience a terminal UI that feels alive. Built with **Ink** and **React**, Flux Flow features:
-- **Dynamic Status Bar**: Real-time telemetry showing your "Neural Headroom" (token usage), Thinking Level, and Session ID.
-
-### 🔌 **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**: Proactive background scanning for errors. If your project breaks, a "Magic Wand" icon $(\text{sparkle})$ appears in your editor title bar for an instant AI fix.
-- **Live Status Heartbeat**: The VS Code Status Bar acts as a live feed, showing the agent's current task (*Thinking*, *Web Searching*, *Patching*, etc.).
-- **Clickable Terminal Links**: Jump from the terminal output straight to your code with clickable file:line links.
-- **Right-Click Integration**: "FluxFlow > Chat" is available in the editor, explorer, and tab bars, even when no files are open.
-- **Selection-Driven Reasoning**: Select a block of code and ask "What does this do?"—the agent receives your selection instantly.
-- **Universal Compatibility**: Works flawlessly with VS Code, Cursor, VSCodium, Trae, and Antigravity.
-
-### 👁️ **Native Multimodality**
-Flux Flow can now see! Use the `view_file` tool to analyze images (JPG, PNG) or deep-dive into PDF technical papers. The agent extracts high-fidelity visual context natively, making it a true multimodal companion.
-
-### 📑 **Document Engineering Suite**
-Need a report or a presentation? Just ask. Flux Flow features a high-fidelity "Printing Press" that generates professional, branded documents natively:
-- **PDF**: Branded documents from HTML/CSS with automatic watermarking.
-- **DOCX**: Native Word documents with multi-page support and automatic numbering.
+- **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](https://nodejs.org/) (v18 or higher recommended)
+- `npm`, `yarn`, or `pnpm`
+
+### Via NPM (Global & Instant)
+You can run the agent instantly or install it globally for high-speed access:
 
-### ⏱️ **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.
+```bash
+# Run instantly (Zero Setup)
+npx fluxflow-cli
 
-### 🚑 **Self-Healing Infrastructure**
-Zero setup means zero setup. On first run, Flux Flow performs an integrity check and autonomously installs its own Chromium engine if needed, ensuring features like PDF generation work 100% of the time without manual intervention.
+# OR Install Globally
+npm install -g fluxflow-cli
+fluxflow
+```
 
-- **Archived Terminal Flow**: See execution outputs transform from live elements into permanent conversation records.
-- **Rich Aesthetics**: High-contrast, sleek design with smooth transitions and micro-animations.
+### From Source (Local Development)
+1. Clone the repository and install dependencies:
+   ```bash
+   git clone https://github.com/KushalRoyChowdhury/fluxflow-cli
+   cd fluxflow-cli
+   npm install
+   ```
 
-### 🧠 **The Dual-Intelligence System**
-- **Flux Mode (Dev)**: High-speed, agentic problem solving with a 70-turn persistent loop for massive coding tasks.
-- **Flow Mode (Chat)**: Optimized for high-quality conversation and web-assisted reasoning.
+2. Start the agent:
+   ```bash
+   npm start
+   ```
 
-### 🛡️ **Digital Fortress Governance**
-Security isn't an afterthought; it's a boundary.
-- **Sandbox Presets**: Choose from **Strict**, **Balanced**, **Autonomous**, or **Custom** security profiles to control agent autonomy.
-- **Granular Command Policies**: Configure Auto-Approve (`Auto` / `Read-Only` / `None`), Auto-Disallow (`Auto` / `Destructive` / `None`), Network Access toggle, and Auto-Approve Git Commits independently.
-- **External Path Hardlock**: Restricts the agent to your Current Working Directory (CWD) unless you explicitly unlock it.
-- **Human-in-the-Loop (HITL)**: Every file write and terminal command requires your high-fidelity approval.
-- **XOR Vaulting**: All local session histories, memories, and API keys are obfuscated and encrypted at rest.
-- **Adaptive Failover**: Automatic multi-stage retry logic with high-concurrency fallback model switching (Gemini 3.1 Flash Lite) during peak API congestion.
+## 📖 Documentation
 
-### 🧹 **The Background Janitor**
-While you move at high speed, the Janitor follows behind—refining session titles, compressing data, and ensuring your context window remains at absolute peak performance.
+🌐 **Official Documentation**: [HERE](https://fluxflow-cli.onrender.com/)
 
-### 🤖 **Autonomous Subagent System**
-Delegate complex tasks to subagents. Spawns blocking subagents (`invokeSync`) or asynchronous background subagents (`invoke`) with distinct telemetry and silent background logging. Built-in transaction-safe reversion logs all subagent changes under the active turn, preserving rollback security.
+To keep this README concise, detailed information about specific components of Flux Flow has been split into separate documents:
 
----
-
-## 🛠️ Key Capabilities
-- **Deep File-System Interaction**: Edit, move, and refactor code across multiple files with atomic precision.
-- **Real-Time Web Intelligence**: Autonomous web-searching via DuckDuckGo for live news and technical research.
-- **Autonomous Project Alignment**: Automatically detects and adheres to project-specific instructions in `Agent.md`, `Skills.md`, and `Fluxflow.md` for high-fidelity alignment with your coding standards and custom workflows.
-- **High-Reliability Fallback**: Automatic failover to a lighter, high-concurrency model during peak traffic to ensure zero session loss.
-- **Persistent Memory**: The agent learns from your preferences and project requirements across sessions.
-
----
+- **[Architecture & Design](./ARCHITECTURE.md)**: Deep dive into the React/Ink rendering, the Agentic Loop, and the Janitor background process.
+- **[Agent Tools & Capabilities](./TOOLS.md)**: A comprehensive list of the tools available to the agent (e.g., File I/O, Execution, Web tools).
+- **[UI & Interaction Features](./UI_FEATURES.md)**: Details on commands, thinking levels, and human-in-the-loop verification.
 
 ## 💻 CLI Startup Arguments
+
 Customize your session parameters directly from your console launch command:
 
 ```bash
@@ -108,30 +102,36 @@ fluxflow [options]
 ```
 
 ### Supported Flags:
-- `--model <model-name>`: Temporary override for the active AI model (e.g., `gemini-2.5-pro`). Keeps settings file untouched.
+- `--model <model-name>`: Temporary override for the active AI model (e.g., `gemini-3.1-pro-preview`). Keps settings file untouched.
 - `--memory <on | off>`: Toggle persistent long-term agent memory for the session.
 - `--resume <session-id>`: Resume a previous chat session programmatically.
 - `--update <check | latest>`: Manually run an update check (`check`) or execute latest update setup (`latest`).
 - `--package <npm | pnpm | yarn | bun>`: Override default package manager to run core application updates.
 - `--auto-del <1d | 7d | 30d>`: Set automated chat log deletion schedule.
-- `--yolo <on | off>`: Toggle autonomous execution permission.
+- `--yolo <on | off>`: Toggle autonomous command execution permission.
 - `--external-access <on | off>`: Toggle permission to let agent read files outside CWD.
-- `--thinking <Fast | Low | Medium/Standard | High | xHigh>`: Override thinking level for reasoning depth. `Medium` and `Standard` is the same (Deepseek compatibility).
+- `--thinking <Fast | Medium | High | xHigh>`: Override default thinking level.
 - `--key <key@google | key@deepseek | key@openrouter>`: Set API key and provider.
 - `--provider <google | deepseek | openrouter>`: Override default provider.
 
 ---
 
-## ⚙️ Configuration
-Type `/settings` in-app to live-configure:
-- **Thinking Level**: Fast (No Reasoning), Low, Medium, High, xHigh (Extended Reasoning).
-- **Sandbox Preset**: Strict, Balanced, Autonomous, or Custom security profiles.
-- **Security Perimeter**: Toggle External Workspace access, Network Access, and Git Commit auto-approval.
+## 🔒 Security & Privacy
 
----
+Flux Flow runs entirely locally on your machine.
+- **Sandbox Presets**: Choose from **Strict**, **Balanced**, **Autonomous**, or **Custom** profiles to fine-tune agent autonomy out of the box.
+- **Granular Command Policies**: Configure Auto-Approve (`Auto` / `Read-Only` / `None`), Auto-Disallow (`Auto` / `Destructive` / `None`), Network Access toggle, and Auto-Approve Git Commits independently.
+- **Global Storage**: All history, memories, and API keys are stored securely in your home directory at `~/.fluxflow`. Sensitive data is encrypted.
+- **Nuclear Reset**: Use the `/reset` command to instantly purge all logs, secrets, and settings from the global storage directory.
+- **Configurable Boundaries**: In Flux mode, file access can be strictly confined to the Current Working Directory, or expanded globally via settings.
+- **API Keys**: You supply your own API keys for your preferred provider: Google GenAI, DeepSeek, or OpenRouter (Experimental).
+
+## 🛠️ Built With
 
-## 🏁 License
-MIT © 2026 Flux Flow.
+- **[React](https://react.dev/) & [Ink](https://github.com/vadimdemedes/ink)**: For the interactive CLI rendering.
+- **[@google/genai](https://www.npmjs.com/package/@google/genai)**: The core AI SDK powering the agent's intelligence.
+- **[chalk](https://www.npmjs.com/package/chalk) & [gradient-string](https://www.npmjs.com/package/gradient-string)**: For terminal styling and aesthetics.
+- **[fs-extra](https://www.npmjs.com/package/fs-extra)**: For robust file system operations.
 
 ---
-*Forged with ⚡ and 🧬. Welcome to the FluxFlow.*
+*Created as a demonstration of highly capable AI tooling.*

package/dist/fluxflow.js

@@ -3702,7 +3702,7 @@ var init_TerminalBox = __esm({
         return resultLines.join("\n");
       };
       const cleanOutput = processPTY(output).replace(/\n{3,}/g, "\n\n");
-      const rawLines = isPty ? cleanOutput ? cleanOutput.split("\n") : [] : cleanOutput ? wrapText(cleanOutput, columns - 6) : [];
+      const rawLines = isPty ? cleanOutput ? cleanOutput.split("\n") : [] : cleanOutput ? wrapText(cleanOutput, columns - 6).split("\n") : [];
       const [isExpanded, setIsExpanded] = useState3(false);
       useInput2((input, key) => {
         if (isFocused && key.ctrl && (input === "o" || input === "")) {

package/flux-flow.cjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const path = require('path');
+
+// Resolve paths relative to this absolute CJS root
+const CLI_PATH = path.join(__dirname, 'src', 'cli.jsx');
+const TSX_PATH = path.join(__dirname, 'node_modules', '.bin', 'tsx' + (process.platform === 'win32' ? '.cmd' : ''));
+
+const flux = spawn(TSX_PATH, [CLI_PATH], {
+    stdio: 'inherit',
+    shell: true
+});
+
+flux.on('exit', (code) => {
+    process.exit(code || 0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fluxflow-cli",
-    "version": "3.0.16",
+    "version": "3.0.17",
     "date": "2026-07-04",
     "description": "A High-Fidelity Agentic CLI with Sub-Agents for the Flux Era.",
     "keywords": [
@@ -29,7 +29,9 @@
         "ARCHITECTURE.md",
         "TOOLS.md",
         "UI_FEATURES.md",
-        "cat.txt"
+        "cat.txt",
+        ".puppeteerrc.cjs",
+        "flux-flow.cjs"
     ],
     "type": "module",
     "bin": {