groove-dev 0.8.0

package/docs/GUI_DESIGN_SPEC.md

@@ -0,0 +1,402 @@
+# Groove AI — GUI Design Specification
+### Terminal-Native Visual Control Plane
+
+> The GUI should feel like a terminal that happens to have graphics in it — not a website pretending to be a terminal.
+
+---
+
+## Philosophy
+
+This is a TUI-meets-browser hybrid. It runs at `localhost:3141` and is designed to sit inside a terminal multiplexer pane (cmux) alongside real terminal sessions. It should look like it belongs there. No rounded corners on containers, no card shadows, no hover animations, no gradient backgrounds. Think: htop with a React Flow node graph in the center.
+
+---
+
+## Color Palette
+
+Based on One Dark Pro. Every color has a purpose.
+
+### Backgrounds
+| Token | Hex | Usage |
+|---|---|---|
+| `--bg-base` | `#24282f` | Main content area / node graph background |
+| `--bg-chrome` | `#282c34` | Sidebar, header bar, panels |
+| `--bg-surface` | `#2c313a` | Buttons, input fields, card surfaces |
+| `--bg-hover` | `#333842` | Button/row hover state |
+| `--bg-active` | `#3a3f4b` | Active/selected button or tab |
+
+### Text
+| Token | Hex | Usage |
+|---|---|---|
+| `--text-primary` | `#abb2bf` | Default body text, labels |
+| `--text-bright` | `#e6e6e6` | Headings, active items, emphasis |
+| `--text-dim` | `#5c6370` | Secondary info, timestamps, hints |
+| `--text-muted` | `#3e4451` | Disabled text, decorative borders |
+
+### Accent / Status
+| Token | Hex | Usage |
+|---|---|---|
+| `--accent` | `#33afbc` | Brand accent — active nav item, selected node border, primary action |
+| `--green` | `#98c379` | Agent active, success states, healthy status |
+| `--amber` | `#e5c07b` | Agent idle, warning, pending approval |
+| `--red` | `#e06c75` | Agent blocked/error, kill actions, conflicts |
+| `--purple` | `#c678dd` | Journalist activity, context rotation events |
+| `--blue` | `#61afef` | Info badges, links, secondary accent |
+
+---
+
+## Typography
+
+One font. Everywhere. No exceptions.
+
+```
+font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace;
+```
+
+| Element | Size | Weight | Color |
+|---|---|---|---|
+| Header bar title | 13px | 600 | `--text-bright` |
+| Nav buttons | 12px | 500 | `--text-primary` (inactive), `--text-bright` (active) |
+| Node labels | 12px | 600 | `--text-bright` |
+| Node metadata | 11px | 400 | `--text-dim` |
+| Panel headings | 11px | 600 | `--text-dim`, uppercase, letter-spacing 1.5px |
+| Panel body text | 12px | 400 | `--text-primary` |
+| Timestamps | 10px | 400 | `--text-dim` |
+| Status badges | 10px | 600 | Status color, uppercase |
+
+---
+
+## Layout
+
+```
+┌──────────────────────────────────────────────────────┐
+│  HEADER BAR (--bg-chrome, 40px height)              │
+│  [logo]  [Agents] [Tokens] [Teams] [Permissions]    │
+├────────────────────────────────────┬─────────────────┤
+│                                    │                 │
+│         NODE GRAPH                 │   DETAIL PANEL  │
+│         (--bg-base)                │   (--bg-chrome) │
+│                                    │                 │
+│    React Flow canvas with          │   Context for   │
+│    agent nodes and edges           │   selected node │
+│                                    │                 │
+│                                    │                 │
+└────────────────────────────────────┴─────────────────┘
+```
+
+### Header Bar
+- Height: 40px
+- Background: `--bg-chrome`
+- Bottom border: 1px `--text-muted`
+- Logo: Groove infinity icon (16px), left side
+- Nav buttons: right-aligned, evenly spaced
+
+### Node Graph Area
+- Background: `--bg-base`
+- Takes remaining viewport width/height
+- Subtle dot grid pattern: `--text-muted` dots, 20px spacing, 1px size
+- No border, no padding — edge to edge
+
+### Detail Panel (right sidebar)
+- Width: 320px, collapsible
+- Background: `--bg-chrome`
+- Left border: 1px `--text-muted`
+- Shows detail for whatever is selected in the graph
+
+---
+
+## Components
+
+### Nav Buttons (Header)
+
+The four main views: **Agents**, **Tokens**, **Teams**, **Permissions**
+
+```
+Inactive:
+  background: transparent
+  color: --text-primary
+  padding: 6px 14px
+  border: none
+
+Hover:
+  background: --bg-hover
+  color: --text-bright
+
+Active:
+  background: --bg-active
+  color: --text-bright
+  border-bottom: 2px --accent (or underline indicator)
+```
+
+No border-radius. These are terminal tabs, not web buttons.
+
+### Agent Nodes (React Flow)
+
+Each node represents one running agent.
+
+```
+┌─────────────────────────┐
+│ ● backend-1             │  ← status dot + agent name
+│ src/api/**              │  ← file scope
+│ claude-code · 45%       │  ← provider + context usage
+└─────────────────────────┘
+```
+
+| Property | Value |
+|---|---|
+| Background | `--bg-surface` |
+| Border | 1px `--text-muted` |
+| Border (selected) | 1px `--accent` |
+| Border-radius | 2px (barely rounded — terminal feel) |
+| Padding | 10px 12px |
+| Width | 200px |
+| Font | 12px for name, 11px for metadata |
+
+**Status dot** (6px circle, left of agent name):
+- `--green` = active
+- `--amber` = idle / waiting
+- `--red` = blocked / error
+- `--purple` = rotating context
+
+**Context usage bar** (optional, bottom of node):
+- Height: 2px
+- Background: `--text-muted`
+- Fill: `--green` (0-60%), `--amber` (60-80%), `--red` (80-100%)
+
+### Edges (connections between nodes)
+
+- Stroke: `--text-muted`
+- Stroke width: 1px
+- Style: straight or step (not bezier — too soft)
+- Animated dash when data is flowing (introduction events, journalist updates)
+
+### QC Supervisor Node (special)
+
+Same structure as agent node but:
+- Border: 1px `--purple`
+- Label prefix: `[QC]`
+- Always positioned at root/top of the tree
+
+### Status Badges
+
+Small inline badges for agent states.
+
+```
+background: rgba(color, 0.12)
+color: status color
+padding: 2px 6px
+font-size: 10px
+font-weight: 600
+text-transform: uppercase
+letter-spacing: 0.5px
+border-radius: 2px
+```
+
+Examples:
+- `ACTIVE` — green bg tint, green text
+- `IDLE` — amber bg tint, amber text
+- `BLOCKED` — red bg tint, red text
+- `ROTATING` — purple bg tint, purple text
+
+### Token Usage View
+
+Replaces the node graph when "Tokens" tab is active.
+
+```
+┌──────────────────────────────────┐
+│ TOKEN USAGE           this session│
+│                                  │
+│ Total          1,247,893         │
+│ Saved (routing)  412,500  (33%) │
+│ Saved (rotation) 289,100  (23%) │
+│                                  │
+│ AGENT BREAKDOWN                  │
+│ ─────────────────────────────── │
+│ backend-1      482,100   38.6%  │
+│ ████████████████░░░░░░          │
+│ frontend-1     391,200   31.3%  │
+│ ██████████████░░░░░░░░          │
+│ database-1     374,593   30.0%  │
+│ █████████████░░░░░░░░░          │
+└──────────────────────────────────┘
+```
+
+Bar charts use block characters or thin divs:
+- Fill: `--accent`
+- Track: `--text-muted`
+- Height: 3px
+
+Numbers right-aligned, monospace tabular. This should look like a terminal stats output, not a web dashboard.
+
+### Teams View
+
+List of saved team configurations.
+
+```
+┌──────────────────────────────────┐
+│ SAVED TEAMS                      │
+│                                  │
+│ > fullstack          4 agents    │
+│   backend, frontend, db, qc     │
+│   saved 2026-04-05               │
+│                                  │
+│ > api-only           2 agents    │
+│   backend, database              │
+│   saved 2026-04-04               │
+└──────────────────────────────────┘
+```
+
+- `>` prefix for each team (terminal-style list marker)
+- Selected team: `--text-bright` text, `--bg-hover` background
+- Load button: inline, right side, `--accent` text
+
+### Permissions / Approvals View
+
+Pending agent actions requiring human approval.
+
+```
+┌──────────────────────────────────┐
+│ PENDING APPROVALS        2       │
+│                                  │
+│ backend-1 wants to:              │
+│ Edit src/middleware/auth.js      │
+│ "Refactoring auth to use JWT"    │
+│ [APPROVE]  [REJECT]    2m ago   │
+│                                  │
+│ frontend-1 wants to:             │
+│ Create src/components/Modal.jsx  │
+│ "Adding confirmation dialog"     │
+│ [APPROVE]  [REJECT]    45s ago  │
+└──────────────────────────────────┘
+```
+
+Action buttons:
+```
+[APPROVE]:
+  background: rgba(--green, 0.12)
+  color: --green
+  border: 1px rgba(--green, 0.2)
+  padding: 4px 10px
+  font-size: 11px
+
+[REJECT]:
+  background: rgba(--red, 0.12)
+  color: --red
+  border: 1px rgba(--red, 0.2)
+  padding: 4px 10px
+  font-size: 11px
+```
+
+---
+
+## Detail Panel (Right Sidebar)
+
+Shows context for selected agent node.
+
+```
+┌─────────────────────┐
+│ AGENT DETAIL        │
+│                     │
+│ backend-1           │
+│ Status: ACTIVE      │
+│ Provider: claude    │
+│ Context: 45%        │
+│ ████████░░░░░░░░░░ │
+│ Tokens: 482,100     │
+│ Scope:              │
+│   src/api/**        │
+│   src/middleware/**  │
+│ Spawned: 14:20      │
+│ Peers: frontend-1,  │
+│   database-1        │
+│                     │
+│ RECENT ACTIVITY     │
+│ ─────────────────  │
+│ 14:32 editing       │
+│   auth.js           │
+│ 14:28 introduced to │
+│   frontend-1        │
+│ 14:20 spawned       │
+└─────────────────────┘
+```
+
+- Section headers: `--text-dim`, 11px, uppercase, 1.5px letter-spacing
+- Dividers: single line of `─` chars or 1px `--text-muted` border
+- Key labels: `--text-dim`
+- Values: `--text-primary`
+- Agent name: `--text-bright`, 14px, 600 weight
+
+---
+
+## Interaction States
+
+| State | Treatment |
+|---|---|
+| Default | `--bg-surface` background, `--text-primary` text |
+| Hover | `--bg-hover` background, `--text-bright` text |
+| Active/Selected | `--bg-active` background, `--text-bright` text |
+| Focused | 1px `--accent` outline (no glow, no shadow) |
+| Disabled | `--text-muted` text, no hover change |
+
+No transitions longer than 100ms. No easing curves. Instant or near-instant state changes — like a terminal.
+
+---
+
+## What NOT To Do
+
+- No border-radius > 2px anywhere
+- No box-shadow anywhere
+- No gradients anywhere
+- No opacity transitions on hover
+- No font-size larger than 14px (exception: token counter numbers)
+- No sans-serif fonts
+- No rounded buttons
+- No icons — use text labels and ASCII where possible (`●`, `>`, `─`, `█`, `░`)
+- No loading spinners — use text like `loading...` or `syncing...`
+- No toast notifications — use inline status text
+- No modals — use the detail panel or inline expansion
+
+---
+
+## CSS Variables (copy-paste ready)
+
+```css
+:root {
+  /* Backgrounds */
+  --bg-base: #24282f;
+  --bg-chrome: #282c34;
+  --bg-surface: #2c313a;
+  --bg-hover: #333842;
+  --bg-active: #3a3f4b;
+
+  /* Text */
+  --text-primary: #abb2bf;
+  --text-bright: #e6e6e6;
+  --text-dim: #5c6370;
+  --text-muted: #3e4451;
+
+  /* Status */
+  --accent: #33afbc;
+  --green: #98c379;
+  --amber: #e5c07b;
+  --red: #e06c75;
+  --purple: #c678dd;
+  --blue: #61afef;
+
+  /* Typography */
+  --font: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Cascadia Code', Consolas, monospace;
+}
+```
+
+---
+
+## File Reference
+
+- Logo (full): `/groove-logo.png` (800x254, cyan on transparent)
+- Logo (icon): `/favicon.png` (500x500, infinity symbol)
+- Brand accent: `#33afbc`
+- Site: https://grooveai.dev
+- Docs: https://docs.grooveai.dev
+
+---
+
+*This spec is the single source of truth for GUI visual design. If it's not in here, don't add it. If it contradicts a mockup, this document wins.*

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "groove-dev",
+  "version": "0.8.0",
+  "description": "Open-source agent orchestration layer for AI coding tools. GUI dashboard, multi-agent coordination, zero cold-start (Journalist), infinite sessions (adaptive context rotation), AI Project Manager, Quick Launch. Works with Claude Code, Codex, Gemini CLI, Aider, Ollama.",
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "Groove Dev <hello@groovedev.ai> (https://groovedev.ai)",
+  "homepage": "https://groovedev.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grooveai-dev/groove"
+  },
+  "bugs": {
+    "url": "https://github.com/grooveai-dev/groove/issues"
+  },
+  "keywords": [
+    "ai",
+    "ai-agent",
+    "ai-coding",
+    "agent-orchestration",
+    "multi-agent",
+    "claude",
+    "claude-code",
+    "codex",
+    "gemini",
+    "aider",
+    "ollama",
+    "coding-assistant",
+    "developer-tools",
+    "devtools",
+    "context-window",
+    "token-savings",
+    "model-routing",
+    "orchestration",
+    "gui",
+    "dashboard",
+    "process-manager",
+    "llm",
+    "vscode",
+    "terminal"
+  ],
+  "bin": {
+    "groove": "./packages/cli/bin/groove.js"
+  },
+  "workspaces": [
+    "packages/daemon",
+    "packages/cli",
+    "packages/gui"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev:daemon": "npm run dev -w packages/daemon",
+    "dev:gui": "npm run dev -w packages/gui",
+    "build": "npm run build -w packages/gui",
+    "build:gui": "npm run build -w packages/gui",
+    "test": "npm test -w packages/daemon",
+    "prepublishOnly": "npm run build:gui"
+  },
+  "bundledDependencies": [
+    "@groove-dev/daemon",
+    "@groove-dev/cli",
+    "@groove-dev/gui"
+  ],
+  "bundleDependencies": [
+    "@groove-dev/daemon",
+    "@groove-dev/cli",
+    "@groove-dev/gui"
+  ]
+}

package/packages/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.4.0');
+
+program
+  .command('start')
+  .description('Start the GROOVE daemon')
+  .option('-p, --port <port>', 'Port to run on', '31415')
+  .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/packages/cli/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@groove-dev/cli",
+  "version": "0.8.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-dev/daemon": "*",
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  }
+}

package/packages/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:31415';
+
+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/packages/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);
+  }
+}