claudetools/.claude/HOOKS.md

Git Hooks Configuration

Overview

Git hooks automatically send notifications to the dev-alerts coordination channel when feature specifications are created or significant commits are made to main branches.

Installed Hooks

post-commit (Main Repo)

Location: .git/hooks/post-commit

Triggers:

• Feature Spec Creation: When a commit includes new docs/specs/SPEC-NNN-*.md files
• Build Events: When commits with conventional commit prefixes (spec:, feat:, fix:, build:) are made to main branch

Actions:

• Extracts SPEC number, priority, effort, and overview from spec file
• Sends coordination message to dev-alerts channel
• Includes commit hash, author, branch, and affected files

Message Format (Feature Spec):

Subject: [ProjectName] Feature Spec: SPEC-NNN [Feature Name]
Body:
  - SPEC number and name
  - Priority and effort estimate
  - Overview excerpt
  - Commit hash and author
  - Link to spec file

Message Format (Build Event):

Subject: [ProjectName] Build: [commit type] on main
Body:
  - Commit hash and type
  - Files changed count
  - Branch and author
  - Full commit message

post-commit (GuruConnect Submodule)

Location: .git/modules/projects/msp-tools/guru-connect/hooks/post-commit

Triggers: Same as main repo Project Key: guruconnect Project Name: GuruConnect

post-commit (GuruRMM Submodule)

Location: .git/modules/projects/msp-tools/guru-rmm/hooks/post-commit

Status: To be created when submodule is initialized Project Key: gururmm Project Name: GuruRMM

Setup

Install Hooks Manually

# Main repo
cp .claude/hooks/post-commit.template .git/hooks/post-commit
chmod +x .git/hooks/post-commit

# GuruConnect submodule
cp .claude/hooks/post-commit.template .git/modules/projects/msp-tools/guru-connect/hooks/post-commit
chmod +x .git/modules/projects/msp-tools/guru-connect/hooks/post-commit

# GuruRMM submodule (when initialized)
cp .claude/hooks/post-commit.template .git/modules/projects/msp-tools/guru-rmm/hooks/post-commit
chmod +x .git/modules/projects/msp-tools/guru-rmm/hooks/post-commit

Verify Hook Installation

# Check if hook exists and is executable
ls -l .git/hooks/post-commit
ls -l .git/modules/projects/msp-tools/guru-connect/hooks/post-commit

# Test manually (run from repo root after a commit)
.git/hooks/post-commit

Coordination API Integration

Hooks send messages to the coordination API at http://172.16.3.30:8001/api/coord/messages with:

• from_session: $(hostname)/claude-main
• to_session: dev-alerts
• project_key: guruconnect, gururmm, or claudetools
• subject: Auto-generated based on event type
• body: Formatted notification with commit details

Message Recipients

Messages sent to dev-alerts can be queried by any session:

# Check unread dev-alerts messages
curl -s "http://172.16.3.30:8001/api/coord/messages?to_session=dev-alerts&unread_only=true"

# Check all dev-alerts messages for a project
curl -s "http://172.16.3.30:8001/api/coord/messages?to_session=dev-alerts&project_key=guruconnect"

Troubleshooting

Hook Not Firing

1. Check executable permission:

   chmod +x .git/hooks/post-commit
   

2. Test manually:

   .git/hooks/post-commit
   

3. Check coordination API:

   curl -s http://172.16.3.30:8001/api/coord/status
   

Debug Hook Execution

Temporarily add debug output to hook:

#!/bin/bash
set -x  # Enable debug mode
# ... rest of hook code ...

Then check git output after commit.

Customization

Add Custom Event Types

Edit the hook and add new patterns to detect:

# Example: Detect documentation commits
if echo "$COMMIT_MSG" | grep -qE '^docs:.*API'; then
    # Send custom dev-alerts message
fi

Change Alert Channel

Replace dev-alerts with a different channel name:

curl -s -X POST http://172.16.3.30:8001/api/coord/messages \
  -H "Content-Type: application/json" \
  -d "{
    \"from_session\": \"$SESSION_ID\",
    \"to_session\": \"build-notifications\",  # Changed from dev-alerts
    ...
  }"

Maintenance

Disable Hooks Temporarily

# Rename to disable
mv .git/hooks/post-commit .git/hooks/post-commit.disabled

# Re-enable
mv .git/hooks/post-commit.disabled .git/hooks/post-commit

Update All Hooks

When the hook logic changes, update all installations:

# Update template
vim .claude/hooks/post-commit.template

# Reinstall to all repos
cp .claude/hooks/post-commit.template .git/hooks/post-commit
cp .claude/hooks/post-commit.template .git/modules/projects/msp-tools/guru-connect/hooks/post-commit
cp .claude/hooks/post-commit.template .git/modules/projects/msp-tools/guru-rmm/hooks/post-commit

---

Last Updated: 2026-05-31