groove-ai 0.1.0

package/CLAUDE.md

@@ -0,0 +1,89 @@
+# GROOVE — Agent Orchestration Layer
+
+> Spawn fast. Stay aware. Never lose context.
+
+## What This Is
+
+GROOVE is a lightweight, open-source agent orchestration layer for AI coding tools. It is a **process manager** — it spawns, coordinates, and monitors AI coding agents. It does NOT wrap, proxy, or impersonate any AI API.
+
+## Architecture
+
+```
+groove/
+├── packages/
+│   ├── daemon/     — Node.js daemon (port 3141) — the brain
+│   ├── cli/        — `groove` CLI commands
+│   └── gui/        — React + Vite GUI (served by daemon)
+├── CLAUDE.md       — this file
+└── LICENSE         — FSL-1.1-Apache-2.0
+```
+
+### Daemon Components
+
+- **Registry** (`registry.js`) — in-memory agent state store, EventEmitter for changes
+- **API** (`api.js`) — REST endpoints + WebSocket broadcasts
+- **ProcessManager** (`process.js`) — spawn/kill agent processes, stdout capture
+- **StateManager** (`state.js`) — persist/recover state across daemon restarts
+- **Introducer** (`introducer.js`) — generates AGENTS_REGISTRY.md, injects team context
+- **LockManager** (`lockmanager.js`) — file scope ownership, conflict detection
+- **Supervisor** (`supervisor.js`) — QC approval routing
+- **Journalist** (`journalist.js`) — background context synthesis engine
+- **TokenTracker** (`tokentracker.js`) — per-agent token accounting
+
+### Providers
+
+Provider abstraction in `providers/base.js`. Each provider implements: `isInstalled()`, `buildSpawnCommand()`, `buildHeadlessCommand()`, `parseOutput()`.
+
+Day 1: Claude Code (`providers/claude-code.js`). Future: Codex, Gemini, Aider, Ollama.
+
+### Terminal Adapters
+
+`terminal/base.js` — interface. `terminal/generic.js` — fallback (background processes).
+
+## Tech Stack
+
+- Node.js (ESM, `"type": "module"`)
+- npm workspaces (monorepo)
+- Express + ws (daemon server)
+- React 19 + Vite 6 (GUI)
+- Zustand (GUI state)
+- React Flow / @xyflow/react (agent tree visualization)
+- commander + chalk (CLI)
+
+## Conventions
+
+- All files use ESM (`import`/`export`)
+- License header on every source file: `// FSL-1.1-Apache-2.0 — see LICENSE`
+- Port 3141 for daemon (REST + WebSocket + GUI)
+- `.groove/` directory in project root for runtime state (gitignored)
+- Generated markdown files: `AGENTS_REGISTRY.md`, `GROOVE_PROJECT_MAP.md`, `GROOVE_DECISIONS.md`
+
+## Compliance (CRITICAL)
+
+GROOVE is a process manager, NOT a harness. Hard rules:
+1. **Never touch OAuth tokens** — each `claude` process manages its own auth
+2. **Never impersonate Claude Code** — GROOVE doesn't send HTTP requests to Anthropic
+3. **Never proxy API calls** — all AI requests flow directly from provider CLI to provider servers
+4. **The Journalist uses API key auth** for headless `claude -p` calls
+5. **One subscription = one user** — never share subscriptions
+
+## CLI Commands
+
+```
+groove start              — start daemon
+groove stop               — stop daemon
+groove spawn --role <r>   — spawn an agent
+groove kill <id>          — kill an agent
+groove agents             — list agents
+groove status             — daemon status
+groove nuke               — kill all + stop
+```
+
+## Build Phases
+
+- **Phase 0** — Scaffolding (this) ✓
+- **Phase 1** — Core daemon + CLI (working spawn/kill/coordinate)
+- **Phase 2** — GUI (React Flow agent tree)
+- **Phase 3** — Journalist + Context Rotation
+- **Phase 4** — Teams (saved agent configs)
+- **Phase 5** — Provider ecosystem + adaptive model routing

package/LICENSE

