vstat

Vibe Stats - AI Dev Tools Status Monitor

A Chrome/Edge browser extension that monitors the real-time status of AI developer tools (Claude AI and GitHub Copilot) with cool AI-themed vibe indicators and comprehensive incident reporting through an intuitive popup interface.

Chrome Extension Manifest V3 Status AI Powered

📄 Privacy Policy - Learn about our data collection and privacy practices

✨ Features

🚀 Quick Start

For End Users

  1. Install from Chrome Web Store (coming soon)
  2. Or load unpacked for development: 
    git clone https://github.com/todddube/vstat.git
cd vstat
# Open chrome://extensions/ → Enable Developer Mode → Load Unpacked → Select this folder

For Developers

# Clone the repository
git clone https://github.com/todddube/vstat.git
cd vstat

# Install test dependencies
cd tests && npm install && cd ..

# Run tests
npm test

# Build for production
npm run build

# Run visual tests
npm run test:visual

📋 Installation Instructions

Coming soon - Extension will be available on Chrome Web Store

Method 2: Load Unpacked (Development/Testing)

  1. Download the Extension: 
    git clone https://github.com/todddube/clstat.git
# OR download ZIP from GitHub and extract
  2. Install in Chrome/Edge:
    • Open Chrome and navigate to chrome://extensions/
    • Enable “Developer mode” (toggle in top-right corner)
    • Click “Load unpacked”
    • Select the vstat directory (or build/ for production build)
    • The Claude status icon should appear in your browser toolbar
  3. Pin the Extension:
    • Click the puzzle piece icon in the toolbar
    • Pin the Claude Status Monitor for easy access

Method 3: Production Build

# Build production-ready extension
npm run build

# Load the ./build directory in Chrome
# This gives you the exact same files that would be on the Chrome Web Store

System Requirements

🎯 Usage Guide

🚥 Status Icon Meanings

Icon Status Badge Description
⚡ Green Operational None All dev tools are vibing! 🔥
⚡ Yellow Minor Issues Number (1-4+) Some services affected, shows count
⚡ Red Major/Critical ! or Number Significant service disruption
⚡ Gray Unknown None Cannot determine status (network/API error)

📱 Popup Interface

Click the extension icon to open a detailed status popup with two main sections:

🚨 Active Issues Tab

📚 Last 5 Incidents Tab

⌨️ Keyboard Shortcuts

🏗️ Architecture & Development

📁 Project Structure

vstat/
├── 📄 manifest.json              # Extension configuration (Manifest V3)
├── ⚙️ background.js              # Service worker (dual-service monitoring)
├── 🎨 popup.html                 # Popup interface HTML
├── 📱 popup.js                   # Popup interface logic
├── 🤖 icons/                     # Cool AI-themed vibe icons (16px to 128px)
│   ├── ai-vibe-16.png            # Toolbar icon (small)
│   ├── ai-vibe-32.png            # Standard icon
│   ├── ai-vibe-48.png            # Large icon
│   └── ai-vibe-128.png           # Extension page icon
├── 🛠️ dev/                       # Development tools and assets
│   ├── scripts/                  # Utility scripts (version sync, etc.)
│   └── README.md                 # Development tools documentation
├── 🎨 design/                    # Design assets and tools
│   └── cool-vibe-icons.html     # Icon generator tool
├── 🧪 tests/                     # Comprehensive test suite
│   ├── unit/                     # Unit tests for components
│   ├── integration/              # Integration tests
│   ├── visual-test-viewer.html   # Interactive visual testing
│   ├── VISUAL_TESTING.md         # Visual testing guide
│   └── README.md                 # Testing documentation
├── 🔧 build-extension.js         # Production build script
├── 📖 BUILD.md                   # Build system documentation
└── 📚 README.md                  # This documentation

🔧 Core Components

Service Worker (background.js)

Popup Interface (popup.js + popup.html)

AI-Themed Vibe Icon System

🧪 Testing

Comprehensive Test Suite

The extension includes a full testing framework with both automated and visual testing capabilities:

# Run all tests
npm test

# Run visual tests with browser interface
npm run test:visual

# Open interactive visual testing tool
npm run visual:viewer

# Validate visual assets
npm run visual:validate

Test Coverage

Visual Testing Tools

📖 Complete Testing Documentation

📦 Building for Production

Quick Build Commands

# Validate all files before building
npm run validate

# Build production-ready zip file
npm run build

# Build and clean up temporary files  
npm run build:clean

# Complete release preparation (validate + build)
npm run prepare-release

Build Output

Chrome Web Store Submission

  1. Run npm run build to create production zip
  2. Go to Chrome Developer Dashboard
  3. Upload the zip file from ./dist/ directory
  4. Complete store listing information and submit for review

📖 Complete Build Documentation

🚀 Release Management

Automated Release Workflow

The project includes a GitHub Action for automated releases that handles version bumping, building, tagging, and creating GitHub releases.

Quick Release Commands

# Check version sync status
npm run version:check

# Sync versions (manifest.json is source of truth)
npm run version:sync

# Prepare for release (build and validate)
npm run prepare-release

# Ready for GitHub Action release
npm run release:patch    # For patch releases (1.0.0 → 1.0.1)
npm run release:minor    # For minor releases (1.0.0 → 1.1.0)
npm run release:major    # For major releases (1.0.0 → 2.0.0)

GitHub Action Release Process

The automated release workflow is triggered manually from the GitHub Actions tab:

  1. Go to GitHub Actions: Navigate to the Actions tab in your repository
  2. Select Release Workflow: Choose “Release Build and Deploy”
  3. Run Workflow: Click “Run workflow” and specify:
    • Version Type: patch, minor, or major
    • Release Notes: Optional custom notes for the release

