Infinite Sessions
Context rotation is how Groove gives you effectively infinite AI coding sessions. Instead of letting sessions degrade, Groove detects the decline, captures full state, and respawns with perfect context.
The Degradation Problem
Every AI coding session follows the same arc. Early on, the model is sharp — fast, accurate, focused. As the context window fills, quality drops. You start seeing:
- Hallucinated file paths and function names
- Circular refactors — changing code back and forth without progress
- Lost direction — forgetting the original task
- Increased tool failures and retries
Most developers restart manually when they notice this. By then, significant tokens have been wasted, and the new session loses all the context the old one built up.
How Infinite Sessions Work
Groove automates the entire cycle:
- Monitor — track degradation signals from the running agent
- Detect — identify when quality has dropped below the adaptive threshold
- Capture — trigger the Journalist to snapshot current state
- Rotate — kill the old session, spawn a fresh one with a handoff brief
- Continue — the new session picks up exactly where the old one left off
The agent never loses context. The session is effectively infinite.
Degradation Signals
Groove tracks five categories of degradation in a sliding 50-event classifier window:
| Signal | What It Measures |
|---|---|
| Error count and trend | Rising error rates indicate context confusion |
| File churn | Repeatedly modifying the same files signals circular work |
| Repetitions | Duplicate tool calls or repeated explanations |
| Tool failures | Failed reads, writes, or commands |
| Scope violations | Touching files outside the agent's assigned scope |
These signals are combined into a session score from 0 to 100, where 100 is a perfectly healthy session.
Adaptive Thresholds
Rotation thresholds are not static. They adapt per provider and per role:
- Each provider/role combination maintains its own threshold
- After each rotation, the threshold is adjusted: +2% if the session scored well (rotation was premature), -5% if it scored poorly (rotation was late)
- Thresholds are persisted to disk and survive daemon restarts
- Over time, thresholds converge to the optimal point for each combination
Convergence
After enough rotations, thresholds stabilize. Groove will rotate Claude Code backend agents at a different point than Gemini CLI frontend agents, because each combination degrades differently.
The Handoff Brief
When rotation triggers, the new agent receives a handoff brief containing:
- Agent identity — role, scope, original task
- Recent tool calls — what the agent was doing in its final moments
- Results — files created and modified, outcomes achieved
- Project map — the latest Journalist synthesis (up to 10K characters)
- Original task — the instruction that started the session
The new agent reads this brief and continues seamlessly.
Natural Pause Detection
Groove is aware of each model's context limits (Opus 1M, Sonnet/Haiku 200K) and factors them into rotation timing. It will not rotate an agent mid-action — it waits for a natural pause before triggering, preventing corruption from interrupted operations.
Safety-Triggered Rotation
Beyond degradation detection, Groove has a self-healing safety trigger to catch genuinely runaway agents — unbounded context expansion, stuck loops that somehow evade quality detection. It's a last-resort net, not a primary control.
Token Ceiling
When an agent consumes more tokens than safety.tokenCeilingPerAgent (default 5,000,000) × the role multiplier in a single instance, the rotator fires a token_limit_exceeded rotation. Tokens carried from prior rotations don't count — the ceiling is scoped to this specific agent instance since it spawned.
Role multipliers scale the ceiling for exploration-heavy roles so they don't trip on legitimate heavy work:
| Role | Multiplier | Effective ceiling |
|---|---|---|
| planner | 10× | 50M |
| analyst | 5× | 25M |
| fullstack / security | 4× | 20M |
| docs | 1× | 5M |
| default (backend, frontend, etc.) | 1× | 5M |
Override any role via safety.roleMultipliers in config.
Bypasses Cooldown
Safety triggers skip the 5-minute rotation cooldown. Degradation rotations wait for stabilization; pathological burn does not get the courtesy of patience.
Velocity trigger removed in v0.27.2
An earlier velocity-based trigger (tokens-per-minute threshold) was removed because it produced false positives on legitimate heavy exploration — a planner reading a real codebase could trip it on normal work. Velocity alone is a bad stuck-loop signal; what actually distinguishes a runaway from real work is speed combined with non-productivity (repetitions, errors, file churn). If a pattern emerges from real usage that warrants earlier warning, it'll be re-added gated on quality signals.
Measurement
Every rotation captures pre-rotation velocity. After the new agent has 10 minutes of data, Groove measures post-rotation velocity and stores the velocityDelta in rotation history — this is the signal used to replace the old hardcoded savings coefficient with a real measurement over time.
Configurability
All three thresholds are configurable in .groove/config.json under the safety key. Set safety.autoRotate: false to disable enforcement entirely (broadcast-only mode). See config reference.
Self-Healing by Design
Safety rotations are fully automatic — no modal, no user intervention, no dropped work. The agent just respawns with a handoff brief and keeps going. Your dashboard will show a red T: or orange V: badge on the rotation timeline so you can see what happened.
Rotation Cooldown
A 5-minute cooldown prevents back-to-back rotations from the same agent when quality stays low post-rotation (e.g., the task is genuinely hard). Safety triggers bypass the cooldown; degradation triggers respect it.
Converged Thresholds
Once an adaptive threshold for a provider:role pair stabilizes (last 10 adjustments < 1% change), Groove trusts it. Quality rotations for converged profiles require a deeper score drop before firing — if the threshold has settled, it's probably right.
Manual Rotation
You can always trigger rotation manually from the GUI or CLI with groove rotate <id>.