@@ -0,0 +1,40 @@
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+Abbreviation
+
+    FSL-1.1-Apache-2.0
+
+Notice
+
+    Copyright 2026 Rok (GROOVE)
+
+Terms and Conditions
+
+Licensor:             Rok (GROOVE)
+Software:             GROOVE — Agent Orchestration Layer
+Use Limitation:       Any use that competes with the Software, including
+                      offering a commercial product or service whose value
+                      derives, entirely or substantially, from the Software's
+                      functionality.
+
+License Grant. Subject to the Use Limitation, Licensor grants you a
+non-exclusive, worldwide, royalty-free license to use, copy, modify, and
+distribute the Software.
+
+Change License.       Apache License, Version 2.0
+Change Date:          Two years from the date of each version release.
+
+On the Change Date, or the fourth anniversary of the first publicly available
+distribution of a specific version of the Software under this License,
+whichever comes first, the above license grant and Use Limitation will be
+replaced with the Change License.
+
+You must conspicuously display this License on each copy of the Software or
+a portion thereof, and the following notice:
+
+    This software is licensed under the Functional Source License, Version 1.1,
+    Apache 2.0 Future License. See LICENSE for details.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

package/README.md

@@ -0,0 +1,104 @@
+# GROOVE
+
+**Orchestrate your AI coding agents. Stop losing context.**
+
+Coordinate multiple AI agents, eliminate cold-start, and save 40-60% on tokens.
+
+[![npm](https://img.shields.io/npm/v/groove-ai)](https://www.npmjs.com/package/groove-ai)
+[![License](https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue)](LICENSE)
+
+---
+
+## Quick Start
+
+```bash
+npm i -g groove-ai
+groove start
+groove spawn --role backend --prompt "Build the auth API"
+groove spawn --role frontend --prompt "Build the login page"
+groove agents
+```
+
+## What GROOVE Does
+
+GROOVE is a **process manager** for AI coding agents. It does not wrap or proxy any AI API — it spawns actual AI tool processes (`claude`, `codex`, `aider`, etc.) and adds:
+
+- **Team awareness** — agents know about each other and their file scopes
+- **File conflict prevention** — scoped ownership prevents agents from stepping on each other
+- **The Journalist** — background AI that synthesizes what agents are doing into living documentation
+- **Context rotation** — kills agents approaching context limits and respawns them with fresh context + handoff brief
+- **Adaptive thresholds** — learns the optimal rotation point per provider, per role
+- **Teams** — save/load agent configurations like Docker Compose for AI agents
+- **Model routing** — automatically routes tasks to the cheapest model that can handle them
+
+## Architecture
+
+```
+┌─────────────┐  ┌─────────┐  ┌──────────────┐
+│  groove CLI  │  │   GUI   │  │ Agent Panes  │
+└──────┬──────┘  └────┬────┘  └──────┬───────┘
+       │              │              │
+       ▼              ▼              ▼
+  ┌────────────────────────────────────────┐
+  │           GROOVE DAEMON (:3141)         │
+  │                                        │
+  │  Registry · Introducer · Lock Manager  │
+  │  Journalist · Rotator · Supervisor     │
+  │  Classifier · Router · Teams           │
+  └───────────────────┬────────────────────┘
+                      │
+  ┌───────────────────▼────────────────────┐
+  │  Providers: Claude Code · Codex ·       │
+  │  Gemini · Aider · Ollama (local)       │
+  └────────────────────────────────────────┘
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `groove start` | Start the daemon |
+| `groove spawn --role <role>` | Spawn an agent |
+| `groove agents` | List all agents |
+| `groove kill <id>` | Kill an agent |
+| `groove rotate <id>` | Rotate an agent (fresh context) |
+| `groove team save <name>` | Save current agents as a team |
+| `groove team load <name>` | Load and spawn a saved team |
+| `groove providers` | List available AI providers |
+| `groove set-key <provider> <key>` | Set API key |
+| `groove config show` | Show configuration |
+| `groove status` | Daemon status |
+| `groove nuke` | Kill everything |
+
+## GUI
+
+Open `http://localhost:3141` after starting the daemon. Features:
+
+- Agent tree visualization (React Flow)
+- Spawn modal with role presets and provider selection
+- Agent detail sidebar with activity log
+- Context usage bars per agent
+- Token dashboard with savings calculator
+- Journalist feed with live synthesis
+- Team management
+- Approval queue for out-of-scope access
+
+## Providers
+
+| Provider | Auth | Models | Hot-Swap |
+|----------|------|--------|----------|
+| Claude Code | Subscription | Opus, Sonnet, Haiku | Yes |
+| Codex | API Key | o3, o4-mini | No |
+| Gemini CLI | API Key | Pro, Flash | No |
+| Aider | API Key | Any | Yes |
+| Ollama | Local | Any | No |
+
+## Compliance
+
+GROOVE is a **process manager**, not a harness. It spawns actual AI tool binaries — it never touches OAuth tokens, never proxies API calls, and never impersonates any client.
+
+## Links
+
+- **Website:** [grooveai.dev](https://grooveai.dev)
+- **Docs:** [docs.grooveai.dev](https://docs.grooveai.dev)
+- **License:** [FSL-1.1-Apache-2.0](LICENSE) (converts to Apache 2.0 after 2 years)

package/node_modules/@groove-ai/cli/bin/groove.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+// GROOVE CLI — Entry Point
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import { program } from 'commander';
+import { start } from '../src/commands/start.js';
+import { stop } from '../src/commands/stop.js';
+import { spawn } from '../src/commands/spawn.js';
+import { kill } from '../src/commands/kill.js';
+import { agents } from '../src/commands/agents.js';
+import { status } from '../src/commands/status.js';
+import { nuke } from '../src/commands/nuke.js';
+import { rotate } from '../src/commands/rotate.js';
+import { teamSave, teamLoad, teamList, teamDelete, teamExport, teamImport } from '../src/commands/team.js';
+import { approvals, approve, reject } from '../src/commands/approve.js';
+import { providers, setKey } from '../src/commands/providers.js';
+import { configShow, configSet } from '../src/commands/config.js';
+
+program
+  .name('groove')
+  .description('Agent orchestration layer for AI coding tools')
+  .version('0.1.0');
+
+program
+  .command('start')
+  .description('Start the GROOVE daemon')
+  .option('-p, --port <port>', 'Port to run on', '3141')
+  .action(start);
+
+program
+  .command('stop')
+  .description('Stop the GROOVE daemon')
+  .action(stop);
+
+program
+  .command('spawn')
+  .description('Spawn a new AI agent')
+  .option('-r, --role <role>', 'Agent role (e.g., backend, frontend, devops)')
+  .option('-s, --scope <patterns...>', 'File scope patterns')
+  .option('-p, --provider <provider>', 'AI provider', 'claude-code')
+  .option('-m, --model <model>', 'Model to use')
+  .option('--prompt <prompt>', 'Initial prompt for the agent')
+  .action(spawn);
+
+program
+  .command('kill <id>')
+  .description('Kill a running agent')
+  .action(kill);
+
+program
+  .command('agents')
+  .description('List all agents')
+  .action(agents);
+
+program
+  .command('status')
+  .description('Show daemon status')
+  .action(status);
+
+program
+  .command('nuke')
+  .description('Kill all agents and stop the daemon')
+  .action(nuke);
+
+program
+  .command('rotate <id>')
+  .description('Rotate an agent (kill + respawn with fresh context)')
+  .action(rotate);
+
+// Teams
+const team = program.command('team').description('Manage saved agent teams');
+team.command('save <name>').description('Save current agents as a team').action(teamSave);
+team.command('load <name>').description('Load and spawn a saved team').action(teamLoad);
+team.command('list').description('List saved teams').action(teamList);
+team.command('delete <name>').description('Delete a saved team').action(teamDelete);
+team.command('export <name>').description('Export team as JSON').action(teamExport);
+team.command('import <file>').description('Import team from JSON file').action(teamImport);
+
+// Approvals
+program.command('approvals').description('List pending approvals').action(approvals);
+program.command('approve <id>').description('Approve a pending request').action(approve);
+program
+  .command('reject <id>')
+  .description('Reject a pending request')
+  .option('--reason <reason>', 'Rejection reason')
+  .action(reject);
+
+// Providers
+program.command('providers').description('List available AI providers').action(providers);
+program.command('set-key <provider> <key>').description('Set API key for a provider').action(setKey);
+
+// Config
+const config = program.command('config').description('View and modify configuration');
+config.command('show').description('Show current configuration').action(configShow);
+config.command('set <key> <value>').description('Set a configuration value').action(configSet);
+
+program.parse();

package/node_modules/@groove-ai/cli/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@groove-ai/cli",
+  "version": "0.1.0",
+  "description": "GROOVE CLI — manage AI coding agents from your terminal",
+  "license": "FSL-1.1-Apache-2.0",
+  "type": "module",
+  "bin": {
+    "groove": "./bin/groove.js"
+  },
+  "dependencies": {
+    "@groove-ai/daemon": "*",
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  }
+}

package/node_modules/@groove-ai/cli/src/client.js

@@ -0,0 +1,25 @@
+// GROOVE CLI — HTTP client for daemon communication
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+const BASE_URL = process.env.GROOVE_URL || 'http://localhost:3141';
+
+export async function apiCall(method, path, body) {
+  const url = `${BASE_URL}${path}`;
+  const options = {
+    method,
+    headers: { 'Content-Type': 'application/json' },
+  };
+
+  if (body) {
+    options.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, options);
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: res.statusText }));
+    throw new Error(err.error || `HTTP ${res.status}`);
+  }
+
+  return res.json();
+}

