# Quick Start Guide

## 🚀 Get Running in 2 Minutes

### Prerequisites
- Node.js installed (for stats server)
- `opencode` CLI installed (`npm install -g @anomalyco/opencode`)
- Web browser (Chrome, Firefox, Safari, Edge)

### Step 1: Start the Stats Server

Open a terminal/PowerShell in the dashboard folder and run:

```powershell
node stats-server.js
```

You should see:
```
OpenCode Stats API running at http://127.0.0.1:9876
Endpoint: GET /agent-metrics
```

### Step 2: Serve the Dashboard

In another terminal, run:

```bash
# Option A: Using Python 3
python -m http.server 8000

# Option B: Using Node http-server
npx http-server
```

### Step 3: Open Dashboard

Navigate to **http://localhost:8000** (or port from Step 2)

You should see the dashboard with all four data sources:
1. ✅ **AISaver Proxy Stats** (fetched locally from https://127.0.0.1:7979)
2. ✅ **OpenCode Command Stats** (from stats-server)
3. ✅ **Balance Tracker** (configurable)
4. ✅ **Cost Analysis** (per-request breakdown)

---

## 📊 Dashboard Sections

### Balance Banner (Top)
- **Starting Balance**: Set your Claude API credit (default $5.33)
- **Current Balance**: Live estimate after all requests
- **Total Spent**: Sum of all request costs
- **Change Over Time**: Visual chart showing balance decline

### Cost Per Request Table
| Column | Meaning |
|--------|---------|
| Balance Before | Your credit before request |
| Cost | Amount deducted |
| Balance After | Your credit after request |
| Full Price | Cost without caching |
| Actual | What you paid after discounts |
| Saved | Cache + compression savings |
| Cache | HIT (green) or MISS (red) |

### Top Overview Cards
- **Credit Balance**: Est. available funds
- **Session Cost**: Total spent this session
- **Prefix Cache**: Hit rate & savings
- **Token Volume**: Total tokens processed

### OpenCode Stats Section
Shows real-time data from `opencode stats` command:
- **OVERVIEW**: Sessions, Messages, Days
- **COST & TOKENS**: Total cost, per-day avg, token metrics
- **TOOL USAGE**: Bar chart of tool usage (bash, read, edit, etc.)

### Request Metrics
- Total requests to FARoom proxy
- Cached vs uncached ratio
- Average latency & TTFB
- Model being used

### Session Overview
- Requests count
- Token totals
- Savings percentage
- Session start/last activity times

---

## ⚙️ Configuration

### Configure your client (Anthropic/Claude models only)

> **Important:** The proxy works **only with Anthropic/Claude models**.
> GPT, Gemini, and other models will not be routed through it.

Point your client **directly** at the local proxy — no Windows/system proxy and
no public cloud URL. In Cursor, go to **Settings → Models** and configure:

1. **OpenAI API Key** — toggle ON, and paste your **Anthropic API key** here
   *(yes — the Anthropic key goes in the OpenAI field)*
2. **Override OpenAI Base URL** — toggle ON, enter:
   ```
   https://127.0.0.1:7979/v1
   ```
3. **Anthropic API Key** — leave toggled **OFF** (do not fill in)

> The proxy listens on `127.0.0.1:7979` and serves any client whose baseURL
> points straight at it — no need to register it as the Windows system proxy /
> `HTTPS_PROXY`. On first run it creates and trusts a local root CA so its
> self-signed TLS cert is accepted.

> Despite the "OpenAI" label, this is the field Cursor uses to route requests
> when a custom base URL is set. The proxy forwards your Anthropic key to
> Anthropic. If you enable the separate Anthropic API Key field, Cursor will
> bypass the proxy for Claude models.

### Set Starting Balance

In the balance banner at the top, enter your starting balance and click **Set**. This persists to browser storage.

### Change Refresh Interval

Edit `app.js` line ~10:
```javascript
REFRESH_INTERVAL: 2000,  // milliseconds
```

### Change Stats Server Port

Edit `stats-server.js` line ~8:
```javascript
const PORT = 9876;  // Change this
```

Then update `app.js` line ~11:
```javascript
OPENCODE_STATS_URL: 'http://127.0.0.1:9876/agent-metrics',
```

---

## 🔧 Troubleshooting

### "Connection Failed" message?

1. **Check AISaver proxy is running**
   ```powershell
   curl -sk https://127.0.0.1:7979/stats
   ```

2. **Check stats server is running**
   ```powershell
   curl http://127.0.0.1:9876/agent-metrics
   ```

3. **Check browser console (F12)** for CORS/network errors

### Stats server says "command not found: opencode"?

Make sure `opencode` CLI is installed:
```bash
npm install -g @anomalyco/opencode
opencode --version
```

### Port already in use?

Change the port and update both server and dashboard config.

---

## 📈 What the Numbers Mean

### Cost Analysis Example
If you see:
- **Full price**: $2.16
- **Actual cost**: $1.90
- **Savings**: -$0.26

It means:
- Without caching, you'd pay $2.16
- With caching, you paid $1.90
- **You saved $0.26 (12%)**

### Token Sizes
- **K** = Thousand (1,000)
- **M** = Million (1,000,000)
- Example: `122.7K` = 122,700 tokens

### Per-Request Calculation
For each request, cost is calculated as:
```
cost = (input_tokens / 1,000,000) × input_price +
       (output_tokens / 1,000,000) × output_price
```

Then discounted by cache/compression savings.

---

## 📱 Browser Support

- ✅ Chrome 90+
- ✅ Firefox 88+
- ✅ Safari 14+
- ✅ Edge 90+

Requires ES6+ JavaScript.

---

## 🎨 Design Features

- **Glassmorphism**: Frosted glass cards with blur effect
- **Animated Orbs**: Floating background gradient orbs
- **Real-time Updates**: 2-second auto-refresh
- **Glow Effects**: Accent borders that glow on hover
- **Scanline Overlay**: Retro CRT monitor effect
- **Smooth Animations**: Cubic-bezier transitions

---

## 💡 Tips

1. **Bookmark balance value**: Manually set balance if it drifts due to external usage
2. **Monitor tool usage**: Check which OpenCode tools consume most time
3. **Track cache hit rate**: Higher % = better optimization
4. **Review cost trends**: Use the balance chart to spot expensive operations

---

Need help? Check **README.md** for full documentation.
