@rulecatch/ai-pooler 0.4.0

package/README.md

@@ -0,0 +1,232 @@
+# @rulecatch/ai-pooler
+
+AI development analytics for Claude Code, Cursor, and other AI coding assistants.
+
+Track your AI-assisted development sessions: tool usage, code changes, productivity patterns, and costs.
+
+**Privacy-first by design**: Zero-knowledge encryption means we literally cannot read your personal data.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @rulecatch/ai-pooler
+
+# Set up automatic tracking
+rulecatch init --api-key=YOUR_KEY --project-id=my-project
+```
+
+That's it! All your Claude Code sessions will now be tracked automatically.
+
+## Privacy & Security
+
+We take your privacy seriously. Rulecatch uses **zero-knowledge architecture** - we cannot read your personal data even if we wanted to.
+
+### Zero-Knowledge Encryption
+
+```bash
+# Optional: Enable zero-knowledge privacy mode
+rulecatch privacy setup --region=eu
+```
+
+When enabled:
+- **Your privacy key** is created and stored locally (never sent to us)
+- **All PII is hashed** before leaving your machine (emails, usernames, file paths)
+- **You choose your data region** (US or EU) - client routes data accordingly
+- **We only see hashes** - cryptographically impossible to reverse
+
+### What This Means
+
+| Data Type | Without Privacy Mode | With Privacy Mode |
+|-----------|---------------------|-------------------|
+| Email | `user@example.com` | `a7f3b2c1...` (hash) |
+| Git username | `RuleCatchUser` | `e9d4f1a8...` (hash) |
+| File paths | `/home/user/project/secret.ts` | `b2c3d4e5...` (hash) |
+| Tool calls | `Read`, `Edit`, `Bash` | `Read`, `Edit`, `Bash` (unchanged) |
+| Token counts | `15,234` | `15,234` (unchanged) |
+
+### GDPR Compliance
+
+- **EU Data Residency**: Use `--region=eu` to store data in Frankfurt, Germany
+- **Right to Deletion**: Delete all your data anytime from the dashboard
+- **Right to Access**: Export all your data in machine-readable format
+- **Data Minimization**: We only collect what's needed for analytics
+- **Client-Side Control**: Your machine decides where data goes, not us
+
+### Privacy Commands
+
+```bash
+# Set up privacy with EU data residency
+rulecatch privacy setup --region=eu
+
+# Check privacy status
+rulecatch privacy status
+
+# Verify your privacy key
+rulecatch privacy verify
+
+# Export key for hooks (required after setup)
+rulecatch privacy export-key
+
+# Reset privacy configuration
+rulecatch privacy reset
+```
+
+## What Gets Tracked
+
+Via Claude Code hooks, we automatically capture:
+
+- **Session start/end** - When you begin and end coding sessions
+- **Tool calls** - Every Read, Write, Edit, Bash, Glob, Grep call (name, success/failure)
+- **File paths** - Which files tools operate on (hashed in privacy mode)
+- **Languages used** - Inferred from file extensions (TypeScript, Python, etc.)
+- **Lines changed** - Actual `git diff` stats captured at session end
+- **Files modified** - List of changed files from git (hashed in privacy mode)
+- **Git context** - Repository, branch, commit, dirty state
+- **Turn completions** - When Claude finishes responding
+- **Token usage** - Input/output tokens (calculated from Claude's stats)
+- **Cost estimates** - Based on model and token usage
+
+### What We Never Collect
+
+- **No code content** - We never see your actual code
+- **No keystrokes** - We never capture what you type
+- **No prompt content** - Your conversations stay private
+- **No file content** - Only metadata, never the actual files
+
+## Commands
+
+```bash
+# Set up tracking (run once)
+rulecatch init --api-key=KEY --project-id=PROJECT
+
+# Check setup status
+rulecatch status
+
+# Send test event
+rulecatch test --api-key=KEY
+
+# View recent activity
+rulecatch logs
+
+# Remove tracking
+rulecatch uninstall
+
+# Show help
+rulecatch help
+```
+
+## Privacy Setup (Recommended)
+
+For maximum privacy, set up zero-knowledge mode:
+
+```bash
+# 1. Set up privacy (choose your region)
+rulecatch privacy setup --region=eu   # EU data residency
+rulecatch privacy setup --region=us   # US data residency (default)
+
+# 2. Export key for hooks
+rulecatch privacy export-key
+
+# 3. Set up tracking as normal
+rulecatch init --api-key=KEY --project-id=PROJECT
+```
+
+## Test Your Setup
+
+Clone the test project to verify data flows correctly:
+
+```bash
+git clone https://github.com/TheDecipherist/rulecatch-test
+cd rulecatch-test
+# Follow instructions in README
+```
+
+## Init Options
+
+| Option | Description |
+|--------|-------------|
+| `--api-key=KEY` | Your Rulecatch API key (from dashboard) |
+| `--project-id=ID` | Project identifier for grouping data |
+| `--endpoint=URL` | Custom API endpoint (optional) |
+
+## Privacy Options
+
+| Option | Description |
+|--------|-------------|
+| `--region=eu` | Store data in EU (Frankfurt) for GDPR compliance |
+| `--region=us` | Store data in US (Virginia) - default |
+
+## Optional: Server Mode
+
+For additional features (metrics queries, session control), add to `.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "rulecatch": {
+      "command": "npx",
+      "args": ["@rulecatch/ai-pooler"],
+      "env": {
+        "RULECATCH_AI_KEY": "your-key",
+        "RULECATCH_PROJECT_ID": "your-project"
+      }
+    }
+  }
+}
+```
+
+This enables Claude to call tracking tools directly:
+- `rulecatch_session_start` - Start a tracked session
+- `rulecatch_session_end` - End session and get metrics
+- `rulecatch_get_metrics` - View current session stats
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `RULECATCH_AI_KEY` | Yes | API key from dashboard |
+| `RULECATCH_PROJECT_ID` | Yes | Project identifier |
+| `RULECATCH_ENDPOINT` | No | API endpoint (auto-selected by region) |
+| `RULECATCH_VERSION` | No | Your project version (for correlation) |
+| `RULECATCH_COMMIT` | No | Git commit hash |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────┐
+│           YOUR MACHINE (Full Control)       │
+│                                             │
+│  Claude Code → Hook fires → Privacy check   │
+│                     ↓                       │
+│         PII hashed locally (SHA-256)        │
+│                     ↓                       │
+│    Region check → Route to US or EU API     │
+└─────────────────────────────────────────────┘
+                      ↓
+        ┌─────────────┴─────────────┐
+        ↓                           ↓
+┌───────────────────┐     ┌───────────────────┐
+│  US API (Virginia)│     │  EU API (Frankfurt)│
+│                   │     │                   │
+│  We receive:      │     │  We receive:      │
+│  - Hashed PII     │     │  - Hashed PII     │
+│  - Plain metrics  │     │  - Plain metrics  │
+│                   │     │                   │
+│  We CANNOT see:   │     │  We CANNOT see:   │
+│  - Your email     │     │  - Your email     │
+│  - Your username  │     │  - Your username  │
+│  - Your file paths│     │  - Your file paths│
+└───────────────────┘     └───────────────────┘
+```
+
+## Links
+
+- **Dashboard**: https://dashboard.rulecatch.ai
+- **Documentation**: https://rulecatch.ai/docs
+- **Privacy Policy**: https://rulecatch.ai/privacy
+- **GitHub**: https://github.com/TheDecipherist/rulecatch
+
+## License
+
+MIT