package/node_modules/@groove-ai/cli/src/commands/agents.js

@@ -0,0 +1,38 @@
+// GROOVE CLI — agents command
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+const STATUS_COLORS = {
+  running: 'green',
+  starting: 'yellow',
+  stopped: 'gray',
+  crashed: 'red',
+  completed: 'cyan',
+};
+
+export async function agents() {
+  try {
+    const list = await apiCall('GET', '/api/agents');
+
+    if (list.length === 0) {
+      console.log(chalk.dim('No agents running. Use `groove spawn` to start one.'));
+      return;
+    }
+
+    console.log(chalk.bold(`\n  GROOVE Agents (${list.length})\n`));
+
+    for (const a of list) {
+      const color = STATUS_COLORS[a.status] || 'white';
+      const statusBadge = chalk[color](`[${a.status}]`);
+      console.log(`  ${chalk.bold(a.name)} ${statusBadge}  ${chalk.dim(a.id)}`);
+      console.log(`    Role: ${a.role}  Provider: ${a.provider}  Scope: ${a.scope.join(', ') || '-'}`);
+      console.log(`    Tokens: ${a.tokensUsed}  Context: ${Math.round(a.contextUsage * 100)}%`);
+      console.log();
+    }
+  } catch {
+    console.error(chalk.red('Cannot connect to daemon. Is it running? Try: groove start'));
+    process.exit(1);
+  }
+}

