Appearance

How It Works ​

GROOVE is built as three layers: a daemon that manages state and processes, a GUI that provides real-time visual control, and a set of coordination engines that keep agents aware of each other and operating at peak quality.

The Daemon ​

When you run groove start, a Node.js daemon launches on port 31415. This is the brain of the entire system. It stays running in the background and manages everything.

The daemon provides:

  • Registry -- an in-memory store of every active agent: its role, scope, provider, model, status, token usage, and activity history. The registry is an EventEmitter -- any state change triggers broadcasts to all connected clients.
  • REST API -- a full HTTP API at localhost:31415/api/ for spawning, killing, querying, and configuring agents. Every action you take in the GUI or CLI goes through these endpoints.
  • WebSocket -- real-time bidirectional communication. The GUI connects over WebSocket and receives instant updates on every agent state change, journalist synthesis, approval request, and system event.
  • State persistence -- the daemon writes its state to .groove/registry.json on every change. If the daemon restarts, it recovers the full agent registry from disk. Your session survives crashes and reboots.

Localhost Only

The daemon binds to 127.0.0.1 by default -- it's not accessible from the network. CORS is restricted to localhost origins. WebSocket connections verify their origin. This is secure by design.

The GUI ​

The GUI is a React application served directly by the daemon at localhost:31415. There's nothing extra to install or run -- opening the URL in your browser gives you the full dashboard.

It connects to the daemon over WebSocket on load and stays in real-time sync. Every agent spawn, status change, context rotation, and Journalist synthesis appears instantly in the interface.

The GUI is built with:

  • React 19 + Vite 6 for the application framework
  • Zustand for state management, synced with WebSocket events
  • React Flow (@xyflow/react) for the interactive agent tree visualization
  • Canvas-based charts for live token heartbeat and activity sparklines

The GUI is the primary interface. While the CLI covers every operation, the GUI provides visibility that a terminal cannot: live node graphs, context gauges, token burn rates, and one-click actions.

Spawning Agents ​

When you spawn an agent -- whether from the GUI's Spawn Panel or the CLI -- the daemon executes a precise sequence:

1. Registration ​

The daemon creates an entry in the registry with the agent's configuration: role, scope (glob patterns for file ownership), provider, model, and permission level.

2. Process Launch ​

The daemon uses the appropriate provider adapter to build the spawn command. Each supported provider has its own adapter that knows how to:

  • Construct the correct CLI invocation
  • Inject role context and system prompts
  • Parse output streams for token counting and status detection

The agent process is launched as a child process. Stdout is captured for the Journalist and token tracker.

3. Role Presets ​

GROOVE includes built-in presets for common roles: backend, frontend, database, devops, planner, designer, and more. Each preset configures:

  • A system prompt tuned for that role
  • Suggested file scopes
  • Recommended permission levels

You can also define fully custom roles with your own prompts and scopes.

4. Permission Levels ​

Every agent runs under one of three permission modes:

ModeBehavior
Always AskEvery operation is routed to the approval queue. You review everything.
AutoRoutine operations proceed independently. Risky operations (destructive file changes, external commands) are routed to the AI Project Manager for review.
Full SendFully autonomous. The agent operates without any approval gates.

Introduction Protocol ​

The introduction protocol is what turns isolated agents into a coordinated team. It runs every time a new agent joins.

What Happens ​

When agent N+1 spawns:

  1. Registry update -- the daemon writes AGENTS_REGISTRY.md to your project root. This file lists every active agent, its role, scope, status, and what it's currently working on.

  2. Existing agent notification -- every already-running agent receives a notification about the new arrival. They learn who joined, what role they're filling, and which files they own.

  3. New agent briefing -- the new agent receives the full AGENTS_REGISTRY.md plus context from the Journalist's living documents. It starts with complete awareness of the project and the team.

Project Files Section ​

The introduction protocol injects a dedicated GROOVE section into each agent's context. This section includes:

  • The team roster with roles and scopes
  • File ownership boundaries
  • Active conflicts or pending negotiations
  • Links to the Journalist's project map and decisions log

Agents reference this section when deciding what to touch and what to leave alone.

Team Awareness in Practice ​

