🦊 LIQUID OPS

"Code has changed. It's an endless series of refactors, managed by AI agents and machines."

Liquid Ops is a Tactical Code Intelligence System. It transforms the abstract task of "software engineering" into a visual, spatial, and strategic Real-Time Strategy (RTS) game.

Instead of managing 20 terminal windows or scrolling through flat file trees, you become the Commander of a specialized AI unit. You look at a 3D tactical map of your codebase, identify high-value targets (technical debt, bugs, missing features), and deploy elite autonomous agents to neutralize them.

---

📡 The Vision

We believe that Agentic AI requires a new interface. Chatbots are linear. Codebases are high-dimensional graphs. To manage a swarm of intelligent agents effectively, you need Situational Awareness, not just a log stream.

🛑 The Problem: "Gas Town" Chaos

Existing multi-agent systems solve the problem of parallelism by brute force:

• Spawning 20 copies of the repo.
• Running 20 isolated agents.
• Merging the chaos at the end.
• Interface: A spreadsheet or list of logs.

✅ The Liquid Ops Solution: "Surgical Strike"

We solve the problem with Shared Intelligence.

• One Truth: All agents share a live Liquid Shadow intelligence graph.
• Surgical Precision: Agents don't overwrite each other; they operate in assigned Sectors (Logic Layer, Data Layer, etc.).
• Interface: A 3D Tactical Map where you see the architecture, the agents, and the mission status in real-time.

---

🏗️ Architecture

Liquid Ops is composed of three primary pillars:

1. The Engine: Liquid Shadow (The Satellite)

The core of Liquid Ops is Liquid Shadow, an advanced code intelligence system exposed as a Model Context Protocol (MCP) server.

• Micro-Topography: Maps your code into discrete layers (Entry, Logic, Data, Utility).
• Polyglot Tracing: Traces execution flow across languages and files.
• Benefit: Agents don't search blindly. They know where the Auth Logic is because the map tells them, avoiding costly full-repo scans.

2. The Units: Specialists for Code (The AI Swarm)

We deploy Specialists routed to the best model and CLI for the job. Liquid Ops orchestrates these tools seamlessly:

Unit	Role	Default Runtime	Behavior
OVERSEER	Commander & Planner	claude	Session-resumed commander. Prefers live attach when available, otherwise respawns with session resume and continues mission context.
RECON	Intelligence	codex / gemini	Fire-and-forget. Reads massive context, maps dependencies, and identifies risks without mutating code.
ENGINEER	Execution	codex / gemini	Fire-and-forget. Specialized in surgical refactoring, writing features, and fixing bugs.

3. The Interface: Command Center (The Map)

Built with Next.js, React Three Fiber (R3F), and Drei, the interface renders your codebase as a Hexagonal Base (The Motherbase).

• Command Spire: The central hub, representing the active project.
• Modules: Components like Logistics, Habitation, and Power generated procedurally based on code statistics (files & symbols).
• Visual Feedback:
  • Spires glow & pulse: Indicate active streaming sessions and live chat connections.
  • Color Coding: Each imported project receives a unique accent color and codename (e.g., ALPHA, BRAVO).

---

🎮 How It Works (The Gameplay Loop)

1. Infiltration (Init)
   • Launch Liquid Ops.
   • Register your local repositories.
   • It performs a shadow_recon scan to index the repository.
   • A unique 3D Motherbase is instantly constructed on the Command Deck.
2. Mission Planning (Briefing)
   • Select a project Spire to enter its sector.
   • Talk to the OVERSEER. Issue a Directive: "Upgrade all JWT handlers to use the new library."
3. Deployment (Action)
   • The OVERSEER plans out the execution steps and uses MCP tools to dispatch a RECON or ENGINEER unit to perform the task.
   • Real-time updates map the job's progress directly onto your HUD.

---

🚀 Getting Started

Prerequisites

• Node.js 20+
• AI CLI dependencies installed globally (claude, codex, gemini), depending on your preferred runtimes.

Installation

1. Clone the repository and install dependencies:

   npm install

2. Start the Command Center development server:

   npm run dev

3. (Optional) Start the MCP server independently if needed for integration:

   npm run mcp

Open http://localhost:3000 to access the Command Deck.

---

🛠️ Tech Stack & API

• Frontend: Next.js 16 (App Router), React 19, Tailwind CSS v4, Framer Motion
• 3D Engine: Three.js, React Three Fiber, React Three Postprocessing
• State Management: Zustand (Shared State for Game, Chat, Project, and Performance)
• AI Orchestration: Custom Node Subprocess Handlers capturing execution streams via CLI
• Local Persistence: Better-SQLite3 for structured Agent execution logging (~/.liquid-ops/sessions/)

MCP Integration

Liquid Ops itself exposes an MCP server (mcp-server/index.mjs) used by the OVERSEER to decouple execution. The following tools are available to the commander AI:

• recon: Distribute an intelligence gathering job to the RECON unit.
• engineer: Distribute an execution job to the ENGINEER unit.
• job_status: Poll on active worker threads.
• reset_session: Wipe the active context for an assigned repo.

---

"This isn't just a tool. It's a next-generation command center."