package/node_modules/@groove-ai/cli/src/commands/approve.js

@@ -0,0 +1,50 @@
+// GROOVE CLI — approve/reject commands
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+export async function approvals() {
+  try {
+    const { pending, status } = await apiCall('GET', '/api/approvals');
+
+    if (pending.length === 0) {
+      console.log(chalk.dim('  No pending approvals.'));
+      return;
+    }
+
+    console.log(chalk.bold(`\n  Pending Approvals (${pending.length})\n`));
+    for (const a of pending) {
+      console.log(`  ${chalk.yellow(a.id)}`);
+      console.log(`    Agent: ${a.agentName}`);
+      console.log(`    Action: ${a.action?.description || a.action?.type || 'unknown'}`);
+      console.log(`    Time: ${new Date(a.requestedAt).toLocaleTimeString()}`);
+      console.log('');
+    }
+  } catch {
+    console.error(chalk.red('  Cannot connect to daemon.'));
+    process.exit(1);
+  }
+}
+
+export async function approve(id) {
+  try {
+    const result = await apiCall('POST', `/api/approvals/${id}/approve`);
+    console.log(chalk.green('  Approved:'), result.id);
+  } catch (err) {
+    console.error(chalk.red('  Failed:'), err.message);
+    process.exit(1);
+  }
+}
+
+export async function reject(id, options) {
+  try {
+    const result = await apiCall('POST', `/api/approvals/${id}/reject`, {
+      reason: options.reason || '',
+    });
+    console.log(chalk.green('  Rejected:'), result.id);
+  } catch (err) {
+    console.error(chalk.red('  Failed:'), err.message);
+    process.exit(1);
+  }
+}

package/node_modules/@groove-ai/cli/src/commands/config.js

