claudewatch/README.md

Automated validation and self-healing system for Claude Code projects

# ClaudeWatch

Automated validation and self-healing system for Claude Code projects. ClaudeWatch automatically validates your web applications for visual elements, accessibility, performance, and more—then intelligently fixes common issues.

[![npm version](https://badge.fury.io/js/claudewatch.svg)](https://badge.fury.io/js/claudewatch)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Visual Analysis** - Screenshot capture and comprehensive page structure analysis
- **Comprehensive Validation** - Visual elements, accessibility, performance, forms, APIs
- **Task Alignment Verification** - Combines DOM analysis with content evaluation
- **Design Quality Assessment** - Evaluates layout, structure, and content alignment
- **Self-Healing** - Automatically fixes common issues (missing alt text, console errors, broken links)
- **Multi-Viewport Testing** - Desktop, tablet, and mobile responsive testing
- **Claude Code Integration** - Runs automatically when you complete tasks
- **Detailed Reports** - Screenshots, validation insights, and technical logs for every test
- **Fast Setup** - One command to get started

## Quick Start

### For Claude Code Users (Recommended)

Tell Claude to install ClaudeWatch:

```bash
npm install -g claudewatch
claudewatch claude-setup
```

ClaudeWatch will now automatically validate your work whenever Claude completes a task.

### Manual Installation

```bash
# Install globally
npm install -g claudewatch

# Initialize in your project
cd your-project
claudewatch init

# Visual analysis is enabled by default

# Start your dev server, then run validation
npm start
claudewatch validate
```

### Visual Analysis Features

ClaudeWatch provides comprehensive visual validation:

1. **Screenshot Capture**: Automatically captures full-page screenshots
2. **Content Analysis**: Analyzes page structure and content alignment
3. **Task Verification**: Compares results against original requirements

## Commands

| Command | Description |
|---------|-------------|
| `claudewatch claude-setup` | Quick setup optimized for Claude Code |
| `claudewatch init` | Initialize ClaudeWatch in your project |
| `claudewatch validate` | Run validation tests |
| `claudewatch self-heal` | Run validation with automatic fixes |
| `claudewatch status` | Show system status and configuration |
| `claudewatch report` | View validation history and reports |
| `claudewatch config` | Open configuration file in editor |
| `claudewatch cleanup` | Clean up old logs and screenshots |

## What Gets Validated

### Visual Elements
- Required page elements exist (h1, nav, forms, etc.)
- Page loads without critical errors
- Screenshots captured and AI-analyzed for visual quality
- **Visual Analysis** - Captures screenshots and analyzes page structure
- **Task Alignment Verification** - Compares page content against original request
- **Layout & Design Quality** - Evaluates structure, hierarchy, and responsive design
- **Content Analysis** - Validates headings, buttons, forms align with requirements

### Accessibility
- Images have alt text
- Proper heading hierarchy (h1, h2, h3...)
- Color contrast compliance
- Keyboard navigation support

### Performance
- Page load times under thresholds
- Core Web Vitals monitoring
- Animation performance optimization

### Forms & Interactions
- Form validation works correctly
- Error messages display properly
- Submit buttons are functional

### APIs & Network
- API endpoints respond correctly
- Health check monitoring
- Network request validation

### Console & Errors
- No JavaScript errors
- No console warnings
- Clean developer console

### Links & Navigation
- No broken links
- Navigation functions properly
- External link validation

## Visual Task Alignment

ClaudeWatch provides comprehensive visual validation by combining screenshot analysis with DOM inspection:

- **Screenshot Analysis** - Captures and analyzes page screenshots across viewports
- **Visual Structure Assessment** - Analyzes layout, hierarchy, and responsive design
- **Content Matching** - Compares page title, headings, and text against the task description
- **UI Pattern Recognition** - Detects if requested elements (forms, buttons, navigation) are present
- **Confidence Scoring** - Combines DOM analysis with content evaluation for accurate assessment
- **Detailed Insights** - Provides specific observations about structure and missing elements

### How It Works

1. **Task Context** - Captures the last Claude task from environment variables
2. **Screenshot Capture** - Takes full-page screenshots across all viewports
3. **DOM Analysis** - Analyzes structural elements, content, and responsive indicators
4. **Visual Analysis** - Examines page structure and content alignment with task requirements
5. **Confidence Scoring** - Combines technical analysis with content assessment
6. **Detailed Reporting** - Provides comprehensive feedback with actionable insights

## Self-Healing Capabilities

ClaudeWatch can automatically fix:

- **Missing Alt Text** - Adds descriptive alt text to images
- **Console Errors** - Removes debug errors and fixes undefined variables
- **Broken Links** - Replaces broken external links
- **API Errors** - Fixes simple endpoint issues
- **Performance Issues** - Optimizes animations and transitions
- **Missing Resources** - Creates placeholder images and files
- **Accessibility Issues** - Fixes contrast and heading problems

## Project Structure After Setup

```
your-project/
├── .claudewatch/
│   ├── config.js          # Validation configuration
│   ├── validator.js       # Main validation script
│   └── self-healer.js     # Self-healing script
├── .claude/
│   └── settings.json      # Claude Code hook configuration
├── validation-logs/       # Detailed JSON reports
├── validation-screenshots/ # Screenshots from all viewports
└── CLAUDE.md              # Instructions for Claude
```

## Configuration

Edit `.claudewatch/config.js` to customize validation:

```javascript
module.exports = {
  baseUrl: 'http://localhost:3000',
  
  pages: [
    {
      path: '/',
      name: 'homepage',
      validations: ['h1', 'nav', '.hero-section'],
      
      forms: [{
        selector: '.contact-form',
        submitButton: 'button[type="submit"]',
        testInvalidData: {
          field: 'input[name="email"]',
          value: 'invalid-email'
        },
        errorSelector: '.error-message'
      }],
      
      apis: [
        { url: '/api/health' },
        { url: '/api/user/profile' }
      ]
    }
  ],
  
  validationTypes: {
    visual: true,
    accessibility: true,
    performance: true,
    forms: true,
    api: true,
    console: true,
    links: true
  }
};
```

## Claude Code Integration

When you install ClaudeWatch with `claude-setup`, it automatically:

1. **Sets up hooks** - Runs validation after each task completion
2. **Creates instructions** - Adds `CLAUDE.md` with guidance for Claude
3. **Enables self-healing** - Automatically fixes common issues
4. **Configures todo lists** - Reminds Claude to include validation tasks

### Example Claude Workflow

```
User: "Add a contact form to the homepage"

Claude: I'll add a contact form to your homepage.

[Claude implements the form]

Auto-validation triggers via hook
Self-healing fixes any issues found
Report generated with screenshots
Summary sent to Claude

Claude: "Contact form added and validated! ClaudeWatch confirmed:
- Form elements present
- Validation working
- Accessibility compliant
- Mobile responsive"
```

## Understanding Reports

### Validation Logs (`validation-logs/`)
- Detailed JSON reports with timestamps
- Error details and warnings
- Performance metrics
- Test results by viewport

### Screenshots (`validation-screenshots/`)
- Full-page screenshots for each viewport
- Visual confirmation of your changes
- Regression testing reference

### Self-Healing Logs
- What issues were found
- Which fixes were applied
- Success/failure status

## Advanced Usage

### Custom Validation Types

Add your own validation logic:

```javascript
// In .claudewatch/config.js
pages: [{
  path: '/dashboard',
  name: 'dashboard',
  customValidations: async (page) => {
    // Custom validation logic
    const userCount = await page.textContent('.user-count');
    return parseInt(userCount) > 0;
  }
}]
```

### Environment-Specific Config

```javascript
module.exports = {
  baseUrl: process.env.NODE_ENV === 'production' 
    ? 'https://myapp.com'
    : 'http://localhost:3000',
  // ...
};
```

### CI/CD Integration

```yaml
# .github/workflows/validate.yml
- name: Run ClaudeWatch Validation
  run: |
    npm start &
    sleep 5
    claudewatch validate
    kill %1
```

## License

MIT License - see [LICENSE](LICENSE) file.

## Support

- [Documentation](https://github.com/PolarOrchid/ClaudeWatch/wiki)
- [Report Issues](https://github.com/PolarOrchid/ClaudeWatch/issues)
- [Discussions](https://github.com/PolarOrchid/ClaudeWatch/discussions)

## Credits

Built for the Claude Code community to enable automated, intelligent validation of web applications.

---

**Made by PolarOrchid for Claude Code developers**

© 2025 PolarOrchid - [PolarOrchid.com](https://PolarOrchid.com)