Configuration

groove uses a .groove/config.json file in your project root for per-project configuration. Edit it directly or use the CLI.

groove config show        # view current config
groove config set <k> <v> # change a value

Default Configuration

{
  "version": "0.3.0",
  "port": 31415,
  "journalistInterval": 120,
  "rotationThreshold": 0.75,
  "autoRotation": true,
  "qcThreshold": 4,
  "maxAgents": 10,
  "defaultProvider": "claude-code",
  "safety": {
    "autoRotate": true,
    "tokenCeilingPerAgent": 5000000
  }
}

Options

version

Config schema version. Managed automatically -- do not edit.

port

Daemon port for the REST API, WebSocket, and GUI. Default: 31415.

groove config set port 31415

journalistInterval

How often the Journalist runs a synthesis cycle, in seconds. Default: 120 (2 minutes).

groove config set journalistInterval 120

Lower values give fresher context documents but consume more headless API calls. For active multi-agent sessions, 120 seconds is a good balance. For solo agent work, consider raising to 300.

rotationThreshold

Context usage percentage that triggers auto-rotation. Default: 0.75 (75%).

groove config set rotationThreshold 0.75

This is the base threshold. groove's adaptive engine adjusts the actual trigger per provider and per role based on session quality scoring. The value here sets the starting point.

autoRotation

Enable or disable automatic context rotation. Default: true.

groove config set autoRotation true

When false, agents will continue running past the threshold until you manually rotate them via the GUI or groove rotate <id>.

qcThreshold

Number of active agents that triggers automatic QC supervisor spawn. Default: 4.

groove config set qcThreshold 4

When you hit this many agents, groove spawns a supervisor agent that reviews risky operations and routes them through the approval queue.

maxAgents

Maximum number of agents that can run simultaneously. Default: 10.

groove config set maxAgents 10

defaultProvider

The default AI provider for new agents. Default: "claude-code".

groove config set defaultProvider claude-code

Available values: claude-code, codex, gemini, ollama.

Safety (Self-Healing Rotation)

One safety net: per-instance token ceiling with role-based multipliers. Catches genuinely runaway agents without false-positiving legitimate heavy work.

safety.autoRotate

Enable or disable the safety net. Default: true.

When false, Groove still detects ceiling breaches but only broadcasts them — no automatic rotation. Useful for debugging, not recommended in production.

safety.tokenCeilingPerAgent

Base maximum tokens an agent can consume in a single instance before auto-rotation fires with reason token_limit_exceeded. Default: 5000000 (5M).

The ceiling is scoped to the agent's current instance since spawn — tokens carried over from prior rotations don't count toward this limit, so a rotated agent starts fresh.

The effective ceiling is tokenCeilingPerAgent × roleMultiplier. A planner (10×) gets 50M; a backend agent (1×) gets 5M.

safety.roleMultipliers

Per-role ceiling multipliers. Override any role with safety.roleMultipliers: { "backend": 2 } to double the ceiling for backend agents. Defaults:

Role	Default multiplier
planner	10
analyst	5
fullstack	4
security	4
docs	1
any other role	1

Velocity trigger removed in v0.27.2

Earlier versions had safety.velocityWindowSeconds and safety.velocityTokenThreshold for an earlier-warning trigger. These were removed because they produced false positives on legitimate heavy exploration. The token ceiling is the single safety net.