# 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
```bash
# 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
```bash
npm install -g vibewatch
vibewatch npm run dev
```
### Option 2: npx (no install)
```bash
npx vibewatch npm run dev
```
### Option 3: Local Development
```bash
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`:
```bash
# 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
```bash
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
```bash
# 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:
```json
{
"mcpServers": {
"vibewatch": {
"command": "npx",
"args": ["-y", "-p", "vibewatch", "vibewatch-mcp"]
}
}
}
```
Or if installed globally (`npm install -g vibewatch`):
```json
{
"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:**
```typescript
{
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:**
```typescript
{
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:
```bash
# 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
```bash
# 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](https://github.com/krjordan/vibewatch/issues) - Bug reports & feature requests
- [Discussions](https://github.com/krjordan/vibewatch/discussions) - Questions & ideas
## License
MIT - see [LICENSE](./LICENSE) for details.
---
Built with love for the vibe coding community.
