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

You submit a prompt (any non-command message)
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
Claude processes your original prompt + recommendations
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:

Tokenized description overlap (weight: 2) - Advanced text matching with stemming
Name matching (weight: 5) - Plugin name relevance (strongest signal)
Keyword tags (weight: 3) - Plugin keywords matching prompt
Task type alignment (weight: 5) - Agents for implementation, skills for research
Project context (weight: 3) - Detects your project type and boosts relevant plugins
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:

Install the essentials plugin: /plugin install essentials@puerto

Find your plugin path:

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

Replace the path in the hook configuration above with your actual path
Edit ~/.claude/settings.json and add the hook configuration
Verify JSON is valid: cat ~/.claude/settings.json | python3 -m json.tool
Restart Claude Code (required)
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:

Open ~/.claude/settings.json
Remove or comment out the UserPromptSubmit hook entry
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:

Is marketplace.json present? Run: ls .claude-plugin/marketplace.json
Is the hook executable? Run: ls -la plugins/essentials/hooks/puerto-prompt-analyzer.js
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?

Check if it's a known issue in the troubleshooting section
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

README.md

Puerto Prompt Analyzer Hook (v2.0)