grov 0.5.4 → 0.5.6

package/README.md

@@ -6,6 +6,8 @@
 
 <p align="center"><strong>Collective AI memory for engineering teams.</strong></p>
 
+<p align="center"><em>When one dev's Claude figures something out, every dev's Claude knows it.</em></p>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/grov"><img src="https://img.shields.io/npm/v/grov" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/grov"><img src="https://img.shields.io/npm/dm/grov" alt="npm downloads"></a>
@@ -17,35 +19,47 @@
   <a href="https://grov.dev">Website</a> •
   <a href="https://app.grov.dev">Dashboard</a> •
   <a href="#quick-start">Quick Start</a> •
-  <a href="#team-sync">Team Sync</a> •
+  <a href="#features">Features</a> •
   <a href="#contributing">Contributing</a>
 </p>
 
-Grov gives your team a shared AI memory.
+---
 
 ## The Problem
 
-Every time you start a new Claude Code session:
-- Claude re-explores your codebase from scratch
-- It reads the same files again
-- It rediscovers patterns you've already established
-- You burn tokens on redundant exploration
-
-**Measured impact:** A typical task takes 10+ minutes, 7%+ token usage, and 3+ explore agents just to understand the codebase.*
+Your team's AI agents are learning in silos.
 
-## The Solution
+- Dev A's Claude spends 10 minutes understanding your auth system
+- Dev B's Claude does the exact same exploration the next day
+- Dev C asks a question that was already answered last week
+- Every new session starts from zero
 
-Grov captures what Claude learns and injects it back on the next session.
+**The waste:** Redundant exploration, duplicate token spend, knowledge that disappears when sessions end.
 
-![grov demo](demo-converted.gif)
+## The Solution
 
-### What Gets Captured
+Grov captures what your team's AI learns and shares it automatically.
 
-Real reasoning, not just file lists:
+```
+Dev A: "How does auth work in this codebase?"
+        ↓
+     Claude investigates, figures it out
+        ↓
+     Grov captures the reasoning + decisions
+        ↓
+     Syncs to team dashboard
+        ↓
+Dev B: "Should we add password salting?"
+        ↓
+     Claude already knows: "Based on verified team knowledge,
+     no - this codebase uses OAuth-only, no passwords stored"
+        ↓
+     No exploration needed. Instant expert answer.
+```
 
-![captured reasoning](docs/reasoning-output.jpeg)
+**Measured impact:** Tasks drop from 10+ minutes to 1-2 minutes when team context is available.
 
-*Architectural decisions, patterns, and rationale - automatically extracted.*
+---
 
 ## Quick Start
 
@@ -57,83 +71,60 @@ grov proxy            # Start (keep running)
 
 Then use Claude Code normally in another terminal. That's it.
 
-## How It Works
-
-```
-Session 1: Claude learns about your auth system
-           ↓
-        grov captures: "Auth tokens refresh in middleware/token.ts:45,
-                        using 15-min window to handle long forms"
-           ↓
-Session 2: User asks about related feature
-           ↓
-        grov injects: Previous context about auth
-           ↓
-        Claude skips exploration, reads files directly
-```
-
-## Commands
-
+For team sync:
 ```bash
-grov init         # Configure proxy URL (one-time)
-grov proxy        # Start the proxy (required)
-grov proxy-status # Show active sessions
-grov status       # Show captured tasks
-grov login        # Login to cloud dashboard
-grov sync         # Sync memories to team dashboard
-grov disable      # Disable grov
+grov login                    # Authenticate via GitHub
+grov sync --enable --team ID  # Enable sync for your team
 ```
 
-## Data Storage
+**Free for individuals and teams up to 3 developers.**
 
-- **Database:** `~/.grov/memory.db` (SQLite)
-- **Per-project:** Context is filtered by project path
-- **Local by default:** Memories stay on your machine unless you enable team sync
+---
 
-### Why Sync to Dashboard?
+## What Gets Captured
 
-Local memories work great for solo use. The dashboard unlocks:
+Real reasoning, not just file lists:
 
-- **Search across all sessions** - Hybrid semantic + keyword search
-- **Team sharing** - What one dev's AI learns, everyone's AI knows
-- **Cross-device sync** - Switch machines without losing context
-- **Browse & manage** - Visual interface for all captured reasoning
+![Dashboard showing captured reasoning](dashboard-showcase.jpeg)
 