This means an agent spawned as frontend with scope src/components/** will:

  • Know that a backend agent owns src/api/**
  • Avoid editing backend files even if it could
  • Reference the decisions log to understand API contracts the backend agent established
  • Coordinate through the registry if it needs something from another agent's domain

The Journalist ​

The Journalist is GROOVE's synthesis engine. It runs in the background and maintains a living picture of your entire project.

How It Works ​

The Journalist monitors the stdout streams of all active agents using stream-json parsing. It filters for meaningful activity: file changes, decisions made, errors encountered, tasks completed.

On configurable triggers, it runs a headless AI call (using claude -p with API key authentication) to synthesize everything it has observed into structured documentation.

What It Produces ​

GROOVE_PROJECT_MAP.md -- a continuously updated map of your project. What files exist, what they do, what has changed recently, what is currently in progress. When a new agent spawns, it reads this document and skips the entire "understand the codebase" phase.

GROOVE_DECISIONS.md -- a log of architectural and implementation decisions agents have made. Why a particular database schema was chosen. Why an API endpoint uses POST instead of PUT. Why a component was split into two. This prevents later agents from revisiting settled questions.

Per-agent session logs -- detailed activity logs for each agent's session, stored in .groove/logs/. These feed into context rotation handoff briefs.

Trigger Conditions ​

The Journalist activates when:

  • A configurable time interval elapses (default: 5 minutes of agent activity)
  • An agent completes a significant task
  • A context rotation is about to happen (to capture state before the handoff)
  • You manually trigger it from the GUI's Journalist feed

Why This Matters ​

The Journalist is the mechanism that eliminates cold-start tax. Without it, every new agent or rotated session would spend thousands of tokens re-reading your codebase. With it, agents arrive pre-briefed and productive from their first token.

The Journalist Uses API Keys

The Journalist's headless synthesis calls use API key authentication, not your Claude Code subscription. This is a separate, lightweight cost. The tokens it spends are a fraction of what cold starts would cost without it.

Context Rotation ​

Context rotation is how GROOVE gives you effectively infinite sessions without context degradation.

The Problem It Solves ​

Every AI model has a context window. As a session accumulates tokens, the model starts compressing earlier context through summarization. After enough turns, the model's understanding of its own earlier work becomes unreliable. Output quality drops.

Most users don't notice the degradation until something goes visibly wrong -- a hallucinated function name, a forgotten constraint, duplicated code. By then, significant tokens have been wasted on low-quality output.

How Rotation Works ​

GROOVE tracks each agent's context consumption and applies adaptive thresholds tuned per provider and per role.

  1. Monitoring -- the token tracker watches each agent's accumulated context usage in real-time. The GUI shows this as a context gauge on each agent's Stats tab.

  2. Threshold detection -- when usage approaches the degradation threshold (which adapts based on observed session quality), GROOVE prepares for rotation.

  3. Handoff brief generation -- the Journalist captures the agent's current state: what it was working on, what it completed, what's pending, any open questions. This becomes a structured handoff document.

  4. Kill and respawn -- the old session is killed. A fresh session is spawned with the same role, scope, and configuration, plus the handoff brief injected as initial context.

  5. Seamless continuation -- the new session picks up exactly where the old one left off, but with a fresh context window operating at peak quality.

Adaptive Thresholds ​

GROOVE doesn't use a fixed rotation point. The adaptive engine tracks session quality scores (0-100) and adjusts thresholds:

  • If a session performed well before rotation, the threshold nudges up (+2%) -- it can run a bit longer next time
  • If quality dropped before rotation was triggered, the threshold nudges down (-5%) -- rotate sooner next time
  • Thresholds converge over time to the optimal rotation point for each provider/role combination

This means GROOVE learns the sweet spot for your specific usage patterns.

AI Project Manager ​

The AI Project Manager is GROOVE's quality gate system, implemented by the Supervisor component.

When It Activates ​

The AI Project Manager operates on agents running in Auto permission mode. It monitors their operations and intercepts ones that are flagged as risky:

  • Destructive file operations (deleting files, overwriting large sections)
  • External command execution
  • Changes outside an agent's declared scope
  • Operations that conflict with another agent's active work

The Approval Queue ​

Intercepted operations appear in the GUI's Approvals tab. Each approval request shows:

  • Which agent is requesting
  • What operation it wants to perform
  • Why it was flagged
  • The relevant context

You review the request and click Approve or Reject. The agent receives the decision and proceeds or backs off accordingly.

Auto-QC Scaling ​

When you have 4 or more agents running simultaneously, the Supervisor automatically activates enhanced quality checks. More agents means more potential for conflicts, so GROOVE tightens oversight proportionally.

Conflict Detection ​

The Supervisor maintains a conflict log at GROOVE_CONFLICTS.md. When two agents attempt to modify overlapping files, the conflict is recorded and flagged. The agents receive notifications about the conflict and can negotiate resolution through the knock protocol.

Coordination: The Knock Protocol ​

When agents have overlapping concerns -- for example, a frontend agent needs to know about an API change the backend agent just made -- GROOVE facilitates coordination through the knock protocol.

How It Works ​

  1. Detection -- the lock manager or Supervisor detects that two agents' work areas overlap or that one agent needs information from another's domain.

  2. Negotiation -- GROOVE mediates a brief exchange where the agents share relevant context about the overlap.

  3. Resolution -- agents adjust their plans based on the negotiation. The outcome is logged in the decisions document.

Duplicate Role Handling ​

If you spawn two agents with the same role (e.g., two backend agents), GROOVE initiates task negotiation. The agents divide their work areas to avoid duplication. This is useful for large codebases where a single agent can't cover an entire domain efficiently.

System Architecture ​

                    Browser (GUI)
                        |
                    WebSocket + HTTP
                        |
        ┌───────────────────────────────────┐
        |        GROOVE Daemon (:31415)     |
        |                                   |
        |  Registry ---- StateManager       |
        |     |                             |
        |  ProcessManager -- Providers      |
        |     |              (claude-code,  |
        |  Introducer        codex, gemini, |
        |     |              aider, ollama) |
        |  LockManager                      |
        |     |                             |
        |  Supervisor --- Approvals         |
        |     |                             |
        |  Journalist --- TokenTracker      |
        |     |              |              |
        |  Rotator ------- Adaptive         |
        |     |                             |
        |  Router -------- Classifier       |
        |                                   |
        └───────────────┬───────────────────┘
                        |
            ┌───────────┼───────────┐
            |           |           |
         Agent 1     Agent 2     Agent 3
        (claude)    (codex)     (gemini)
            |           |           |
        Anthropic    OpenAI      Google
        servers      servers     servers

Each agent process communicates directly with its provider's servers. GROOVE never intercepts, proxies, or modifies those communications. It coordinates at the process level only.

Next Steps ​

FSL-1.1-Apache-2.0

© 2026 Groove AI