@@ -0,0 +1,35 @@
+// GROOVE CLI — config command
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+export async function configShow() {
+  try {
+    const status = await apiCall('GET', '/api/config');
+    console.log(chalk.bold('\n  GROOVE Configuration\n'));
+    for (const [key, value] of Object.entries(status)) {
+      console.log(`  ${chalk.dim(key.padEnd(24))} ${chalk.white(JSON.stringify(value))}`);
+    }
+    console.log('');
+  } catch {
+    console.error(chalk.red('  Cannot connect to daemon.'));
+    process.exit(1);
+  }
+}
+
+export async function configSet(key, value) {
+  try {
+    // Auto-parse numbers and booleans
+    let parsed = value;
+    if (value === 'true') parsed = true;
+    else if (value === 'false') parsed = false;
+    else if (!isNaN(value) && value !== '') parsed = Number(value);
+
+    await apiCall('PATCH', '/api/config', { [key]: parsed });
+    console.log(chalk.green(`  Set ${key} = ${JSON.stringify(parsed)}`));
+  } catch (err) {
+    console.error(chalk.red('  Failed:'), err.message);
+    process.exit(1);
+  }
+}

package/node_modules/@groove-ai/cli/src/commands/kill.js

@@ -0,0 +1,15 @@
+// GROOVE CLI — kill command
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+export async function kill(id) {
+  try {
+    await apiCall('DELETE', `/api/agents/${id}`);
+    console.log(chalk.green('Killed agent:'), id);
+  } catch (err) {
+    console.error(chalk.red('Failed to kill:'), err.message);
+    process.exit(1);
+  }
+}

package/node_modules/@groove-ai/cli/src/commands/nuke.js

@@ -0,0 +1,19 @@
+// GROOVE CLI — nuke command
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+export async function nuke() {
+  try {
+    console.log(chalk.yellow('Nuking all agents...'));
+    await apiCall('DELETE', '/api/agents');
+
+    const status = await apiCall('GET', '/api/status');
+    process.kill(status.pid, 'SIGTERM');
+
+    console.log(chalk.green('All agents killed. Daemon stopped.'));
+  } catch {
+    console.log(chalk.yellow('No running daemon found.'));
+  }
+}

package/node_modules/@groove-ai/cli/src/commands/providers.js

@@ -0,0 +1,40 @@
+// GROOVE CLI — providers command
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+export async function providers() {
+  try {
+    const list = await apiCall('GET', '/api/providers');
+
+    console.log(chalk.bold('\n  Available Providers\n'));
+
+    for (const p of list) {
+      const installed = p.installed ? chalk.green('installed') : chalk.red('not installed');
+      const authed = p.authType === 'local' || p.authType === 'subscription'
+        ? ''
+        : p.hasKey ? chalk.green(' (key set)') : chalk.yellow(' (no key)');
+
+      console.log(`  ${chalk.bold(p.name.padEnd(18))} ${installed}${authed}`);
+      console.log(`    Auth: ${p.authType}  Models: ${p.models.map(m => m.name).join(', ')}`);
+      if (!p.installed) {
+        console.log(`    Install: ${chalk.dim(p.installCommand)}`);
+      }
+      console.log('');
+    }
+  } catch {
+    console.error(chalk.red('  Cannot connect to daemon.'));
+    process.exit(1);
+  }
+}
+
+export async function setKey(provider, key) {
+  try {
+    const result = await apiCall('POST', `/api/credentials/${provider}`, { key });
+    console.log(chalk.green(`  Key set for ${provider}:`), result.masked);
+  } catch (err) {
+    console.error(chalk.red('  Failed:'), err.message);
+    process.exit(1);
+  }
+}

package/node_modules/@groove-ai/cli/src/commands/rotate.js

@@ -0,0 +1,16 @@
+// GROOVE CLI — rotate command
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import chalk from 'chalk';
+import { apiCall } from '../client.js';
+
+export async function rotate(id) {
+  try {
+    console.log(chalk.yellow(`  Rotating agent ${id}...`));
+    const newAgent = await apiCall('POST', `/api/agents/${id}/rotate`);
+    console.log(chalk.green(`  Rotated.`), `New session: ${chalk.bold(newAgent.name)} (${newAgent.id})`);
+  } catch (err) {
+    console.error(chalk.red('  Rotation failed:'), err.message);
+    process.exit(1);
+  }
+}