-[Open Dashboard](https://app.grov.dev)
+*Architectural decisions, patterns, and rationale - automatically extracted and synced to your team.*
 
-## Team Sync
+Every captured memory includes:
+- **Reasoning trace** - The WHY behind decisions (CONCLUSION/INSIGHT pairs)
+- **Key decisions** - What was chosen and why alternatives were rejected
+- **Files touched** - Which parts of the codebase are relevant
+- **Constraints discovered** - What can't break, what must stay compatible
 
-Share memories across your engineering team with the cloud dashboard.
+---
 
-```bash
-grov login                    # Authenticate via GitHub
-grov sync --enable --team ID  # Enable sync for a team
-```
+## What Your Team Gets
 
-Once enabled, memories automatically sync to [app.grov.dev](https://app.grov.dev) where your team can:
-- Browse all captured reasoning
-- **Hybrid search** - semantic (AI understands meaning) + lexical (keyword matching)
-- Invite team members
-- See who learned what
+When a teammate asks a related question, Claude already knows:
 
-Memories sync automatically when sessions complete - no manual intervention needed.
+![Claude using team knowledge](cli-showcase.jpeg)
 
-## Requirements
+*No exploration. No re-investigation. Instant expert answers from team memory.*
 
-- Node.js 18+
-- Claude Code
+Claude receives verified context and skips the exploration phase entirely - no "let me investigate" or "I'll need to look at the codebase."
 
 ---
 
-## Advanced Features
+## Features
 
-### Anti-Drift Detection
+### Team Knowledge Sharing
+The core value: what one dev's AI learns, everyone's AI knows.
+
+- **Automatic capture** - Reasoning extracted when tasks complete
+- **Automatic sync** - Memories sync to your team in real-time
+- **Automatic injection** - Relevant context injected into new sessions
+- **Hybrid search** - Semantic (AI understands meaning) + lexical (keyword matching)
 
-Grov monitors what Claude **does** (not what you ask) and corrects if it drifts from your goal.
+### Anti-Drift Detection
+Grov monitors what Claude **does** (not what you ask) and corrects when it goes off-track.
 
 - Extracts your intent from the first prompt
 - Monitors Claude's actions (file edits, commands, explorations)
-- Uses Claude Haiku to score alignment (1-10)
+- Scores alignment (1-10) using Claude Haiku
 - Injects corrections at 4 levels: nudge → correct → intervene → halt
 
 ```bash
@@ -141,25 +132,85 @@ Grov monitors what Claude **does** (not what you ask) and corrects if it drifts
 grov drift-test "refactor the auth system" --goal "fix login bug"
 ```
 
-### Extended Cache (Experimental)
-
-Anthropic's prompt cache expires after 5 minutes of inactivity. If you pause to think between prompts, the cache expires and must be recreated (costs more, takes longer).
+### Extended Cache
+Anthropic's prompt cache expires after 5 minutes of inactivity. Grov keeps it warm.
 
 ```bash
 grov proxy --extended-cache
 ```
 
-**What this does:** Sends minimal keep-alive requests (~$0.002 each) during idle periods to preserve your cache.
+- Sends minimal keep-alive requests (~$0.002 each) during idle periods
+- Saves ~$0.18 per idle period by avoiding cache recreation
+- Your next prompt is faster and cheaper
+
+**Opt-in only.** By using `--extended-cache`, you consent to Grov making API requests on your behalf.
+
+### Auto-Compaction
+When your context window fills up, Grov automatically compacts while preserving what matters.
+
+- Pre-computes summary at 85% capacity
+- Preserves: original goal, key decisions with reasoning, current state, next steps
+- Drops: verbose exploration, redundant file reads, superseded reasoning
+- Claude continues seamlessly without losing important context
+
+No manual `/compact` needed. No lost reasoning.
+
+---
+
+## Commands
+
+```bash
+grov init         # Configure proxy URL (one-time)
+grov proxy        # Start the proxy (required)
+grov proxy-status # Show active sessions
+grov status       # Show captured tasks
+grov login        # Login to cloud dashboard
+grov sync         # Sync memories to team dashboard
+grov disable      # Disable grov
+grov drift-test   # Test drift detection
+```
+
+---
 
-**Important:** By using `--extended-cache`, you consent to Grov making API requests on your behalf to keep the cache active. These requests:
-- Use your Anthropic API key
-- Are sent automatically during idle periods (every ~4 minutes)
-- Cost approximately $0.002 per keep-alive
-- Are discarded (not added to your conversation)
+## How It Works
 
-This feature is **disabled by default** and requires explicit opt-in.
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Claude Code                                                │
+│       │                                                     │
+│       ▼                                                     │
+│  Grov Proxy (localhost:8080)                                │
+│       │                                                     │
+│       ├──► Inject team memory from past sessions            │
+│       ├──► Forward to Anthropic API                         │
+│       ├──► Monitor for drift, inject corrections            │
+│       ├──► Track context usage, auto-compact if needed      │
+│       └──► Capture reasoning when task completes            │
+│                    │                                        │
+│                    ▼                                        │
+│              Team Dashboard (app.grov.dev)                  │
+│                    │                                        │
+│                    ▼                                        │
+│              Available to entire team                       │
+└─────────────────────────────────────────────────────────────┘
+```
 
-### Environment Variables
+**Local by default:** Memories stay on your machine in `~/.grov/memory.db` (SQLite) unless you enable team sync.
+
+---
+
+## Dashboard
+
+Browse, search, and manage your team's AI knowledge at [app.grov.dev](https://app.grov.dev).
+
+- **Search across all sessions** - Hybrid semantic + keyword search
+- **Browse reasoning traces** - See the WHY behind every decision
+- **Team visibility** - See who learned what, when
+- **Invite teammates** - Share knowledge automatically
+
+---
+
+## Environment Variables
 
 ```bash
 # Required for drift detection and LLM extraction
@@ -171,45 +222,21 @@ export PROXY_HOST=127.0.0.1                        # Proxy host
 export PROXY_PORT=8080                             # Proxy port
 ```
 
-Without an API key, grov uses basic extraction and disables drift detection.
-
-### What Gets Stored
-
-```json
-{
-  "task": "Fix auth logout bug",
-  "goal": "Prevent random user logouts",
-  "files_touched": ["src/auth/session.ts", "src/middleware/token.ts"],
-  "reasoning_trace": [
-    "Investigated token refresh logic",
-    "Found refresh window was too short",
-    "Extended from 5min to 15min"
-  ],
-  "status": "complete"
-}
-```
+Without an API key, Grov uses basic extraction and disables drift detection.
 
-### What Gets Injected
+---
 
-```
-VERIFIED CONTEXT FROM PREVIOUS SESSIONS:
+## Requirements
 
-[Task: Fix auth logout bug]
-- Files: session.ts, token.ts
-- Extended token refresh window from 5min to 15min
-- Reason: Users were getting logged out during long forms
+- Node.js 18+
+- Claude Code
 
-YOU MAY SKIP EXPLORE AGENTS for files mentioned above.
-```
+---
 
-### How the Proxy Works
+## Pricing
 
-1. **`grov init`** sets `ANTHROPIC_BASE_URL=http://127.0.0.1:8080` in Claude's settings
-2. **`grov proxy`** intercepts all API calls and:
-   - Extracts intent from first prompt
-   - Injects context from team memory
-   - Tracks actions and detects drift
-   - Saves reasoning when tasks complete
+- **Free** - Individuals and teams up to 3 developers
+- **Team** - Larger teams with additional features (coming soon)
 
 ---
 
@@ -222,8 +249,12 @@ YOU MAY SKIP EXPLORE AGENTS for files mentioned above.
 - [x] Team sync (cloud backend)
 - [x] Web dashboard
 - [x] Hybrid search (semantic + lexical)
+- [x] Extended cache (keep prompt cache warm)
+- [x] Auto-compaction with reasoning preservation
 - [ ] VS Code extension
 
+---
+
 ## Contributing
 
 1. **Fork the repo** and clone locally
@@ -238,6 +269,8 @@ node dist/cli.js init    # Test CLI
 
 Found a bug? [Open an issue](https://github.com/TonyStef/Grov/issues).
 
+---
+
 ## License
 
 Apache License 2.0 - see [LICENSE](LICENSE) file for details.

package/dist/cli.js

@@ -127,4 +127,12 @@ program
     const { sync } = await import('./commands/sync.js');
     await sync(options);
 }));
