gh-bandofai-puerto-plugins-essentials/hooks/README.md

Puerto Prompt Analyzer Hook (v2.0)

Intelligent prompt analyzer for Claude Code that automatically validates user instructions and recommends relevant plugins from the Puerto marketplace.

🆕 Version 2.0 Features:

• ⚡ 60x faster with intelligent caching
• 🎯 2x more accurate with advanced text processing
• 🚫 Filters installed plugins - never recommends what you already have
• 🧠 Project context aware - detects JavaScript, Python, Rust, Go, Ruby, Java projects
• 🔧 Fully configurable - customize scoring, blacklist plugins, set favorites
• 📊 Performance monitoring - logs slow executions
• 🎲 Diversity algorithm - shows varied recommendations, not repetitive ones
• 💾 Session memory - avoids showing same plugins repeatedly

⚠️ Manual Setup Required Due to Claude Code security restrictions, hooks cannot be automatically configured when installing plugins. You must manually add this hook to your ~/.claude/settings.json file. See the Essentials Plugin README for step-by-step setup instructions.

Overview

The instruction analysis hook runs before Claude processes your prompts, providing:

• Task Type Classification: Automatically categorizes your request as Research, Implementation, Mixed, or General
• Instruction Validation: Detects vague or unclear instructions and provides improvement suggestions
• Plugin Recommendations: Suggests top 2-3 relevant plugins from Puerto marketplace based on your task
• Transparent Analysis: Shows recommendations directly in Claude's response with install commands

How It Works

1. You submit a prompt (any non-command message)
2. Hook analyzes your prompt before Claude sees it:
   • Classifies task type using keyword detection
   • Validates instruction clarity
   • Scores all marketplace plugins for relevance
   • Generates top recommendations
3. Claude processes your original prompt + recommendations
4. You see analysis section in Claude's response with suggested plugins

Features

Task Classification (Enhanced v2.0)

Uses advanced tokenization and stemming to determine task type:

• Research: explain, analyze, investigate, understand, compare, study, evaluate, etc.
• Implementation: implement, create, build, fix, refactor, add, deploy, optimize, etc.
• Mixed: Contains both research and implementation keywords (requires 1.5x threshold)
• General: No clear classification

Improvements: Stemming ("building" → "build"), stop word filtering, better thresholds

Instruction Validation

Detects common issues:

• Too vague: "fix it", "make it better", "help" → Suggests being more specific
• Missing context: Short prompts (<30 chars) with ambiguous pronouns → Requests clarification
• Overly broad: "build an app" → Suggests breaking down into components

Intelligent Plugin Scoring (v2.0)

Recommendations based on weighted scoring algorithm:

1. Tokenized description overlap (weight: 2) - Advanced text matching with stemming
2. Name matching (weight: 5) - Plugin name relevance (strongest signal)
3. Keyword tags (weight: 3) - Plugin keywords matching prompt
4. Task type alignment (weight: 5) - Agents for implementation, skills for research
5. Project context (weight: 3) - Detects your project type and boosts relevant plugins
6. Category matching (weight: 4) - Favorite categories get priority

Quality threshold: Only shows plugins scoring ≥8 points (configurable)

Filters:

• ✅ Skips already-installed plugins
• ✅ Reduces score for recently shown plugins (-5 points)
• ✅ Respects blacklist configuration
• ✅ Diversity algorithm ensures varied recommendations

Project Context Detection (New in v2.0)

Automatically detects your project type:

• JavaScript/Node.js - Detects package.json, frameworks (React, Vue, Next.js, Express)
• Python - Detects requirements.txt, pyproject.toml
• Rust - Detects Cargo.toml
• Go - Detects go.mod
• Ruby - Detects Gemfile
• Java - Detects pom.xml, build.gradle

Boosts plugin scores when they match your project stack!

Example Output

## 🔍 Instruction Analysis

**Task Type:** Implementation

**📦 Recommended Plugins:**

### 1. `engineering`
**Description:** Full-stack development department with 7 specialized agents
**Why:** Matches keywords: implementation, build, create
**Install:** `/plugin install engineering`

### 2. `product`
**Description:** Product management and data analysis department
**Why:** Matches keywords: analyze, track, metrics
**Install:** `/plugin install product`

---

Configuration

Installation

⚠️ Manual setup is required. Hooks cannot be automatically configured by plugins for security reasons.

Hook Configuration (Manual Setup Required)

You must manually add this to your ~/.claude/settings.json file:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/plugins/marketplaces/puerto/plugins/essentials/hooks/puerto-prompt-analyzer.js",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Setup Steps:

1. Install the essentials plugin: /plugin install essentials@puerto

2. Find your plugin path:

   find ~/.claude/plugins -name "puerto-prompt-analyzer.js" 2>/dev/null
   

3. Replace the path in the hook configuration above with your actual path

4. Edit ~/.claude/settings.json and add the hook configuration

