@arclabs561/hookwise

Intelligent git hooks powered by LLMs - wise guidance for your commits, code, and documentation.

Why "Hookwise"?

Hookwise provides intelligent, context-aware guidance for your git workflow - like having a wise advisor reviewing your commits and code. The name combines "hooks" (git hooks) with "wise" (intelligent guidance).

Features

• 🧠 LLM-powered commit message validation - Intelligent feedback on commit messages
• 📚 Documentation bloat detection - Analyze and prevent documentation accumulation
• ⚡ Easy installation - Simple setup with husky
• 🎛️ Multi-level configuration - Per-repo, global, and environment variable configs
• 🧪 Testing utilities - Test hooks without committing
• 🚀 Fast feedback - Format validation first, LLM analysis optional

Prerequisites

This package requires Husky for git hooks management.

Husky is the standard tool for managing git hooks in Node.js projects. Hookwise integrates seamlessly with Husky to provide intelligent LLM-powered validation.

Installation

npm install --save-dev @arclabs561/hookwise @arclabs561/llm-utils husky

Quick Start

1. Initialize Husky (Required)

Husky must be initialized first:

npx husky install

This sets up the .husky directory and git hooks infrastructure.

2. Install Hookwise

npx hookwise install

This installs intelligent hooks into your .husky directory:

• commit-msg - LLM-powered commit message validation
• pre-commit - Documentation bloat checking (optional)

3. Test It

# Test commit message validation (no commit needed!)
npx hookwise test-commit "feat: add new feature"

# Test documentation check
npx hookwise test-docs

# See current configuration
npx hookwise config

Usage

Commit Message Validation

The commit-msg hook automatically validates commit messages:

git commit -m "feat: add new feature"

Hookwise provides:

• ✅ Format validation (conventional commits)
• 📊 Quality scoring (0-10) via LLM
• 💡 Intelligent suggestions
• 🎯 Context-aware feedback

WIP Commits: Automatically allowed (e.g., wip:, WIP:, [wip])

Skip Validation:

HOOKWISE_SKIP=true git commit -m "emergency fix"
# Or use git's built-in:
git commit --no-verify -m "emergency fix"

Documentation Bloat Detection

Prevent documentation accumulation:

git commit  # Automatically checks for excessive docs

Detects:

• Too many markdown files in root
• Temporary analysis documents (FINAL_, COMPLETE_, etc.)
• Old documentation that should be archived
• Redundant content (with optional LLM analysis)

Configuration

Hookwise supports multi-level configuration:

1. Repository-level (.hookwise.config.mjs) - Project-specific settings
2. Global-level (~/.hookwise.config.mjs or git config) - Personal defaults
3. Environment variables - Override everything

Repository Config

Create .hookwise.config.mjs in your repo root:

export default {
  commitMessage: {
    enabled: true,
    blocking: true,  // Block commits with poor messages
    tier: 'simple',   // Use simple tier for speed
    minScore: 5,      // Minimum LLM score (0-10)
  },
  documentation: {
    enabled: true,
    maxRootFiles: 5,
    archivePatterns: ['FINAL_', 'COMPLETE_', 'ANALYSIS_'],
  },
};

Global Config

Set personal defaults in ~/.hookwise.config.mjs:

export default {
  commitMessage: {
    blocking: false,  // Don't block, just warn
    minScore: 4,      // Lower threshold for personal repos
  },
};

Environment Variables

Override any setting:

HOOKWISE_COMMIT_MESSAGE_BLOCKING=false
HOOKWISE_COMMIT_MESSAGE_MIN_SCORE=3
HOOKWISE_DOCUMENTATION_ENABLED=false

Testing

Run tests:

npm test

Test hooks manually:

npx hookwise test-commit "feat: add feature"
npx hookwise test-commit "bad message"
npx hookwise test-docs
npx hookwise config

API

Programmatic Usage

import { validateCommitMessage, analyzeDocBloat } from '@arclabs561/hookwise';

// Validate commit message
const result = await validateCommitMessage('feat: add feature');
console.log(result.valid, result.issues);

// Check documentation bloat
const bloat = await analyzeDocBloat();
console.log(bloat.issues, bloat.warnings);

Environment Variables

Requires @arclabs561/llm-utils to be configured with API keys:

• GEMINI_API_KEY or
• OPENAI_API_KEY or
• ANTHROPIC_API_KEY

See @arclabs561/llm-utils documentation for details.

License

MIT