+// grov doctor - Diagnose setup issues
+program
+    .command('doctor')
+    .description('Check grov setup and diagnose issues')
+    .action(safeAction(async () => {
+    const { doctor } = await import('./commands/doctor.js');
+    await doctor();
+}));
 program.parse();

package/dist/commands/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctor(): Promise<void>;

package/dist/commands/doctor.js

@@ -0,0 +1,88 @@
+// grov doctor - Check setup and diagnose issues
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { request } from 'undici';
+import { readCredentials, getSyncStatus } from '../lib/credentials.js';
+import { initDatabase } from '../lib/store/database.js';
+const CLAUDE_SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
+const DB_PATH = join(homedir(), '.grov', 'memory.db');
+export async function doctor() {
+    console.log('\nGrov Doctor');
+    console.log('===========\n');
+    // Check proxy
+    const proxyRunning = await checkProxy();
+    printCheck('Proxy', proxyRunning, 'Running on port 8080', 'Not running', 'grov proxy');
+    // Check Claude settings
+    const baseUrlConfigured = checkBaseUrl();
+    printCheck('ANTHROPIC_BASE_URL', baseUrlConfigured, 'Configured for proxy', 'Not configured', 'grov init');
+    // Check API key
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    const hasApiKey = !!(apiKey && apiKey.length > 10);
+    const apiKeyFix = process.platform === 'win32'
+        ? 'set ANTHROPIC_API_KEY=sk-ant-...'
+        : 'export ANTHROPIC_API_KEY=sk-ant-... (add to shell profile)';
+    printCheck('ANTHROPIC_API_KEY', hasApiKey, 'Set', 'Not set (task detection disabled)', apiKeyFix);
+    // Check login
+    const creds = readCredentials();
+    printCheck('Login', !!creds, creds ? `Logged in as ${creds.email}` : 'Not logged in', 'Not logged in', 'grov login');
+    // Check sync
+    const syncStatus = getSyncStatus();
+    const syncOk = syncStatus?.enabled && syncStatus?.teamId;
+    const syncMsg = syncOk
+        ? `Team ${syncStatus.teamId.substring(0, 8)}...`
+        : syncStatus?.teamId ? 'Disabled' : 'No team';
+    printCheck('Cloud Sync', !!syncOk, syncMsg, syncMsg, 'grov sync --enable --team <id>');
+    // Check database
+    const dbStats = checkDatabase();
+    const dbOk = dbStats.tasks > 0 || dbStats.sessions > 0;
+    const dbMsg = `${dbStats.tasks} tasks, ${dbStats.unsynced} unsynced, ${dbStats.sessions} active`;
+    printCheck('Local Database', dbOk, dbMsg, 'Empty', 'Use Claude Code with proxy running');
+    console.log('');
+}
+async function checkProxy() {
+    try {
+        const res = await request('http://127.0.0.1:8080/health', {
+            headersTimeout: 2000,
+            bodyTimeout: 2000
+        });
+        return res.statusCode === 200;
+    }
+    catch {
+        return false;
+    }
+}
+function checkBaseUrl() {
+    if (!existsSync(CLAUDE_SETTINGS_PATH))
+        return false;
+    try {
+        const settings = JSON.parse(readFileSync(CLAUDE_SETTINGS_PATH, 'utf-8'));
+        return settings.env?.ANTHROPIC_BASE_URL === 'http://127.0.0.1:8080';
+    }
+    catch {
+        return false;
+    }
+}
+function checkDatabase() {
+    if (!existsSync(DB_PATH)) {
+        return { tasks: 0, unsynced: 0, sessions: 0 };
+    }
+    try {
+        const db = initDatabase();
+        const tasks = db.prepare('SELECT COUNT(*) as c FROM tasks').get().c;
+        const unsynced = db.prepare('SELECT COUNT(*) as c FROM tasks WHERE synced_at IS NULL').get().c;
+        const sessions = db.prepare("SELECT COUNT(*) as c FROM session_states WHERE status = 'active'").get().c;
+        return { tasks, unsynced, sessions };
+    }
+    catch {
+        return { tasks: 0, unsynced: 0, sessions: 0 };
+    }
+}
+function printCheck(name, ok, successMsg, failMsg, fix) {
+    const icon = ok ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    const msg = ok ? successMsg : failMsg;
+    console.log(`${icon} ${name}: ${msg}`);
+    if (!ok) {
+        console.log(`  \x1b[90m→ ${fix}\x1b[0m`);
+    }
+}