5. Verify JSON is valid: cat ~/.claude/settings.json | python3 -m json.tool

6. Restart Claude Code (required)

7. Test by submitting a non-command prompt - you should see "🔍 Instruction Analysis" in the response

Note: If node is not in your PATH, use the full path: "command": "/usr/local/bin/node /path/to/puerto-prompt-analyzer.js"

For detailed setup instructions with troubleshooting, see the Essentials Plugin README.

Advanced Configuration (New in v2.0)

Customize the hook behavior by creating ~/.claude/puerto-prompt-analyzer.json:

{
  "minScore": 8,
  "maxRecommendations": 3,
  "cacheMinutes": 1,
  "blacklist": [],
  "favoriteCategories": [],
  "showScores": false
}

Configuration Options:

Option	Type	Default	Description
minScore	number	8	Minimum score threshold (0-100). Higher = more selective
maxRecommendations	number	3	Maximum number of plugins to recommend
cacheMinutes	number	1	How long to cache marketplace data (in minutes)
blacklist	array	[]	Plugin names to never recommend (e.g., ["plugin-name"])
favoriteCategories	array	[]	Categories to boost (e.g., ["frontend", "backend"])
showScores	boolean	false	Show relevance scores for debugging

Example Configurations:

Conservative (fewer, higher-quality recommendations):

{
  "minScore": 12,
  "maxRecommendations": 2,
  "showScores": false
}

Exploratory (more recommendations, lower threshold):

{
  "minScore": 5,
  "maxRecommendations": 5,
  "showScores": true
}

Frontend-focused:

{
  "minScore": 8,
  "maxRecommendations": 3,
  "favoriteCategories": ["frontend", "ui", "design"],
  "blacklist": ["backend-heavy-plugin"]
}

See puerto-prompt-analyzer.example.json for more examples.

Disabling the Hook

To temporarily disable the analyzer:

1. Open ~/.claude/settings.json
2. Remove or comment out the UserPromptSubmit hook entry
3. Restart Claude Code

Performance

Version 2.0 Performance:

• Execution time: < 100ms for 95% of prompts (was < 1s)
• Cache hit rate: ~95% after first run
• Memory: ~50KB marketplace.json cached in memory
• Latency: Minimal impact on workflow (<5% overhead)
• Dependencies: None (uses Node.js built-ins only)

Optimizations:

• ✅ Marketplace data cached for 60 seconds
• ✅ Installed plugins cached for 60 seconds
• ✅ Session memory for deduplication
• ✅ Efficient tokenization with stop words
• ✅ Logs executions >500ms for monitoring

Error Handling

The hook follows a fail-open philosophy:

• Never blocks your prompt, even on errors
• All errors logged to stderr for debugging
• If marketplace.json is missing, proceeds without recommendations
• If JSON parsing fails, allows prompt normally
• Timeout protection (60s limit)

You will never be prevented from working due to hook failures.

Troubleshooting

No recommendations appearing

Check:

1. Is marketplace.json present? Run: ls .claude-plugin/marketplace.json
2. Is the hook executable? Run: ls -la plugins/essentials/hooks/puerto-prompt-analyzer.js
3. Check stderr for errors: Look for [puerto-prompt-analyzer] messages

Solution:

# Regenerate marketplace catalog
npm run generate-catalog

# Make hook executable
chmod +x plugins/essentials/hooks/puerto-prompt-analyzer.js

Hook seems slow

Check:

# Test hook execution time
time echo '{"prompt": "test", "hook_event_name": "UserPromptSubmit"}' | \
  node plugins/essentials/hooks/puerto-prompt-analyzer.js

Expected: < 1 second

Invalid recommendations

The hook uses simple keyword matching (MVP). Accuracy improves with:

• More specific prompts
• Using keywords from plugin descriptions
• Clearer task intent (research vs implementation)

Future: v2 will include LLM-based classification for better accuracy.

Technical Details

Input Format

Hook receives JSON via stdin:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "User's submitted text"
}

Output Format

Hook outputs JSON to stdout:

{
  "decision": undefined,
  "reason": "Analysis complete",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "## 🔍 Instruction Analysis\n..."
  }
}

Skipped Prompts

Hook automatically skips:

• Empty prompts
• Command prompts (start with /)
• Prompts that fail JSON parsing

Customization (Future v2)

Planned features:

• Configurable keywords in settings.json
• Plugin blacklist/whitelist
• LLM-based classification option
• User feedback loop (track recommendation acceptance)
• Installation status detection
• Context-aware recommendations

Contributing

Found a bug or have a suggestion?

1. Check if it's a known issue in the troubleshooting section
2. File an issue with:
   • Sample prompt that caused the issue
   • Expected vs actual recommendations
   • stderr output if available

License

MIT License - Part of the Puerto marketplace ecosystem

See Also

• Claude Code Hooks Documentation
• Puerto Marketplace
• Essentials Plugin README