🌮 Nacho Flow: VS Code & Cursor Companion Extension

You just paid $2.00 to ask your AI agent to check a log file. There's a better way.

Route routine prompt turns (log inspections, file searches, syntax fixes) to your local workstation GPU ($0.00) and automatically burst complex multi-file reasoning to frontier cloud APIs with 100% reasoning fidelity and up to 94.7% cost reduction.

The Nacho Flow VS Code Companion Extension delivers a high-visibility control hub, real-time financial telemetry dashboard, preset hot-swapper, and market deal scout for autonomous coding agents (Zoo Code, Cline, Cursor, OpenCode, Aider, Continue).

⚡ 60-Second Quickstart (Zero CLI Required)

The extension bundles the native high-performance Go dispatch binary directly. You do not need Go installed or any command-line setup:

1. Open the Nacho Flow Sidebar: Click the 🌮 Nacho Flow icon in the VS Code Activity Bar (left sidebar).
2. Launch the Engine: Under 1. Model Dispatcher, click ▶ Start. The status chip turns 🟢 Engine Online.
3. Configure Your Agent: Under 3. Coding Agents, click 📋 Copy next to:
   • Base URL: http://127.0.0.1:8000/v1
   • Model ID: nacho-hybrid
   • (Optional API Key: sk-nacho-secret-key)
4. Paste into Your Agent: Open Zoo Code, Cline, or Cursor settings $\rightarrow$ set Provider to OpenAI Compatible $\rightarrow$ paste the copied values.

Routine turns now run on your GPU for $0.00, while complex reasoning automatically escalates to Claude or DeepSeek-R1!

✨ Features

🎛️ 1. Sidebar Control Hub (Activity Bar)

Manage your agent supervisor and model dispatcher directly from your editor sidebar without obscuring your code:

