Ghost Dev 🎤

Voice output layer for Cursor - enables natural voice interaction with your AI coding assistant using ElevenLabs TTS with intelligent fallbacks and robust error handling.

Features

• 🎤 Voice Responses: Convert AI responses to natural speech using ElevenLabs TTS
• 🔧 Text Processing: Optimizes developer content (code, JSON, etc.) for TTS
• 🎭 Multiple Voices: Choose from ElevenLabs voice library
• 🔌 MCP Integration: Seamless integration with Cursor via Model Context Protocol
• 📱 CLI Interface: Standalone command-line tools for testing
• 🩺 System Diagnostics: Built-in health checks and troubleshooting
• 🛡️ Robust Error Handling: Automatic fallbacks and retry mechanisms
• 🔄 Fallback TTS: Uses system TTS when ElevenLabs is unavailable
• ⚡ Performance Optimized: Fast audio generation with intelligent caching

Installation & Setup

Option 1: MCP Server (Recommended for Cursor)

1. Install Ghost Dev globally:

   npm install -g ghost-dev

2. Add to your .cursor/mcp.json:

   {
     "mcpServers": {
       "ghost-dev": {
         "command": "npx",
         "args": ["-y", "--package=ghost-dev", "ghost-dev-mcp"],
         "env": {
           "ELEVENLABS_API_KEY": "your_elevenlabs_api_key_here"
         }
       }
     }
   }

3. Get your ElevenLabs API key:

   • Sign up at ElevenLabs
   • Go to Profile → API Keys
   • Create a new key with text-to-speech permissions
   • Replace your_elevenlabs_api_key_here in the config above

4. Restart Cursor to load the MCP server

5. Test your setup:

   In Cursor, try: Hey Ghost, say hello world!

Troubleshooting & Diagnostics

Ghost Dev includes a comprehensive diagnostic system to help troubleshoot any issues:

Run diagnostics in Cursor: The ghost_doctor tool automatically checks:

• ✅ ElevenLabs API key validity and connection
• ✅ Audio playback capabilities (afplay/ffplay)
• ✅ File system permissions
• ✅ MCP configuration
• ✅ System dependencies (Node.js version)
• ✅ Account usage and limits

Common Issues & Solutions:

File Permission Errors:

# Option 1: Grant write permissions to your project directory
chmod 755 /path/to/your/project

# Option 2: Create a dedicated ghost-dev directory
mkdir -p ~/.ghost-dev && chmod 755 ~/.ghost-dev

Audio Playback Issues:

# macOS: Install/update Xcode command line tools
xcode-select --install

# Linux: Install ffmpeg
sudo apt install ffmpeg  # Ubuntu/Debian
sudo yum install ffmpeg  # CentOS/RHEL

API Connection Issues:

• Verify your ElevenLabs API key is correct
• Check your internet connection
• Confirm your ElevenLabs account has available characters

MCP Tools Available

Once configured as an MCP server, Ghost Dev provides these tools in Cursor:

ghost_speak

Convert text to speech with TTS optimization and automatic fallbacks.

Features:

• Primary: ElevenLabs TTS with high-quality voices
• Fallback: System TTS (macOS say, Linux espeak, Windows PowerShell)
• Automatic retry with exponential backoff
• Intelligent error handling with user-friendly messages

// Parameters:
{
  text: string,           // Required: Text to convert
  voiceId?: string,       // Optional: ElevenLabs voice ID
  outputPath?: string,    // Optional: Save location
  stability?: number,     // Optional: 0.0-1.0
  similarityBoost?: number // Optional: 0.0-1.0
}

ghost_list_voices

List all available ElevenLabs voices with details.

ghost_test_connection

Test API connection and show account info (characters used/remaining).

ghost_doctor

NEW! Comprehensive system diagnostics and health check.

Checks performed:

• ElevenLabs API key and connection status
• Audio playback system availability
• File system permissions for audio output
• MCP configuration validation
• Node.js version compatibility
• Account usage and limits

Example output:

🔧 Ghost Dev Diagnostic Report

✅ Ghost Dev is healthy and ready to rock, mate!

📊 Results:
✅ ElevenLabs API Key: API key found and appears valid
✅ ElevenLabs Connection: Connected successfully (0/10000 characters used)
✅ Audio Playback: Audio players available: afplay
✅ File Permissions: Write access available: Temp Directory, System Temp
✅ MCP Configuration: MCP configuration file found and readable
✅ Node.js Version: Node.js v20.19.2 is compatible

🎉 All systems go!
Ghost Dev is ready for action. Try: "Hey Ghost, say hello world!"

Error Handling & Fallbacks

Ghost Dev includes robust error handling to ensure reliable operation:

Automatic Fallbacks:

1. ElevenLabs API fails → Retry with exponential backoff
2. Still failing → Switch to system TTS automatically
3. Audio playback fails → Save file with helpful error message
4. File permissions denied → Try alternative save locations

Error Types Handled:

• API connectivity issues
• Rate limiting and quota exceeded
• File system permission errors
• Audio playback system failures
• Configuration problems

User Experience:

• Clear, actionable error messages
• Automatic fallback to system TTS
• Helpful suggestions for resolving issues
• No cryptic technical errors

Usage with "Hey Ghost" Prompts

Ghost Dev is designed to work seamlessly with "Hey Ghost" prompts in Cursor. When you start a prompt with "Hey Ghost", the AI can automatically use the ghost_speak tool to provide voice responses.

Examples:

Hey Ghost, explain how async/await works in JavaScript

Hey Ghost, review this code and suggest improvements

Hey Ghost, what's the difference between let and const?

The AI will respond with both text and automatically generate speech using Ghost Dev, with fallback to system TTS if needed.

Text Processing Features

Ghost Dev automatically optimizes text for TTS by:

• Converting code snippets to readable descriptions
• Expanding abbreviations (API → "A P I", JSON → "Jason")
• Converting CSS units (px → "pixels", rem → "rem units")
• Removing markdown formatting
• Cleaning HTML content
• Chunking long text appropriately
• Handling special characters and symbols

CLI Commands

• ghost-dev speak "Hello world" - Convert text to speech
• ghost-dev voices - List available voices
• ghost-dev test-tts - Test TTS functionality
• ghost-dev debug-api - Debug API connection

Development

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode
pnpm dev

# Run tests
pnpm test

# Lint code
pnpm lint

System Requirements

• Node.js: v18+ (v20+ recommended)
• Audio: macOS (afplay), Linux (ffmpeg/espeak), Windows (PowerShell)
• Network: Internet connection for ElevenLabs API
• API: ElevenLabs account with available characters

License

ISC

Enjoy coding with voice! 🎤✨

Ghost Dev makes your AI assistant truly conversational. Perfect for accessibility, multitasking, or just because hearing your code explained is awesome!