DevMate 🤖

AI-powered runtime error fixing for developers using Cursor

Watch DevMate automatically detect and fix runtime errors in your code

📁 Project Structure

| Directory | Description | |-----------|-------------| | src/ | Core source code and TypeScript files | | dist/ | Compiled JavaScript output | | docs/ | Documentation and guides | | example/ | Example projects demonstrating usage | | .github/ | GitHub templates and workflows | | __tests__/ | Test files and test utilities |

🚀 Quick Install

# Using npx (recommended)
npx devmate run --cmd="npm run dev"

# Or install globally
npm install -g devmate
devmate run --cmd="npm run dev"

⚡️ Quick Start

1. Run your app with DevMate

   # For Node.js apps
   devmate run --cmd="node app.js"
   
   # For React apps
   devmate run --cmd="npm run dev"
   
   # For TypeScript apps
   devmate run --cmd="ts-node app.ts"

2. When an error occurs

   • DevMate detects the error
   • Generates a .cursor_prompt.md file
   • Cursor AI suggests a fix

3. Apply the fix

   • Review the suggestion in Cursor
   • Apply the fix with one click
   • Your app continues running

🧠 What is DevMate?

DevMate is a CLI tool that transforms runtime errors into AI-powered fixes. It works by:

1. Detecting runtime errors in your Node.js or browser applications
2. Sending them to GPT for intelligent analysis
3. Generating a .cursor_prompt.md file with fix suggestions
4. Letting Cursor AI automatically apply the fixes

🔍 How it Works

graph LR
    A[Your App] -->|Runtime Error| B[DevMate]
    B -->|Error Analysis| C[GPT]
    C -->|Fix Suggestion| B
    B -->|Generate| D[.cursor_prompt.md]
    D -->|Auto-fix| E[Cursor AI]

1. Run your app with DevMate: devmate run --cmd="npm run dev"
2. DevMate monitors for runtime errors
3. When an error occurs, GPT analyzes it
4. DevMate generates a .cursor_prompt.md with the fix
5. Cursor AI picks up the prompt and offers to fix the code

💡 Features

• 🔍 Smart Error Detection

  • Node.js runtime errors
  • Browser console errors
  • TypeScript compilation errors
  • Custom error pattern support

• 🤖 AI-Powered Analysis

  • GPT-4 integration for intelligent error analysis
  • Context-aware fix suggestions
  • Confidence scoring for suggestions
  • Fallback to template mode if GPT is unavailable

• 📝 Cursor Integration

  • Automatic .cursor_prompt.md generation
  • Structured error context
  • Code snippets with before/after context
  • Step-by-step fix instructions

• ⚡️ Developer Experience

  • Zero configuration to start
  • Real-time error monitoring
  • Optional file watching
  • Automatic server restart

⚙️ Configuration

Create a devmate.config.json in your project root:

{
  "command": "npm run dev",
  "targetLanguage": "typescript",
  "browserToolsEnabled": true,
  "errorPatterns": [
    {
      "type": "TypeScript Error",
      "regex": "TS\\d+",
      "filePathGroup": 1,
      "lineNumberGroup": 2,
      "messageGroup": 3
    }
  ],
  "gpt": {
    "apiKey": "YOUR_API_KEY",
    "model": "gpt-4-turbo-preview",
    "temperature": 0.3,
    "maxTokens": 1000
  }
}

GPT Configuration

DevMate supports OpenAI's GPT models for intelligent error analysis. To configure GPT:

1. Get an API Key

   • Sign up at OpenAI
   • Create an API key in your dashboard
   • Copy the key to your configuration

2. Configure in devmate.config.json

   "gpt": {
     "apiKey": "YOUR_API_KEY",
     "model": "gpt-4-turbo-preview",
     "temperature": 0.3,
     "maxTokens": 1000
   }

3. Test Your Configuration

   npm run test-gpt

4. Security Best Practices

   • Never commit your API key to git
   • Use environment variables:

     # .env file
     OPENAI_API_KEY=your_key_here

   • Or use a secrets manager

5. Template-Only Mode

   • If no API key is provided, DevMate runs in template-only mode
   • Basic error analysis is still available
   • GPT features are disabled

Configuration Options

| Option | Type | Description | |--------|------|-------------| | command | string | Command to run your development server | | targetLanguage | string | Primary language (typescript/javascript) | | browserToolsEnabled | boolean | Enable browser error detection | | errorPatterns | array | Custom error detection patterns | | gpt.apiKey | string | OpenAI API key | | gpt.model | string | GPT model to use | | gpt.temperature | number | Response creativity (0-1) | | gpt.maxTokens | number | Maximum response length |

🧪 Testing

DevMate uses Vitest for testing. To run the tests:

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Test Structure

src/
├── __tests__/
│   ├── promptBuilder.test.ts  # Tests for prompt generation
│   ├── gptService.test.ts     # Tests for GPT integration
│   └── runner.test.ts         # Tests for process runner

Example Tests

// Example test for GPT service
describe('GPTService', () => {
  it('should handle API errors gracefully', async () => {
    const service = new GPTService(config);
    await expect(service.getErrorFix(error))
      .rejects
      .toThrow('Invalid OpenAI API key');
  });
});

🧩 Examples

Check out our example projects:

• Node.js Error Example
• React Error Example

👥 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Cursor for the amazing AI-powered IDE
• OpenAI for the GPT API
• All our contributors and users

🤖 GPT Integration

JSON Response Format

DevMate enforces structured JSON responses from GPT to ensure consistent error analysis. When creating custom prompts:

1. Always Require JSON

   // Good: Explicit JSON requirement
   "You MUST respond ONLY with a valid JSON object: { ... }"
      
   // Bad: Ambiguous format
   "Please provide a response in any format"

2. Include Response Example

   // Good: Clear example
   "Response format:
   {
     'suggestion': 'The fix',
     'explanation': 'Why it works',
     'confidence': 0.9
   }"

3. Handle Parsing Gracefully

   • DevMate attempts multiple parsing strategies:
     1. Direct JSON parsing
     2. JSON extraction from text
     3. Fallback to raw response
   • All responses are structured, even if parsing fails

Example Prompt

const prompt = `
Analyze this error and provide a fix.

IMPORTANT: You MUST respond ONLY with a valid JSON object:
{
  "suggestion": "The complete code fix",
  "explanation": "Brief explanation of why this fixes the issue",
  "confidence": 0.0-1.0
}

Do not include any text outside the JSON object.`;

Response Handling

DevMate automatically handles various response scenarios:

1. Valid JSON

   {
     "suggestion": "Add type annotation",
     "explanation": "Missing type causes TypeScript error",
     "confidence": 0.95
   }

2. JSON in Text

   Here's my analysis:
   {
     "suggestion": "Add type annotation",
     "explanation": "Missing type causes TypeScript error",
     "confidence": 0.95
   }
   Hope this helps!

3. Raw Text Fallback

   You should add a type annotation to fix this error.

   → Automatically converted to structured response