The Journalist
The Journalist is Groove's background synthesis engine. It watches what every agent does and distills it into living documentation that any agent can read on spawn.
The Cold-Start Problem
Every AI coding session starts the same way: the model spends thousands of tokens rediscovering the project. It reads files, asks about structure, traces dependencies. If you have run five sessions today, you have paid for that discovery five times.
Across the industry, cold-start context re-establishment is one of the largest sources of wasted tokens. It gets worse with teams of agents — each new spawn repeats the same exploration.
How the Journalist Solves It
The Journalist maintains a single file — GROOVE_PROJECT_MAP.md — that contains the full synthesized state of the project. When a new agent spawns, it reads this file and immediately knows:
- What the project is and how it is structured
- What every other agent has done and is currently doing
- What decisions have been made and why
- What files have been created, modified, or deleted
No re-exploration. No wasted tokens. One read and the agent is fully oriented.
Synthesis Cycle
The Journalist runs on two triggers:
- Timer — every 120 seconds while agents are active
- Completion — immediately when any agent finishes its task
Each cycle collects recent agent activity, filters and trims it to fit within a 40K character input budget, and sends it to a Haiku model for synthesis.
What It Produces
GROOVE_PROJECT_MAP.md
A living project map that includes architecture, active work, recent changes, and inter-agent coordination notes. Updated every cycle.
GROOVE_DECISIONS.md
A chronological log of significant decisions made during the session — architectural choices, dependency selections, API design decisions — with reasoning.
Per-Agent Session Logs
Each agent gets a dedicated log capturing its activity. These feed into handoff briefs during context rotation.
What Gets Captured
The Journalist focuses on progress, not exploration. It captures what agents changed, not what they read:
| Event | Captured | Details |
|---|---|---|
| Write/Edit | Yes | File path + diff summary ("bg-gray" -> "HEX.accent") |
| Bash commands | Yes | Command + output snippet (npm test -> 141 passed) |
| Decisions/reasoning | Yes | Thinking blocks over 200 chars |
| Results | Yes | Final output, cost, duration |
| Read/Glob/Grep | No | Exploration noise — excluded from synthesis |
| Transient errors | No | Stderr like ENOENT causes degradation — excluded |
User Feedback Tracking
When you send a message to an agent, the Journalist records it. Future agents see what you said about previous work:
## User Feedback (from previous tasks)
- Command-Frontend (frontend): "the bar color still isn't teal"This prevents agents from repeating mistakes. Feedback persists across daemon restarts in .groove/user-feedback.json.
Decisions Deduplication
The decisions log automatically skips near-duplicate entries. If three synthesis cycles observe the same agent doing the same work, only the first decision entry is kept. The log caps at 20 entries to prevent unbounded growth.
Completed Agent Persistence
Agents that finish their work remain in the project map for 30 minutes. A new agent spawning after a teammate completes will still see what was just built — no context gap.
AI Synthesis
Synthesis is performed by a headless Haiku call (claude -p) with the collected activity as input. The 40K character budget ensures the call stays fast and cheap.
If the AI synthesis fails for any reason, the Journalist falls back to a structural summary built from the raw data — no cycle is ever skipped.
Cost
At Haiku rates, the Journalist costs approximately $0.33 per hour of active use. For context, that is less than the tokens wasted by a single cold-start re-exploration in most projects.
Workspace-Scoped Synthesis
When agents have different working directories, the Journalist organizes its output by workspace. GROOVE_PROJECT_MAP.md gets per-workspace sections instead of a single flat list, and handoff briefs during context rotation only include the relevant workspace's context.
A frontend agent's handoff brief will not contain backend database migration details. Less noise, better context, faster cold starts.
When all agents are at the project root, synthesis behaves as a single flat map -- no configuration needed.
How Agents Use It
When a new agent spawns, its introduction context includes the current project map. During context rotation, the handoff brief references the latest synthesis. The result is that every agent — whether it is the first or the fifteenth — starts with full project awareness.
Integration with Persistent Memory
As of v0.27, handoff briefs do more than snapshot the current agent's session — they prepend the last 3 rotation briefs from the persistent role chain (.groove/memory/handoff-chain/<role>.md). A new backend agent sees what the last three backend agents struggled with, decided, and resolved — not just the session being handed off right now.
This creates causal continuity across rotations. Bug #1 found by agent bk-5 doesn't get rediscovered by bk-6 during their brief; the chain makes the accumulated knowledge explicit. See Persistent Memory for the full shape of the 7th layer.
Overhead Tracking
The Journalist's own synthesis calls — plus the PM approval gate, task negotiator, gateway Q&A, and planner fallback — are all tracked under reserved agent IDs (__journalist__, __pm__, __negotiator__, etc.). Previously invisible 1-6M tokens/day now appear in the dashboard's Intel panel under "GROOVE Overhead" so you can compare coordination cost against coordination savings for an honest ROI picture.