# pi-copilot-usage

A [pi](https://github.com/badlogic/pi-mono) extension that shows your GitHub Copilot premium request usage as a percentage in the status bar.

```
Copilot: 13%
Copilot: 80% ~    ← warning at 75%+
Copilot: 93% !    ← warning at 90%+
```

## Features

- **Zero config** — uses pi's existing GitHub Copilot login, no separate token needed
- **Plan-agnostic** — works with Copilot Pro (300/mo), Pro+ (1500/mo), and Enterprise; shows "unlimited" for uncapped plans
- **Live updates** — refreshes every 60 seconds
- **Overage tracking** — shows `+Nover` if your plan allows overage requests
- `/copilot-usage` command to force an immediate refresh

## Prerequisites

You must be logged in to GitHub Copilot in pi. If you haven't already:

```
/login
```

Select GitHub Copilot and complete the OAuth flow.

## Installation

### Global (all projects)

```bash
pi install npm:pi-copilot-usage
```

### Project-local

```bash
pi install -l npm:pi-copilot-usage
```

### Try without installing

```bash
pi -e npm:pi-copilot-usage
```

## How it works

Reads the OAuth token pi stores at `~/.pi/agent/auth.json` after login and calls `GET /copilot_internal/user` on the GitHub API. This endpoint returns real-time quota snapshots including `percent_remaining`, `entitlement`, and `overage_count` — no billing scope or separate PAT required.

The percentage updates on GitHub's side in real-time as you use Copilot. The extension polls every 60 seconds to keep the status bar current.

## Status indicators

| Display | Meaning |
|---------|---------|
| `Copilot: 13%` | 13% of monthly quota used |
| `Copilot: 80% ~` | 75–89% used, getting close |
| `Copilot: 93% !` | 90%+ used, nearly exhausted |
| `Copilot: 100% +3over !` | Quota exhausted, 3 overage requests used |
| `Copilot: unlimited` | Plan has no cap |
| `Copilot: not logged in (run /login)` | No Copilot auth found |

## License

MIT