wifi-densepose/npm/packages/ruvector/HOOKS.md

RuVector Hooks for Claude Code

Self-learning intelligence hooks that enhance Claude Code with Q-learning, vector memory, and automatic agent routing.

Quick Start

# 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

# 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:

npx ruvector hooks pretrain

# Options
--depth <n>     # 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:

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 <dir>    # Output directory (default: .claude/agents)
--format <fmt>    # yaml, json, or md (default: yaml)
--include-prompts # Include system prompts in agent configs

Verification & Diagnostics

# Check if hooks are working
npx ruvector hooks verify

# Diagnose and fix issues
npx ruvector hooks doctor
npx ruvector hooks doctor --fix

Data Management

# 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

# 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

# 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
• npm Package
• Claude Code Documentation