Workspaces and Large Codebases

AI coding agents fail on large codebases. Context fills with irrelevant code, agents lose direction in thousands of files, and every new spawn wastes tokens re-exploring structure they will never touch. Groove solves this by giving each agent its own slice of the project.

The Problem

In a monorepo with a frontend, backend, and shared library, a frontend agent does not need to see database migrations. A backend agent does not need React components in its context. But without scoping, every agent loads everything and gets confused.

The result: agents make changes in wrong directories, duplicate work across boundaries, and burn tokens orienting themselves in code that is not relevant to their task.

Working Directories

Every agent can be assigned a working directory. The agent's process spawns inside that directory — it starts there and its context is naturally focused on that subtree.

mysite/
├── packages/frontend/     <-- Frontend agent's cwd
│   ├── src/
│   └── package.json
├── packages/backend/      <-- Backend agent's cwd
│   ├── src/
│   └── package.json
├── packages/shared/       <-- Fullstack agent can access
└── ARCHITECTURE.md        <-- Everyone reads this

From the GUI

Open the Spawn Panel, click + advanced options, and set the Working Directory field to a relative path like packages/frontend. If Groove detected workspaces in your project, they appear as quick-pick buttons below the input.

From the CLI

groove spawn --role frontend --working-dir packages/frontend
groove spawn --role backend --working-dir packages/backend

From the Planner

When a planner agent analyzes a monorepo, it includes workingDir in its recommended team configuration. The Quick Launch system spawns each agent in the correct directory automatically.

Default Behavior

When no working directory is set, agents spawn at the project root — exactly how Groove has always worked. This is a non-breaking addition.

Codebase Indexing

On startup, Groove scans your project structure and builds a codebase index. This gives every agent instant orientation without spending tokens exploring the file tree.

The indexer detects:

• npm/yarn workspaces — workspaces field in package.json
• pnpm workspaces — pnpm-workspace.yaml
• Lerna monorepos — lerna.json
• Multi-package projects — multiple package.json files at depth 1-2

The result is stored in .groove/codebase-index.json and injected into every agent's introduction context.

What Agents Receive

Instead of exploring the project structure themselves, agents get a compact summary on spawn:

Project: mysite (847 files, 42 directories)

Workspaces (3):
- packages/frontend/ — @mysite/frontend (124 files, 8 subdirs)
- packages/backend/ — @mysite/backend (89 files, 6 subdirs)
- packages/shared/ — @mysite/shared (31 files, 3 subdirs)

Key files:
- package.json
- ARCHITECTURE.md
- packages/frontend/package.json
- packages/backend/package.json
- packages/shared/package.json

This replaces thousands of tokens of file-tree exploration with a single, instant read.

Architecture Injection

If your project has an ARCHITECTURE.md file at the root, Groove automatically injects it into every agent's context. This gives all agents a shared understanding of the system — conventions, API contracts, directory layout — without you needing to paste it into every prompt.

Groove checks for architecture documentation in this order:

1. ARCHITECTURE.md (project root)
2. docs/architecture.md
3. .github/ARCHITECTURE.md

The first match is injected, truncated to 5,000 characters to stay within a reasonable context budget.

Write an ARCHITECTURE.md

If you work on a large codebase and don't have one yet, write a brief ARCHITECTURE.md describing the directory structure, key patterns, and conventions. It pays for itself immediately — every agent that spawns will make better decisions because of it.

Per-Workspace Journalist

The Journalist adapts to workspace-scoped agents. When agents have different working directories, synthesis output is organized by workspace:

• GROOVE_PROJECT_MAP.md is sectioned by workspace instead of one flat list
• 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

When all agents are at the project root, the Journalist behaves exactly as before — a single flat project map.

Putting It Together

A typical workflow on a large codebase:

1. Start Groove — the indexer scans and detects your workspaces
2. Spawn a Planner — it reads the codebase index and recommends a team with correct working directories
3. Quick Launch — one click spawns all agents, each in its own subdirectory
4. Agents work in isolation — frontend and backend agents see only their own code
5. The Journalist tracks by workspace — handoff briefs stay focused and relevant
6. Coordination when needed — if an agent needs a change in another workspace, it writes to .groove/coordination.md and the right agent picks it up

API Reference

Spawn with Working Directory

POST /api/agents
{
  "role": "frontend",
  "workingDir": "packages/frontend",
  "scope": ["src/components/**", "src/pages/**"],
  "prompt": "Build the checkout flow"
}

Codebase Indexer

GET /api/indexer              # Index status
GET /api/indexer/workspaces   # Detected workspaces
POST /api/indexer/rescan      # Re-scan the project