• Local vs. Remote Gateway:
  • This Machine: 1-click ▶ Start, ⏹ Stop, 🔄 Restart, and interactive streaming 📄 Logs for the bundled native Go engine.
  • Remote Server: Connect across LAN or Tailscale (e.g. http://192.168.1.100:8000 or http://gpu-box.internal:8000) with optional Bearer Auth Token and instant ⚡ Test ping. When switching to Remote Server, the local engine is cleanly stopped to free GPU memory, and automatically resumed when you switch back to This Machine.
• Configurable Routing Profiles with 1-Click Switching (⚡ Switch):
  • Switch on the fly between three independent, fully customizable configuration profiles (profile1.yaml, profile2.yaml, profile3.yaml) with native process isolation:
    • 🌮 Profile 1 (profile1.yaml / config.yaml): Fully customizable configuration slot (e.g. general-purpose coding rules and balanced local/cloud routing).
    • 🤖 Profile 2 (profile2.yaml): Fully customizable configuration slot (e.g. tuned for multi-agent workflows like Zoo Code with strict JSON tool calling).
    • 🛠️ Profile 3 (profile3.yaml): Fully customizable configuration slot (e.g. tuned for XML-based tool agents like Cline with relaxed prose ceilings).
  • You have total freedom to customize each profile for any combination of models, providers, context thresholds, and routing rules you prefer.
  • In local mode, switching cleanly restarts the native engine with the --config <path> flag. In remote mode, local profile mutation is safely disabled.
  • Click 📝 Edit YAML (or the dashboard [📝 Profile X (YAML)] button) to open the active profile in the editor with auto-reload on save.
• Provider Status Monitoring: Real-time discovery and health chips for local engines (Ollama, vLLM, llama.cpp) and cloud APIs (OpenRouter, DeepSeek, Anthropic).
• 1-Click Agent Setup: Instant copy buttons for Base URL, API Key, and Model ID, plus marketplace install buttons for Zoo Code and Cline.
• Maintenance & Recovery: 1-click buttons to recalculate stats from logs, reset tripped circuit breakers, or zero accumulators.

📊 2. Real-Time Analytics Dashboard (Ctrl+Shift+P → Nacho Flow: Show Dashboard)

A mission-control flight instrument webview built on a Unified Top-Down State Snapshot Architecture:

• Unified State Snapshot & Monotonic Rendering:
  • Atomic snapshot delivery (DashboardSnapshot) with monotonic timestamp sequencing, eliminating visual race conditions, ghost cards, or out-of-order deliveries during rapid switches.
  • Active Profile Badge & Config Button: Dynamic header indicators (📋 Profile X / 🌐 Remote Server) with a 1-click [📝 Profile X (YAML)] / [📝 Remote config.yaml] editor button.
  • Clean Offline Transitions: Disconnecting or stopping the engine atomically purges all data caches and displays clean offline status banners.
• Financial Telemetry & Time Windows:
  • Filter metrics by All Time, Today, Yesterday, This Week, or This Month.
  • Displays Total Spend, Total Savings ($ and %), Local GPU Turns ($0.00), Cloud Turns, and Billed vs. Avoided Token volume.
  • Counterfactual Savings Engine: Calculates true mathematical cost savings comparing local turns against frontier cloud pricing, including prompt cache discounts.
• Live Route Inspector:
  • Inspect the last 500 LLM requests processed by the gateway in real time.
  • View exact token estimates, round-trip latency, matching tier rule, provider, model ID, and retry recovery steps.
• Auto-Refresh Controls: Set background route updates to 15s, 30s, 60s, or Off, or click Refresh Now.

🛡️ 3. "The Three Fixes" Live Defense Telemetry

Nacho Flow supervises local and cloud open-weight models in real time, eliminating common agent failure loops:

• 🎸 Cycle Killer (In-Flight Stream Breaker):
  • Monitors the live token stream in real time. Kills repetitive N-gram loops and runaway prose in $<3$s, injecting a local $0.00 system override before escalating to cloud.
  • Visualizes intercepted loops, avoided runaway GPU minutes, and local self-healing rate ($0.00 recovery via [SYSTEM OVERRIDE] prompts).
• ⚡ Kickstart (Stall Resuscitation Engine):
  • Monitors consecutive non-write turns. Auto-suspends during exploration via extensible schema detection (HasWriteCapability), and jolts agents out of passive read/plan procrastination when implementation stalls.
• 🧚 Fairy Dust (Programmable Milestone Checkpoints):
  • A cadenced intervention engine. You control the trigger interval (every $N$ writes), the model, the audit prompt, and the spend cap—deploying frontier reasoning models precisely when and where quality verification matters.

🔥 4. Heat Seeker: Live Model Deals & 1-Click Tier Adoption

Heat Seeker continuously scans 300+ cloud models on OpenRouter, discovering flash discounts, subsidized capacity, and 100% free endpoints:

• Deal Cards: Displays discount percentage (up to 99% OFF or 100% FREE), prompt and completion pricing per 1M tokens, 🔧 Tools support indicator, SWE-bench coding capability score (🧠 Index XX.X), and provider badge.
• 1-Click Tier Adoption (⚡ Adopt):
  1. Click ⚡ Adopt on any discovered deal card.
  2. A VS Code QuickPick modal appears with your active tiers; recommended target tiers are marked with a ⭐.
  3. Select the tier to replace. The extension creates an automatic timestamped backup (config.yaml.bak_<timestamp>), updates the YAML while preserving all comments, and hot-swaps the new model into the running gateway with zero downtime!
• 1-Click Copy Model ID: Copy model IDs to your clipboard for instant prompt turn overrides (@nacho:model="...").

🎛️ 5. 1-Click Auto-Tuning Optimizer

Click Run Auto-Tuner in the dashboard toolbar to analyze historical turns from traffic.jsonl:

• Statistical odds-ratio analysis calculates the optimal context boundary where local model error rates rise.
• Recommends calibrated token thresholds and keyword exclusion rules.
• Review the visual diff banner in the dashboard and click Apply Recommendation to atomically update config.yaml with an automatic backup.

🚦 6. Status Bar HUD & Hover Card

A lightweight widget in your VS Code Status Bar (bottom right):

🌮 $45.81 Saved Today (2% Local)

• Hover Card: Rich Markdown tooltip displaying active daemon status, active preset (Cline), today's spend/savings (+$45.81 / 75% saved), token volume, and quick links.
• Click QuickPick: Opens a quick menu to open the dashboard, switch presets, start/stop/restart the engine, open config.yaml, or reset circuit breakers.

🌶️ 7. Direct In-Chat Control Directives (@nacho:)

Steer routing and toggle session guardrails directly from your prompt in Zoo Code, Cline, or Cursor without opening settings:

🏛️ Architecture: Thin-Client Doctrine

This extension strictly adheres to the Thin-Client Doctrine:

1. Single Source of Truth: All configuration resides in config.yaml—zero duplicate settings in VS Code workspace state.
2. Zero Core Logic in TypeScript: All routing evaluations, token estimations, normalizers, and cost calculations execute in compiled Go inside the daemon.
3. Reactive SSE Transport: Consumes server-sent events with zero polling loops, preserving editor battery and CPU cycles (0.0% CPU when idle).

⌨️ Command Palette Reference

All features can be triggered via Ctrl+Shift+P / Cmd+Shift+P:

⚙️ Extension Settings

Configure extension behaviors in VS Code Settings (Ctrl+, $\rightarrow$ search Nacho Flow):

📚 Documentation & Community

• Official Website & Docs Hub: spicebox.dev/nacho-flow
• Interactive Documentation: spicebox.dev/nacho-flow/docs.html
• Full Extension User Guide: docs/EXTENSION_USER_GUIDE.md
• GitHub Repository: github.com/dixieflatline76/nacho-flow
• Support & Community: spicebox.dev/nacho-flow/support.html

🌮 Support Nacho Flow

Nacho Flow is 100% free and open source for individual developers and open-source projects. It was born out of sheer engineering frustration while building Spice, when autonomous coding agents kept burning hundreds of dollars in API credits on runaway loops and planning stalls.

If Nacho Flow saved your sanity, your workflow, or your API bill:

• Don't buy me a coffee. Instead, consider grabbing a copy of Spice on the Mac App Store or Microsoft Store (or leaving it a 5-star review). You get a beautiful, native desktop utility in return, and it directly funds continued open-source development.
• On Linux or dev containers? Give Nacho Flow a star on GitHub. It boosts repository visibility and helps fellow developers discover local agent routing!

📄 License

• The VS Code Companion Extension is open source under the MIT License.
• The core Nacho Flow gateway daemon is licensed under GNU AGPL-3.0 with API Interoperability Exception.