Cursor Helper

A powerful VS Code/Cursor extension that enhances your AI-assisted coding experience with notifications and intelligent monitoring.

✨ Features

• 🔔 Smart Notifications: Desktop alerts for task completion, context capacity, and file confirmations
• 📚 Prompt Template Library: Save, organize, and reuse effective prompts with variable substitution
• 🔊 Cross-Platform Sound: Native sound support for macOS, Windows, and Linux
• ⚙️ Highly Configurable: Extensive settings for messages, sounds, and thresholds
• 🔒 Privacy First: Runs entirely locally, no telemetry or external calls

📑 Table of Contents

• Quick Start
• Features Deep Dive
  • Task Notifications
  • Prompt Template Library
  • Context Monitoring
  • File Confirmations
• Configuration
• Commands
• Troubleshooting
• Development
• Contributing

🚀 Quick Start

1. Installation

From VSIX (Recommended for testing)

npm install && npm run build && npm run package

Install the generated .vsix via Extensions → Install from VSIX...

From Source (Development)

git clone https://github.com/alieneclectic/cursor-helper.git
cd cursor-helper
npm install

Press F5 to launch Extension Development Host

2. Setup Notifications

Easy Method:

1. Open Command Palette: Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
2. Run: Cursor Helper: Quick Setup (Copy Rule)
3. Follow the prompts to add the rule to Cursor

Manual Method - Add this to Cursor Settings:

At the END of your turn, after you have completely finished all work and before ending your response, run this command to notify the user:
<!run:sh -lc "echo \"$(date) :: CURSOR_DONE\" > $HOME/.cursor-notify.flag">

At the END of your turn, after you have completely finished all work and before ending your response, run this command to notify the user:
<!run:powershell -command "$d=Get-Date; Set-Content -Path $env:USERPROFILE\.cursor-notify.flag -Value $d;">

3. Test It

Run Cursor Helper: Test Notification from the Command Palette. You should see a notification and hear a sound! 🎉

🎯 Features Deep Dive

Task Notifications

Get instant desktop notifications when Cursor completes tasks. The extension watches a flag file that Cursor updates via a custom rule. When detected, you'll receive a notification with optional sound.

How it works:

1. Add the Cursor rule (see Quick Start)
2. Cursor AI completes a task → updates flag file
3. Extension detects change → triggers notification

Prompt Template Library

Save, organize, and reuse your most effective prompts with powerful variable substitution. Perfect for standardizing workflows and sharing best practices with your team.

Key Features:

• 📝 Create from scratch or selection: Convert any text into a reusable template
• 🔄 Variable substitution: Use {{variableName}} for dynamic placeholders
• 📂 Category organization: Refactoring, Debugging, Testing, Documentation, Optimization, General
• 🏷️ Tags & search: Easily find templates with tags and full-text search
• 📊 Usage tracking: See which templates are most effective
• 🔀 Import/Export: Share templates across projects and teams
• ⭐ 8 default templates: Get started immediately with curated examples

Quick Start:

1. Run: Cursor Helper: Open Template Library
2. Browse default templates or create your own
3. Use Cursor Helper: Insert Template to add to your prompt

Variable Syntax:

• {{name}} - Simple placeholder
• {{name:description}} - With descriptive prompt
• {{name:description:default}} - With default value

Example Template:

Please refactor {{fileName:Name of the file}} to improve {{goal:Refactoring goal::readability}}.

Focus on:
- Code clarity
- Performance
- {{customFocus:Additional focus area::Error handling}}

Learn More: See TEMPLATE_LIBRARY_GUIDE.md for detailed documentation.

Context Monitoring

Get alerted when Cursor's context window nears capacity so you can start fresh or summarize.

Setup:

1. Run: Cursor Helper: Setup Context Window Monitoring
2. Or manually add this rule to Cursor Settings:

When the context window usage exceeds 90%, run this command to alert the user:
<!run:sh -lc "echo \"$(date) :: CONTEXT_ALERT\" > $HOME/.cursor-context-alert.flag">