What the GitHub Action Does

The automated workflow performs these steps:

  1. 📋 Version Management:
    • Reads current version from manifest.json
    • Bumps version according to semver (patch/minor/major)
    • Updates both manifest.json and package.json
  2. 🔍 Validation & Build:
    • Validates all extension files
    • Runs the build process with npm run build:clean
    • Creates production-ready zip file
  3. 📝 Git Operations:
    • Commits version changes to repository
    • Creates and pushes git tag (e.g., v1.2.3)
    • Pushes changes to main branch
  4. 🚀 GitHub Release:
    • Creates GitHub release with changelog
    • Attaches extension zip file and manifest
    • Generates Chrome Web Store submission notes
  5. 📦 Chrome Web Store Prep:
    • Provides submission checklist
    • Includes store description template
    • Ready-to-upload zip file

Manual Version Management

For more granular control, use the version sync utilities:

# Set specific version
npm run version:set 1.2.3

# Bump version types
npm run version:bump patch   # 1.0.0 → 1.0.1
npm run version:bump minor   # 1.0.0 → 1.1.0
npm run version:bump major   # 1.0.0 → 2.0.0

# Check if manifest.json and package.json are in sync
npm run version:check

# Sync package.json to manifest.json version
npm run version:sync

# Check About popup version consistency
npm run about:check

Release Workflow Best Practices

  1. Pre-Release Checklist:
    • ✅ All tests pass: npm test
    • ✅ Visual tests validate: npm run test:visual
    • ✅ Build succeeds: npm run prepare-release
    • ✅ Extension loads and works in Chrome
  2. Release Types:
    • Patch: Bug fixes, small improvements
    • Minor: New features, significant enhancements
    • Major: Breaking changes, major redesigns
  3. Post-Release:
    • ✅ Download zip from GitHub release
    • ✅ Submit to Chrome Web Store Developer Dashboard
    • ✅ Test released version in clean browser profile

Release Files Structure

After a GitHub Action release, you’ll find:

📦 GitHub Release Assets:
├── 📁 vibe-stats-v1.2.3.zip      # Ready for Chrome Web Store
├── 📄 manifest.json              # Updated manifest file
└── 📝 Release Notes               # Automated changelog

🌐 Chrome Web Store Submission:
├── 📋 Submission checklist
├── 📝 Store description template
└── 🔗 Developer dashboard link

📖 Complete Build Documentation 🚀 Detailed Release Guide

🔗 API Integration

Dual-Service API Integration

Anthropic Status APIs (Claude AI):

GitHub Status APIs (GitHub Copilot):

Status Mapping Logic

| API Response | Extension Status | Icon Color | Badge | |————–|——————|————|——–| | none, operational | Operational | 🟢 Green | None | | minor | Minor Issues | 🟡 Yellow | Service count | | major, critical | Major Issues | 🔴 Red | ! or count | | Network/Parse Error | Unknown | ⚪ Gray | None |

🛠️ Development Setup

Prerequisites

Development Workflow

  1. Clone and Setup: 
    git clone https://github.com/todddube/vstat.git
cd vstat
cd tests && npm install && cd ..
  2. Load in Browser:
    • Open chrome://extensions/
    • Enable Developer Mode
    • Load Unpacked → Select project directory
  3. Development Cycle: 
    # Make changes to code
   
# Test changes
npm test
   
# Test visual components
npm run test:visual
   
# Build for testing
npm run build
   
# Reload extension in Chrome
  4. Debugging:
    • Background Script: chrome://extensions/ → “Inspect views: service worker”
    • Popup Interface: Right-click extension icon → “Inspect popup”
    • Console Logs: Check both background and popup consoles

Icon Development

The extension uses custom AI-themed vibe icons optimized for high-resolution displays. Icon development tools are located in the dev/icon-generator/ folder:

AI Vibe Icon Generator

# Open the HTML icon generator in your browser
start dev/icon-generator/create-ai-vibe-icons.html
# Or double-click the file to open in default browser

See dev/README.md for detailed usage instructions.

Icon Features

Icon Development Workflow

  1. Open dev/icon-generator/create-ai-vibe-icons.html in browser
  2. Icons are auto-generated with download links
  3. Download all four sizes (ai-vibe-16.png through ai-vibe-128.png)
  4. Replace existing files in icons/ folder
  5. Reload extension in Chrome to see changes

🔧 Configuration

Extension Settings

The extension uses sensible defaults that work for most users:

Customization

Advanced users can modify settings by editing:

🐛 Troubleshooting

Common Issues

🔴 Extension Not Loading

Symptoms: Extension doesn’t appear in toolbar Solutions:

🟡 Status Not Updating

Symptoms: Icon stays gray or doesn’t change Solutions:

🔴 Popup Not Opening

Symptoms: Clicking icon does nothing or shows errors Solutions:

🔄 Performance Issues

Symptoms: Browser slowdown or high memory usage Solutions:

Debug Tools

Getting Help

📚 Documentation Index

🤝 Contributing

Development Contributions

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Test your changes: npm test && npm run test:visual
  4. Build and validate: npm run prepare-release
  5. Commit with clear messages: git commit -m 'Add amazing feature'
  6. Push to your fork: git push origin feature/amazing-feature
  7. Create a Pull Request with detailed description

Code Standards

Testing Requirements

📄 License

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

⭐ Acknowledgments

🔗 Quick Links

Made with ❤️ for the Claude community