npm package: @mattdef/opencode-quota
Description: OpenCode plugin to display quota and costs for AI providers
Author: Mattdef
Latest version: 1.0.4

# OpenCode Quota Plugin

A plugin for [OpenCode](https://opencode.ai) that displays quota and cost information for your AI providers directly in the terminal.

## Features

- **Real-time quota monitoring** for configured AI providers
- **Parallel fetching** - All providers queried simultaneously
- **Beautiful table output** with color-coded usage indicators
- **Error handling** - Graceful degradation when providers are unavailable
- **Zero configuration** - Automatically reads OpenCode's `auth.json`

## Supported Providers

- ✅ **Claude** (Anthropic) - Quota-based
- ✅ **GitHub Copilot** - Quota-based
- ✅ **OpenRouter** - Pay-as-you-go
- ✅ **Codex** (OpenAI) - Quota-based
- ✅ **Gemini CLI** - Quota-based
- ✅ **Kimi** - Quota-based
- ✅ **OpenCode Zen** - Pay-as-you-go
- ✅ **Antigravity** - Quota-based

## Installation

### Via npm (Recommended)

Add to your `opencode.json`:

```json
{
  "plugin": ["@mattdef/opencode-quota"]
}
```

That's it! OpenCode will automatically install the plugin on next startup.

### Manual Installation

If you prefer to install manually:

```bash
# Create the plugin directory
mkdir -p ~/.config/opencode/plugins/opencode-quota

# Copy plugin files
cp -r dist/* ~/.config/opencode/plugins/opencode-quota/
```

## Usage

In OpenCode, simply type:

```
/quota
```

The plugin will fetch and display quota information for all configured providers.

### Options

- `/quota --all` - Show all providers, including non-configured ones

### Example Output

```
Provider              Type             Usage      Key Metrics
──────────────────────────────────────────────────────────────────────
Claude                Quota-based      23%        77/100 remaining
GitHub Copilot        Quota-based      45%        55/100 remaining
OpenRouter            Pay-as-you-go    -          $12.34 spent
──────────────────────────────────────────────────────────────────────
Quota providers: 2 | Pay-as-you-go: $12.34
```

### Color Coding

- 🟢 **Green** - Usage < 50%
- 🟡 **Yellow** - Usage 50-80%
- 🔴 **Red** - Usage > 80%

## Configuration

No configuration required! The plugin automatically:

1. Reads authentication tokens from OpenCode's `auth.json`
2. Searches multiple locations:
   - `$XDG_DATA_HOME/opencode/auth.json`
   - `~/.local/share/opencode/auth.json`
   - `~/Library/Application Support/opencode/auth.json`

## Troubleshooting

### "No providers configured" message

Make sure you have connected your providers in OpenCode:
```
/connect
```

### Authentication errors

If you see authentication errors, try reconnecting the provider:
```
/connect claude
/connect github_copilot
/connect openrouter
```

### Plugin not loading

Check OpenCode logs for plugin loading errors:
```
opencode --verbose
```

## Development

### Project Structure

```
opencode-quota/
├── src/
│   ├── index.ts                    # Plugin entry point
│   ├── types/
│   │   └── index.ts               # TypeScript interfaces
│   ├── providers/
│   │   ├── ClaudeProvider.ts      # Claude implementation
│   │   ├── CopilotProvider.ts     # Copilot implementation
│   │   ├── OpenRouterProvider.ts  # OpenRouter implementation
│   │   ├── CodexProvider.ts       # Codex implementation
│   │   ├── GeminiCLIProvider.ts   # Gemini CLI implementation
│   │   ├── KimiProvider.ts        # Kimi implementation
│   │   ├── OpenCodeZenProvider.ts # OpenCode Zen implementation
│   │   └── AntigravityProvider.ts # Antigravity implementation
│   ├── services/
│   │   ├── TokenManager.ts        # Auth token management
│   │   ├── ProviderManager.ts     # Parallel fetching
│   │   └── TableFormatter.ts      # Output formatting
│   └── utils/
│       └── colors.ts              # Terminal colors
├── package.json
└── tsconfig.json
```

### Building

```bash
npm install
npm run build
```

### Publishing

```bash
npm login
npm publish --access public
```

### Adding a New Provider

1. Create a new provider class in `src/providers/`:

```typescript
import { ProviderProtocol, ProviderIdentifier, ProviderType, ProviderResult } from '../types/index.js';

export class MyProvider implements ProviderProtocol {
  readonly identifier = ProviderIdentifier.MY_PROVIDER;
  readonly type = ProviderType.QUOTA_BASED; // or PAY_AS_YOU_GO
  readonly fetchTimeout = 10000;

  isConfigured(): boolean {
    // Check if provider is configured
    return true;
  }

  async fetch(): Promise<ProviderResult> {
    // Implementation here
  }
}
```

2. Register in `ProviderManager.initializeProviders()`:

```typescript
this.providers.set(ProviderIdentifier.MY_PROVIDER, new MyProvider());
```

3. Add display name in `TableFormatter.getProviderDisplayName()`

## License

MIT License - See LICENSE file for details.

## Credits

Based on the [OpenCode Bar](https://github.com/kargnas/opencode-bar) project by kargnas.