When the context window usage exceeds 90%, run this command to alert the user:
<!run:powershell -command "$d=Get-Date; Set-Content -Path $env:USERPROFILE\.cursor-context-alert.flag -Value $d;">

Adjust threshold in settings (default: 90%)

File Confirmations

Get notified when Cursor requests permission to edit files, so you never miss an important approval.

Setup:

1. Run: Cursor Helper: Setup File Confirmation Alerts
2. Or manually add this rule to Cursor Settings:

Before asking for confirmation to edit a file, run this command to alert the user:
<!run:sh -lc "echo \"$(date) :: FILE_CONFIRM\" > $HOME/.cursor-file-confirm.flag">

Before asking for confirmation to edit a file, run this command to alert the user:
<!run:powershell -command "$d=Get-Date; Set-Content -Path $env:USERPROFILE\.cursor-file-confirm.flag -Value $d;">

⚙️ Configuration

Example Configuration:

{
  "cursorHelper.message": "✅ Task complete!",
  "cursorHelper.customSoundPath": "/System/Library/Sounds/Hero.aiff",
  "cursorHelper.contextMonitoring.threshold": 85
}

Platform-Specific Sounds:

• macOS: /System/Library/Sounds/Hero.aiff
• Windows: C:\Users\YourName\Music\complete.wav
• Linux: /home/username/sounds/complete.wav

💻 Commands

Access via Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

🐛 Troubleshooting

🔧 Development

Build & Run:

npm install              # Install dependencies
npm run build            # Build TypeScript
npm run watch            # Watch mode for development
npm run package          # Create .vsix package

Debug:

1. Open project in VS Code/Cursor
2. Press F5 to launch Extension Development Host
3. Test commands via Command Palette
4. View logs: View → Output → Cursor Helper

Architecture:

src/
├── core/types.ts                    # Core interfaces
├── config/configManager.ts          # Settings management
├── watchers/                        # File watchers
├── notifiers/vscodeNotifier.ts      # Notification handler
├── sound/soundPlayer.ts             # Cross-platform audio
├── templates/                       # Prompt template library
└── extension.ts                     # Entry point

The codebase uses interfaces (IWatcher, INotifier, ISoundPlayer) making it easy to extend with new functionality.

🤝 Contributing

Contributions welcome! The extension is designed for extensibility.

Quick Start:

1. Fork & clone
2. npm install → Make changes → npm run watch
3. Press F5 to test
4. Submit PR with clear description

Contribution Ideas:

• New watcher types (HTTP, logs, processes)
• Webhook notifications
• Rich notifications with actions
• Automated tests

Standards: TypeScript strict mode, interfaces over types, async/await, JSDoc for public APIs

📜 Changelog

v0.7.1 (2025-10-02)

• 🗑️ REMOVED: Token tracking feature (was non-functional without automatic API integration)
• 🧹 Cleaned up codebase and reduced complexity
• ✨ Focus on core working features: notifications, templates, and monitoring

v0.7.0 (2025-10-02)

• 📚 NEW: Prompt Template Library with variable substitution
• 🔄 Save and reuse effective prompts across projects
• 📂 Category organization and tag-based search
• 📊 Usage tracking and analytics
• 🔀 Import/Export templates for team sharing
• ⭐ 8 curated default templates included

v0.6.1 (2025-10-02)

• 🐛 Fixed: Notifications now trigger only when Cursor is completely done, not on individual step success
• 📝 Updated Cursor Rule to be more explicit about end-of-turn timing

v0.6.0 (2025-10-02)

• 🐛 Fixed notification timing (removed in v0.7.1)

v0.5.0 (2025-10-01)

• 📝 File edit confirmation alerts

v0.2.0 (2025-10-01)

• ⚠️ Context window monitoring

v0.1.0 (2025-10-01)

• 🎉 Initial release with notifications & sounds

📄 License

MIT License - see LICENSE for details.

🙏 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Star: If this helps you, please ⭐ star the repo!

Built with ❤️ for the Cursor AI community.

Enjoy Cursor Helper! 🎉