From cd224fac529370184e3131d6282cfdfe45b27d37 Mon Sep 17 00:00:00 2001 From: rUv Date: Tue, 30 Dec 2025 21:51:37 +0000 Subject: [PATCH] docs: add Claude Code hooks section to README and create HOOKS.md - Added hooks feature summary near top of README.md - Created comprehensive HOOKS.md documentation - Links to detailed docs for pretrain, build-agents, verify, etc. --- npm/packages/ruvector/HOOKS.md | 221 +++++++++++++++++++++++++++++ npm/packages/ruvector/README.md | 20 +++ npm/packages/ruvector/package.json | 2 +- 3 files changed, 242 insertions(+), 1 deletion(-) create mode 100644 npm/packages/ruvector/HOOKS.md diff --git a/npm/packages/ruvector/HOOKS.md b/npm/packages/ruvector/HOOKS.md new file mode 100644 index 000000000..7ad692031 --- /dev/null +++ b/npm/packages/ruvector/HOOKS.md @@ -0,0 +1,221 @@ +# RuVector Hooks for Claude Code + +Self-learning intelligence hooks that enhance Claude Code with Q-learning, vector memory, and automatic agent routing. + +## Quick Start + +```bash +# Full setup: hooks + pretrain + optimized agents +npx ruvector hooks init --pretrain --build-agents quality + +# Or step by step: +npx ruvector hooks init # Setup hooks +npx ruvector hooks pretrain # Analyze repository +npx ruvector hooks build-agents # Generate agent configs +``` + +## What It Does + +RuVector hooks integrate with Claude Code to provide: + +| Feature | Description | +|---------|-------------| +| **Agent Routing** | Suggests the best agent for each file type based on learned patterns | +| **Co-edit Patterns** | Predicts "likely next files" from git history | +| **Vector Memory** | Semantic recall of project context | +| **Command Analysis** | Risk assessment for bash commands | +| **Self-Learning** | Q-learning improves suggestions over time | + +## Commands + +### Initialization + +```bash +# Full configuration +npx ruvector hooks init + +# With pretrain and agent building +npx ruvector hooks init --pretrain --build-agents security + +# Minimal (basic hooks only) +npx ruvector hooks init --minimal + +# Options +--force # Overwrite existing settings +--minimal # Basic hooks only +--pretrain # Run pretrain after init +--build-agents # Generate optimized agents (quality|speed|security|testing|fullstack) +--no-claude-md # Skip CLAUDE.md creation +--no-permissions # Skip permissions config +--no-env # Skip environment variables +--no-gitignore # Skip .gitignore update +--no-mcp # Skip MCP server config +--no-statusline # Skip status line config +``` + +### Pretrain + +Analyze your repository to bootstrap intelligence: + +```bash +npx ruvector hooks pretrain + +# Options +--depth # Git history depth (default: 100) +--verbose # Show detailed progress +--skip-git # Skip git history analysis +--skip-files # Skip file structure analysis +``` + +**What it learns:** +- File type → Agent mapping (`.rs` → rust-developer) +- Co-edit patterns from git history +- Directory → Agent mapping +- Project context memories + +### Build Agents + +Generate optimized `.claude/agents/` configurations: + +```bash +npx ruvector hooks build-agents --focus quality + +# Focus modes +--focus quality # Code quality, best practices (default) +--focus speed # Rapid development, prototyping +--focus security # OWASP, input validation, encryption +--focus testing # TDD, comprehensive coverage +--focus fullstack # Balanced frontend/backend/database + +# Options +--output # Output directory (default: .claude/agents) +--format # yaml, json, or md (default: yaml) +--include-prompts # Include system prompts in agent configs +``` + +### Verification & Diagnostics + +```bash +# Check if hooks are working +npx ruvector hooks verify + +# Diagnose and fix issues +npx ruvector hooks doctor +npx ruvector hooks doctor --fix +``` + +### Data Management + +```bash +# View statistics +npx ruvector hooks stats + +# Export intelligence data +npx ruvector hooks export -o backup.json +npx ruvector hooks export --include-all + +# Import intelligence data +npx ruvector hooks import backup.json +npx ruvector hooks import backup.json --merge +``` + +### Memory Operations + +```bash +# Store context in vector memory +npx ruvector hooks remember "API uses JWT auth" -t project + +# Semantic search memory +npx ruvector hooks recall "authentication" + +# Route a task to best agent +npx ruvector hooks route "implement user login" +``` + +## Hook Events + +| Event | Trigger | RuVector Action | +|-------|---------|-----------------| +| **PreToolUse** | Before Edit/Write/Bash | Agent routing, file analysis, command risk | +| **PostToolUse** | After Edit/Write/Bash | Q-learning update, pattern recording | +| **SessionStart** | Conversation begins | Load intelligence, display stats | +| **Stop** | Conversation ends | Save learning data | +| **UserPromptSubmit** | User sends message | Context suggestions | +| **PreCompact** | Before context compaction | Preserve important context | +| **Notification** | Any notification | Track events for learning | + +## Generated Files + +After running `hooks init`: + +``` +your-project/ +├── .claude/ +│ ├── settings.json # Hooks configuration +│ ├── statusline.sh # Status bar script +│ └── agents/ # Generated agents (with --build-agents) +│ ├── rust-specialist.yaml +│ ├── typescript-specialist.yaml +│ ├── test-architect.yaml +│ └── project-coordinator.yaml +├── .ruvector/ +│ └── intelligence.json # Learning data +├── CLAUDE.md # Project documentation +└── .gitignore # Updated with .ruvector/ +``` + +## Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `RUVECTOR_INTELLIGENCE_ENABLED` | `true` | Enable/disable intelligence | +| `RUVECTOR_LEARNING_RATE` | `0.1` | Q-learning rate (0.0-1.0) | +| `RUVECTOR_MEMORY_BACKEND` | `rvlite` | Memory storage backend | +| `INTELLIGENCE_MODE` | `treatment` | A/B testing mode | + +## Example Output + +### Agent Routing +``` +🧠 Intelligence Analysis: + 📁 src/api/routes.ts + 🤖 Recommended: typescript-developer (85% confidence) + → learned from 127 .ts files in repo + 📎 Likely next files: + - src/api/handlers.ts (12 co-edits) + - src/types/api.ts (8 co-edits) +``` + +### Command Analysis +``` +🧠 Command Analysis: + 📦 Category: rust + 🏷️ Type: test + ✅ Risk: LOW +``` + +## Best Practices + +1. **Run pretrain on existing repos** — Bootstrap intelligence before starting work +2. **Use focus modes** — Match agent generation to your current task +3. **Export before major changes** — Backup learning data +4. **Let it learn** — Intelligence improves with each edit + +## Troubleshooting + +```bash +# Check setup +npx ruvector hooks verify + +# Fix common issues +npx ruvector hooks doctor --fix + +# Reset and reinitialize +npx ruvector hooks init --force --pretrain +``` + +## Links + +- [RuVector GitHub](https://github.com/ruvnet/ruvector) +- [npm Package](https://www.npmjs.com/package/ruvector) +- [Claude Code Documentation](https://docs.anthropic.com/claude-code) diff --git a/npm/packages/ruvector/README.md b/npm/packages/ruvector/README.md index ef1adeb66..d715a0f8d 100644 --- a/npm/packages/ruvector/README.md +++ b/npm/packages/ruvector/README.md @@ -20,6 +20,26 @@ Built by [rUv](https://ruv.io) with production-grade Rust performance and intell --- +## 🧠 Claude Code Hooks (NEW) + +**Self-learning intelligence for Claude Code** — RuVector provides optimized hooks that learn from your development patterns. + +```bash +# One-command setup with pretrain and agent generation +npx ruvector hooks init --pretrain --build-agents quality +``` + +**Features:** +- 🎯 **Smart Agent Routing** — Automatically suggests the best agent for each file type +- 📚 **Repository Pretrain** — Analyzes your codebase to bootstrap intelligence +- 🤖 **Agent Builder** — Generates optimized `.claude/agents/` configs for your stack +- 🔗 **Co-edit Patterns** — Learns which files are edited together from git history +- 💾 **Vector Memory** — Semantic recall of project context + +📖 **[Full Hooks Documentation →](https://github.com/ruvnet/ruvector/blob/main/npm/packages/ruvector/HOOKS.md)** + +--- + ## 🌟 Why Ruvector? ### The Problem with Existing Vector Databases diff --git a/npm/packages/ruvector/package.json b/npm/packages/ruvector/package.json index d43eea7d7..9e3232764 100644 --- a/npm/packages/ruvector/package.json +++ b/npm/packages/ruvector/package.json @@ -1,6 +1,6 @@ { "name": "ruvector", - "version": "0.1.49", + "version": "0.1.50", "description": "High-performance vector database for Node.js with automatic native/WASM fallback", "main": "dist/index.js", "types": "dist/index.d.ts",