VibeWatch

Your AI pair programmer's eyes on your terminal

What is VibeWatch?

VibeWatch is a CLI tool that monitors your development commands and exposes terminal output to Claude (or any MCP-compatible AI assistant) in real-time. No more copy-pasting errors - just tell Claude "check my terminal" and it sees everything.

Quick Start

# Install globally
npm install -g vibewatch

# Or run directly with npx
npx vibewatch npm run dev

# Your dev server runs normally, but now Claude can see it!

Then ask Claude: "I'm getting an error, check my terminal" - Claude automatically sees your terminal output via MCP.

Installation

Option 1: Global Install

npm install -g vibewatch
vibewatch npm run dev

Option 2: npx (no install)

npx vibewatch npm run dev

Option 3: Local Development

git clone https://github.com/krjordan/vibewatch.git
cd vibewatch
npm install
npm run build
node dist/cli.js npm run dev

Usage

Basic Usage

Wrap any command with vibewatch:

# JavaScript/TypeScript
vibewatch npm run dev
vibewatch npx next dev
vibewatch yarn dev
vibewatch pnpm dev

# Python
vibewatch python manage.py runserver
vibewatch uvicorn main:app --reload
vibewatch pytest

# Any command
vibewatch cargo run
vibewatch go run main.go

CLI Options

vibewatch [options] <command>

Options:
  -p, --port <number>        API server port (default: 3333)
  -b, --buffer-size <number> Log buffer size (default: 100)
  -v, --verbose              Include node_modules in stack traces
  -r, --raw                  Disable noise filtering (keep all output)
  -k, --keep-alive <seconds> Keep API alive after crash for MCP queries (default: 30)
  -h, --help                 Display help
  -V, --version              Show version

Examples

# Next.js with custom port
vibewatch --port 4444 npx next dev

# Keep API alive for 60 seconds after crash
vibewatch --keep-alive 60 npm run dev

# Disable noise filtering for debugging
vibewatch --raw npm run build

# Larger buffer for long-running processes
vibewatch --buffer-size 500 npm test

MCP Integration

Claude Desktop / Cursor Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json) or Cursor MCP settings:

{
  "mcpServers": {
    "vibewatch": {
      "command": "npx",
      "args": ["-y", "-p", "vibewatch", "vibewatch-mcp"]
    }
  }
}

Or if installed globally (npm install -g vibewatch):

{
  "mcpServers": {
    "vibewatch": {
      "command": "vibewatch-mcp"
    }
  }
}

Available MCP Tools

Tool	Description
get_terminal_output	Get recent terminal output with optional filtering
get_crash_context	Get detailed crash information with stack traces
get_recent_errors	Quick view of recent errors only
ping	Test connectivity

MCP Tool Parameters

get_terminal_output:

{
  lines?: number,           // Max lines to retrieve (default: 50, max: 100)
  filter?: 'all' | 'errors' | 'warnings',  // Filter output type
  detail?: 'errors' | 'context' | 'full'   // Progressive disclosure level
}

get_crash_context:

{
  verbose?: boolean  // Include node_modules/site-packages (default: false)
}

API Endpoints

VibeWatch exposes a local HTTP API for direct queries:

Endpoint	Description
GET /health	Server status and buffer stats
GET /live?lines=50&detail=context	Recent output with progressive disclosure
GET /crash	Crash snapshot (if crashed)
GET /errors	Errors only
GET /context?window=5	Errors with surrounding context

Progressive Disclosure

Save tokens by requesting only what you need:

# Errors only (~200 tokens)
curl 'http://localhost:3333/live?detail=errors'

# Errors with context (~500 tokens)
curl 'http://localhost:3333/live?detail=context'

# Full output (~1000 tokens)
curl 'http://localhost:3333/live?detail=full'

Features

Framework Detection

VibeWatch automatically detects and optimizes for:

• JavaScript: Next.js, Vite, Webpack
• Python: Django, FastAPI, pytest
• General: Node.js, Python, Rust, Go

Smart Filtering

• ANSI code stripping
• Noise reduction (progress bars, HMR updates)
• Repeated line collapsing
• Stack trace filtering (node_modules/site-packages hidden by default)

Error Detection

• Language-aware error pattern matching
• Framework-specific error patterns
• Non-fatal error notifications
• Relevant file path extraction

Crash Handling

• Automatic crash detection
• Buffer snapshot preservation
• Keep-alive mode for post-crash MCP queries
• Exit code and signal reporting

Architecture

[Your Dev Command]
        ↓
[VibeWatch CLI] ─── wraps process, captures output
        ↓
[Circular Buffer] ─── last 100 lines, noise filtering
        ↓
[Fastify API] ─────── localhost:3333
        ↓
[MCP Server] ──────── stdio transport
        ↓
[Claude Desktop/Cursor/Any MCP Client]

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

Documentation

• Product Requirements
• Development Roadmap
• Feature Ideas

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm test
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

Support

• GitHub Issues - Bug reports & feature requests
• Discussions - Questions & ideas

License

MIT - see LICENSE for details.

---

Built with love for the vibe coding community.