How It Works

The Daemon

When you run groove start, a Node.js daemon launches on port 3141. It manages:

• Registry — in-memory store of all active agents, their roles, scopes, and status
• WebSocket — real-time broadcasts to the GUI and CLI
• REST API — endpoints for spawning, killing, and querying agents
• State persistence — survives daemon restarts via .groove/registry.json

Spawning Agents

groove spawn --role backend --scope "src/api/**"

When you spawn an agent:

1. The daemon registers it in the registry
2. A provider process (e.g., claude) is started with the role context
3. The introduction protocol runs — existing agents are notified
4. AGENTS_REGISTRY.md is updated in the project root
5. The GUI tree updates in real-time

The Introduction Protocol

When agent #2 spawns, the daemon:

• Writes AGENTS_REGISTRY.md with all active agents and their scopes
• Notifies existing agents about the new arrival
• Gives the new agent a full context brief on spawn

This ensures every agent knows who else is working and what files they own.

File Locks

Groove prevents conflicts through scoped file ownership:

groove spawn --role backend --scope "src/api/**,src/middleware/**"
groove spawn --role frontend --scope "src/components/**,src/pages/**"

Agents are aware of their boundaries. The lock manager tracks ownership and flags violations before they happen.

The Journalist

The core innovation. A background process that:

1. Tails all active agent stdout streams
2. Runs on a configurable interval (default: 5 minutes)
3. Synthesizes activity into living documentation
4. Updates GROOVE_PROJECT_MAP.md and GROOVE_DECISIONS.md

When a new agent spawns, it reads PROJECT_MAP.md and immediately knows the full project state. No re-explanation needed.

Context Rotation

Context windows degrade over time. Groove monitors usage and auto-rotates:

1. Detects when an agent's context is approaching degradation threshold
2. Triggers the Journalist to capture current state
3. Kills the old session
4. Spawns a fresh session with full context handoff

Quality stays at 100%. Sessions are effectively infinite.