How do I use VibeWatch?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@VibeWatch check my terminal for errors" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

VibeWatch

Your AI pair programmer's eyes on your terminal

npm version License: MIT

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

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Contribution Guide

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: npm test
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
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.

VibeWatch

VibeWatch

What is VibeWatch?

Quick Start

Installation

Option 1: Global Install

Option 2: npx (no install)

Option 3: Local Development

Usage

Basic Usage

CLI Options

Examples

MCP Integration

Claude Desktop / Cursor Configuration

Available MCP Tools

MCP Tool Parameters

API Endpoints

Progressive Disclosure

Features

Framework Detection

Smart Filtering

Error Detection

Crash Handling

Architecture

Development

Documentation

Contributing

Quick Contribution Guide

Support

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API