vibe-stocks/README.md

Terminal-based stock market viewer with real-time data streaming

# vibe-stocks

A terminal-based stock market viewer with real-time data streaming. Get live market data right in your terminal!

![vibe-stocks demo](https://img.shields.io/badge/terminal-stock_viewer-cyan)

## Installation

```bash
npx vibe-stocks
```

Or install globally:

```bash
npm install -g vibe-stocks
```

## Usage

### Stream Real-Time Quotes

```bash
# Stream default stocks (AAPL, MSFT, GOOGL, AMZN, TSLA)
vibe-stocks stream

# Stream specific stocks
vibe-stocks stream NVDA AMD COIN TSLA

# Compact mode
vibe-stocks stream --compact AAPL MSFT
```

### Market Overview

Interactive market overview with multiple views:

```bash
vibe-stocks market

# Show top 20 stocks
vibe-stocks market --top 20
```

Keyboard shortcuts:
- `1` - Overview
- `2` - Top Gainers
- `3` - Top Losers
- `Ctrl+C` - Exit

### View Stock Quote

```bash
vibe-stocks quote AAPL
vibe-stocks quote TSLA
```

### Display Price Chart

```bash
# Default 1-month chart
vibe-stocks chart AAPL

# 1-year chart
vibe-stocks chart NVDA --period 1y

# Custom height
vibe-stocks chart MSFT --period 6m --height 20
```

## Features

- 📈 Real-time streaming quotes via WebSocket
- 🎨 Beautiful terminal UI with colors
- 📊 ASCII price charts
- 🔥 Extreme mover alerts
- 💹 Market overview with gainers/losers
- 🚀 No API key required
- ⚡ Fast and lightweight

## Examples

### Stream Multiple Stocks
```bash
vibe-stocks stream AAPL MSFT GOOGL AMZN META NVDA TSLA
```

### Market Overview
```bash
vibe-stocks market
```

Output:
```
Vibe Stocks - Market Overview
Last Update: 3:45:23 PM

↑ 28 Gainers | ↓ 22 Losers

🔥 Extreme Movers (>3%)
  COIN: $245.67 +8.92%
  NVDA: $982.45 +5.23%
  TSLA: $412.34 -4.56%

Symbol   Name                    Price      Change    Volume
─────────────────────────────────────────────────────────────
COIN     Coinbase Global        $245.67     +8.92%    15.2M
NVDA     NVIDIA Corporation     $982.45     +5.23%    45.6M
AAPL     Apple Inc              $213.45     +0.85%    38.9M
```

### Price Chart
```bash
vibe-stocks chart AAPL --period 1m
```

Output:
```
AAPL Price Chart - 1m
Last Update: 3:45:30 PM

    215.00 ┤                    ╭─╮
    214.50 ┤                   ╱  ╰╮
    214.00 ┤               ╭──╯    ╰─╮
    213.50 ┤          ╭───╯          ╰──╮
    213.00 ┤      ╭──╯                  ╰───
    212.50 ┤  ╭──╯
    212.00 ┼──╯

Range: $212.00 - $215.00
Period Change: +0.85%
```

## Data Source

Real-time market data is provided by MCP Server (Model Context Protocol), which aggregates data from multiple financial data providers. No API key is required as this uses public endpoints.

## Supported Symbols

- **US Stocks**: AAPL, MSFT, GOOGL, AMZN, TSLA, etc.
- **ETFs**: SPY, QQQ, DIA, IWM, etc.
- **Crypto-related**: COIN, MSTR, etc.

## Requirements

- Node.js 14.0.0 or higher
- Terminal with ANSI color support
- Internet connection

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License

## Author

Created by Shawn Carpenter

## Disclaimer

This tool is for informational purposes only. Stock market data may be delayed. Always verify data with official sources before making investment decisions.