Vibewatch

VibeWatch

> Your AI pair programmer's eyes on your terminal

[](https://www.npmjs.com/package/vibewatch) [](https://opensource.org/licenses/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] 

Options:
  -p, --port         API server port (default: 3333)
  -b, --buffer-size  Log buffer size (default: 100)
  -v, --verbose              Include node_modules in stack traces
  -r, --raw                  Disable noise filtering (keep all output)
  -k, --keep-alive  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

getterminaloutput:

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

getcrashcontext:

{
  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](./docs/planning/PRD.md)
• [Development Roadmap](./docs/planning/ROADMAP.md)
• [Feature Ideas](./docs/planning/FEATURE_IDEAS.md)

Contributing

We welcome contributions! See [CONTRIBUTING.md](./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](./LICENSE) for details.

---

Built with love for the vibe coding community.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: krjordan
• Source: krjordan/vibewatch
• License: MIT

Install and usage instructions live in the source repository linked above.