What is GROOVE?

GROOVE is a visual command center for AI coding agents. It spawns, coordinates, and monitors every agent on your project from a single real-time dashboard -- so your AI tools stop wasting tokens, stop losing context, and start working as a team.

You install it with one command, run groove start, and a GUI opens at localhost:31415. From there, you click to spawn agents, watch them work in a live node graph, chat with them, rotate their context when it degrades, and review quality gates -- all without touching the terminal.

It works with Claude Code, Codex, Gemini CLI, Aider, and Ollama. Any AI coding tool that runs as a process, GROOVE can orchestrate.

The Industry Problem

AI coding agents are powerful individually. But the moment you try to use more than one -- or even run a single long session -- four problems surface:

Token Waste

Every time you start a new AI session, the agent spends hundreds of thousands of tokens re-reading your codebase, re-learning your conventions, re-establishing context. This happens whether you closed the session voluntarily or it crashed. The cost adds up fast across a real project.

Context Degradation

AI models have context windows. As a session runs longer and the window fills up, the model starts compressing older context. Code it wrote an hour ago becomes hazy. Instructions from the beginning of the session get lost. Quality drops off a cliff -- but you can't see it happening until the output goes wrong.

Cold-Start Tax

When you kill a degraded session and start fresh, you're back to square one. The new agent knows nothing about what the last one accomplished. You spend ten minutes explaining what was already done. Multiply that by every session restart across a project, and you've burned a significant chunk of your budget on repetition.

No Coordination

If you have two agents working on the same project -- say, one on the backend and one on the frontend -- they have no idea the other exists. They'll edit the same files, make conflicting assumptions about data shapes, and create merge conflicts you have to untangle by hand. There's no protocol for them to negotiate.

How GROOVE Solves Each One

The Journalist: Zero Cold-Start

GROOVE runs a background synthesis engine called the Journalist. It continuously monitors every agent's activity and maintains two living documents:

• GROOVE_PROJECT_MAP.md -- a real-time map of your entire project: what exists, what changed, what's in progress
• GROOVE_DECISIONS.md -- a log of every architectural decision agents have made and why

When a new agent spawns, it reads these documents and immediately has full project context. No re-explanation. No wasted tokens. The cold-start tax drops to near zero.

Infinite Sessions: Context Rotation

GROOVE monitors each agent's context usage with adaptive thresholds tuned per provider and per role. When it detects an agent approaching the degradation cliff, it:

1. Triggers the Journalist to capture the agent's current state
2. Generates a handoff brief with everything the agent was working on
3. Kills the old session
4. Spawns a fresh session and injects the handoff brief

The result: sessions that are effectively infinite. Quality stays at peak because the context window is always fresh. The agent picks up exactly where it left off, but with a clean slate of attention.

Introduction Protocol: Team Awareness

When you spawn a second agent, GROOVE runs an introduction protocol:

• Every existing agent is notified about the new arrival, its role, and its file scope
• The new agent receives a full briefing on who else is working and what they own
• An AGENTS_REGISTRY.md file is maintained in your project root so agents can reference each other

Agents stop stepping on each other. They know their boundaries.

AI Project Manager: Quality Gates

When you have multiple agents making changes, someone needs to review the risky ones. GROOVE includes a Supervisor that acts as an AI Project Manager:

• Agents running in Auto mode route risky operations through an approval queue
• You review and approve or reject from the GUI's Approvals tab
• Conflict detection flags when agents are about to collide on the same files

You stay in control without micromanaging every agent.

What GROOVE Is

• A process manager -- it spawns and manages AI tool processes on your machine
• A visual dashboard -- a React GUI at localhost:31415 for real-time monitoring and control
• A coordination layer -- introduction protocol, file locks, and approval routing
• A context engine -- the Journalist, context rotation, and adaptive thresholds
• Open source -- FSL-1.1-Apache-2.0 license

What GROOVE Is NOT

Important distinctions

• Not a replacement for Claude Code, Codex, Gemini CLI, or any AI tool. It makes them work better together.
• Not an API proxy -- GROOVE never sends requests to Anthropic, OpenAI, or Google. Your AI tools talk directly to their own servers. GROOVE is fully compliant with all provider terms of service.
• Not an IDE -- it works alongside your existing editor, terminal, and workflow.
• Not another AI model -- it orchestrates existing models, it doesn't replace them.

Works Everywhere

GROOVE is designed to be accessible to anyone who works with AI coding tools:

• Any terminal -- works with the default system terminal, iTerm2, Windows Terminal, tmux, or anything else
• Any IDE -- VS Code, Cursor, JetBrains, Neovim, Emacs, or no IDE at all
• Any OS -- macOS, Linux, Windows (via WSL)
• Any skill level -- the GUI is the primary interface. If you can click a button and fill in a text field, you can orchestrate agents. The CLI is there for power users who want it, but it's not required.

Supported Providers

Provider	Auth	Models
Claude Code	Subscription	Opus, Sonnet, Haiku
Codex	API Key	o3, o4-mini
Gemini CLI	API Key	Pro, Flash
Aider	API Key	Any supported model
Ollama	Local	Any downloaded model

You can mix providers on the same project. Run Claude Code for complex backend work, Gemini for lightweight frontend tasks, and Ollama for local-only operations -- all coordinated through a single dashboard.

Next Steps

• Getting Started -- install and spawn your first agents in under two minutes
• How It Works -- the full architecture and coordination model