package/dist/commands/login.js

@@ -1,8 +1,24 @@
 // Login command - Device authorization flow
 // Authenticates CLI with Grov cloud using OAuth-like device flow
 import open from 'open';
-import { writeCredentials, isAuthenticated, readCredentials } from '../lib/credentials.js';
-import { startDeviceFlow, pollDeviceFlow, sleep } from '../lib/api-client.js';
+import * as readline from 'readline';
+import { writeCredentials, isAuthenticated, readCredentials, setTeamId, setSyncEnabled } from '../lib/credentials.js';
+import { startDeviceFlow, pollDeviceFlow, sleep, fetchTeams } from '../lib/api-client.js';
+/**
+ * Prompt user for input
+ */
+function prompt(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase());
+        });
+    });
+}
 /**
  * Decode JWT payload to extract user info
  */
@@ -91,16 +107,54 @@ export async function login() {
                 email: userInfo.email,
                 sync_enabled: false,
             });
-            console.log('╔═════════════════════════════════════════╗');
-            console.log('║                                         ║');
-            console.log('║   Successfully logged in!               ║');
-            console.log('║                                         ║');
-            console.log('╚═════════════════════════════════════════╝');
-            console.log(`\nLogged in as: ${userInfo.email}\n`);
-            console.log('Next steps:');
-            console.log('  1. Run "grov sync --status" to check sync settings');
-            console.log('  2. Run "grov sync --enable --team <team-id>" to enable sync');
-            console.log('  3. Run "grov status" to view local memories\n');
+            console.log('\n✓ Logged in as:', userInfo.email);
+            // Auto-setup: Fetch teams and configure sync
+            console.log('\nSetting up cloud sync...');
+            try {
+                const teams = await fetchTeams();
+                if (teams.length === 0) {
+                    console.log('\n⚠ No teams found.');
+                    console.log('Create one at: https://app.grov.dev/team');
+                    console.log('Then run: grov sync --enable --team <team-id>\n');
+                    return;
+                }
+                let selectedTeam = teams[0];
+                // If multiple teams, let user choose
+                if (teams.length > 1) {
+                    console.log('\nYour teams:');
+                    teams.forEach((team, i) => {
+                        console.log(`  ${i + 1}. ${team.name} (${team.slug})`);
+                    });
+                    const choice = await prompt(`\nSelect team [1-${teams.length}] (default: 1): `);
+                    const index = parseInt(choice, 10) - 1;
+                    if (index >= 0 && index < teams.length) {
+                        selectedTeam = teams[index];
+                    }
+                }
+                // Ask to enable sync (default yes)
+                const enableSync = await prompt(`Enable cloud sync to "${selectedTeam.name}"? [Y/n]: `);
+                if (enableSync !== 'n' && enableSync !== 'no') {
+                    setTeamId(selectedTeam.id);
+                    setSyncEnabled(true);
+                    console.log('\n╔═════════════════════════════════════════╗');
+                    console.log('║                                         ║');
+                    console.log('║   ✓ Cloud sync enabled!                 ║');
+                    console.log('║                                         ║');
+                    console.log('╚═════════════════════════════════════════╝');
+                    console.log(`\nSyncing to: ${selectedTeam.name}`);
+                    console.log('\nYou\'re all set! Your AI sessions will now be saved.');
+                    console.log('View them at: https://app.grov.dev/memories\n');
+                }
+                else {
+                    console.log('\n✓ Logged in. Sync not enabled.');
+                    console.log('Run "grov sync --enable" later to start syncing.\n');
+                }
+            }
+            catch (err) {
+                console.log('\n⚠ Could not auto-configure sync.');
+                console.log('Run "grov sync --enable --team <team-id>" manually.');
+                console.log('Find your team ID at: https://app.grov.dev/team\n');
+            }
             return;
         }
         if (status === 'expired') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grov",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Collective AI memory for Claude Code - captures reasoning from sessions and injects context into future sessions",
   "type": "module",
   "main": "dist/cli.js",