Agents and Roles

What is an Agent?

An agent is a managed AI coding process. When you spawn an agent, Groove starts a real provider session (e.g., a claude process) with a specific role, scope, and set of instructions. Groove tracks its lifecycle, captures its output, and coordinates it with every other agent in the project.

Agents are not simulated. Each one is a full AI coding session running under your own subscription or API key.

Role Presets

Every agent is assigned a role that defines its focus:

Role	Focus
Backend	Server logic, APIs, databases, middleware
Frontend	UI components, pages, styling, client state
Fullstack	End-to-end features across the stack
Planner	Architecture and planning only — does not write code
Testing	Test suites, coverage, test infrastructure
DevOps	CI/CD, deployment, infrastructure config
Docs	Documentation, READMEs, API references

The Planner Role

The Planner is unique — it produces plans and architectural decisions but never writes production code. Use it to break down large features before spawning builders.

File Scopes

Agents can be assigned file scopes using glob patterns to define ownership:

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

Scopes are tracked by the lock manager. When agents know their boundaries, they avoid stepping on each other's files. Scope violations are flagged in real-time.

Spawning Agents

From the GUI

Open the Spawn Panel, pick a role, select your provider and model, set the permission level, and click spawn. The agent appears in the tree immediately.

From the CLI

groove spawn --role backend
groove spawn --role frontend --scope "src/ui/**" --provider claude-code --model sonnet

Both methods register the agent in the daemon and trigger the introduction protocol.

Agent Lifecycle

Every agent moves through a defined set of states:

starting → running → completed | crashed | killed

• Starting — process is launching, context is being injected
• Running — actively working, stdout being captured
• Completed — finished its task naturally
• Crashed — exited with an error
• Killed — stopped by the user or by a rotation

Dead agents (completed, crashed, killed) remain visible in the registry. You can continue them or remove them.

Communicating with Agents

The Agent Panel in the GUI provides three communication modes:

• Instruct — sends a new task to the agent. This triggers a rotation: the agent is killed and respawned with your instruction and a full handoff brief.
• Query — asks the agent a question using a headless read-only call. The running session is not interrupted. Use this to check on progress or ask about decisions.
• Continue — respawns a dead agent (completed or crashed) with its last context, so it can pick up where it left off.

Query is Non-Disruptive

Query runs a separate headless process that reads the agent's context but never touches its running session. You can query an agent as often as you want without affecting its work.