Appearance

Getting Started ​

Get GROOVE running and spawn your first coordinated agents in under two minutes.

Prerequisites ​

  • Node.js 20+ -- check with node --version
  • At least one AI coding tool installed -- Claude Code, Codex, Gemini CLI, Aider, or Ollama

Install ​

bash
npm i -g groove-ai

Start GROOVE ​

bash
groove start

This launches the GROOVE daemon and opens the GUI in your default browser at localhost:31415.

First-Run Wizard

The first time you run groove start, GROOVE scans your system for installed AI providers, walks you through configuration, and sets up your project's .groove/ directory. This only happens once.

The GUI at a Glance ​

When the dashboard opens, you'll see four main areas:

The Agent Tree ​

The center of the screen is a real-time node graph powered by React Flow. Each agent you spawn appears as a terminal-style node showing its role, status, provider, model, token usage, and a live heartbeat indicator. Edges between nodes show relationships. Running agents pulse with animated connections.

You can click any node to select it and open its detail panel.

The Spawn Panel ​

Click Spawn Agent to open the spawn modal. Here you configure:

  • Role -- what the agent will do. Presets include backend, frontend, database, devops, planner, and more. Or type a custom role.
  • Provider -- which AI tool to use (Claude Code, Codex, Gemini CLI, Aider, Ollama)
  • Model -- which model to run (e.g., Opus, Sonnet, o3, Pro)
  • Scope -- which files and directories the agent owns (glob patterns like src/api/**)
  • Permissions -- how much autonomy the agent gets:
    • Always Ask -- routes all operations through the approval queue
    • Auto -- handles routine work independently, routes risky operations for approval
    • Full Send -- fully autonomous, no approval gates

The Agent Detail Panel ​

When you select an agent, a sidebar opens with three tabs:

  • Chat -- send instructions to the agent or query it without interrupting its work
  • Stats -- live token heartbeat chart, burn rate, context usage gauge, activity sparkline
  • Actions -- rotate context, stop, delete, clone, change model, modify the system prompt

Tab Navigation ​

Along the top, four tabs give you full-area views:

  • Agents -- the default agent tree and detail panel
  • Tokens -- token usage dashboard with per-agent breakdown and savings metrics
  • Teams -- save, load, and manage team configurations
  • Approvals -- pending approval queue with approve/reject controls

Your First Project ​

Here's a practical walkthrough for a typical project setup.

Step 1: Spawn a Planner ​

The Planner agent reads your codebase and creates a structured plan before any code gets written.

  1. Click Spawn Agent
  2. Set Role to planner
  3. Choose your preferred provider and model (a strong model like Opus or o3 works best for planning)
  4. Leave Scope empty -- the Planner needs to see the whole project
  5. Set Permissions to Auto
  6. Click Spawn

The Planner node appears in the agent tree. It starts analyzing your project and writing a plan. Wait for it to finish -- you'll see its status update in the node.

Step 2: Spawn a Backend Agent ​

Once the Planner has laid out the work:

  1. Click Spawn Agent
  2. Set Role to backend
  3. Set Scope to src/api/**,src/middleware/**,src/models/**
  4. Set Permissions to Auto
  5. Click Spawn

GROOVE's introduction protocol kicks in immediately. The backend agent receives:

  • The current AGENTS_REGISTRY.md listing the Planner and its status
  • The GROOVE_PROJECT_MAP.md with full project context from the Journalist
  • Its assigned file scope so it knows what it owns

Step 3: Spawn a Frontend Agent ​

  1. Click Spawn Agent
  2. Set Role to frontend
  3. Set Scope to src/components/**,src/pages/**,src/styles/**
  4. Set Permissions to Auto
  5. Click Spawn

Now you have three agents working together. The frontend agent knows about both the Planner and the backend agent. It knows which files belong to each role. The agent tree shows all three nodes with their relationships.

Mix Providers

You can use different providers for different agents. For example, run the Planner on Claude Code Opus for deep reasoning, the backend on Claude Code Sonnet for speed, and the frontend on Gemini Pro for cost efficiency. GROOVE coordinates them regardless of provider.

Step 4: Monitor and Interact ​

From the dashboard you can:

  • Watch the agent tree -- nodes update in real-time as agents work. Status bars show running, idle, or completed.
  • Check context usage -- the Stats tab for each agent shows a context gauge. When it fills up, GROOVE will auto-rotate.
  • Send instructions -- click an agent, open the Chat tab, and type a message. The agent receives it as input.
  • Query without interrupting -- use the query feature in the Chat tab to ask an agent a question via a headless call. The agent's main session is not interrupted.
  • Review approvals -- if any agent in Auto mode hits a risky operation, it appears in the Approvals tab. Review and approve or reject.

What Happens Under the Hood ​

When you spawned those three agents, GROOVE did several things automatically:

  1. Daemon registration -- each agent was registered in the in-memory registry with its role, scope, provider, model, and status

  2. Process spawning -- each agent's provider CLI was launched as a child process with the appropriate flags and context

  3. Introduction protocol -- on each spawn, GROOVE updated AGENTS_REGISTRY.md in your project root and notified all existing agents about the new team member

  4. Journalist activation -- the Journalist started monitoring all agent output streams. It synthesizes activity into GROOVE_PROJECT_MAP.md and GROOVE_DECISIONS.md, which live in your project root

  5. Context tracking -- the token tracker began monitoring each agent's token consumption and context window usage

  6. WebSocket broadcasts -- every state change was broadcast to the GUI over WebSocket, keeping the dashboard in real-time sync

The .groove/ directory

GROOVE creates a .groove/ directory in your project root for runtime state, logs, and configuration. Add it to your .gitignore -- it's meant for local use only. The generated markdown files (AGENTS_REGISTRY.md, GROOVE_PROJECT_MAP.md, GROOVE_DECISIONS.md) are placed in the project root and are safe to commit if you want to preserve them.

CLI Alternative ​

Everything you did in the GUI can also be done from the terminal:

bash
# Spawn agents
groove spawn --role planner
groove spawn --role backend --scope "src/api/**"
groove spawn --role frontend --scope "src/components/**"

# Check status
groove agents

# Rotate an agent's context
groove rotate <agent-id>

# Kill a specific agent
groove kill <agent-id>

# Kill all agents and stop the daemon
groove nuke

The CLI and GUI are fully interchangeable -- changes made in one are reflected in the other instantly via WebSocket.

Next Steps ​

FSL-1.1-Apache-2.0

© 2026 Groove AI