npm package: @kapishdima/ai-ledger
Description: AI provider balance and spending tracker for OpenCode
Author: kapishdima
Latest version: 0.0.11

# ai-ledger

AI provider balance and spending tracker for OpenCode

Track your AI API usage across multiple providers (OpenAI, Anthropic, Kimi, MiniMax) directly in OpenCode with automatic cost deduction and beautiful balance visualization.

## Features

- 🔍 **Automatic Provider Detection** - Detects configured AI providers from environment variables
- 💰 **Balance Tracking** - Track spending and remaining balances in real-time
- 📊 **Visual Progress Bars** - Unicode-based progress bars show usage at a glance
- 💾 **Local SQLite Storage** - All data stored locally in `~/.config/opencode/ai-ledger/wallet.db`
- 🎯 **Automatic Cost Deduction** - Automatically deducts costs from AI requests
- 🏦 **Easy Top-ups** - Simple commands to add funds to any provider

## Installation

```bash
npm install ai-ledger
# or
bun add ai-ledger
```

Then add to your OpenCode configuration:

```json
{
  "plugins": ["ai-ledger"]
}
```

## Usage

### Initialize

Detects configured AI providers and shows setup instructions:

```bash
/ledger_init
```

**Example output:**
```
Found 2 AI provider(s):

  /ledger_set openai <amount>    - Set OpenAI balance
  /ledger_set anthropic <amount>    - Set Anthropic balance

Example: /ledger_set openai 50.00
```

### Set Initial Balance

Set the initial balance for a provider:

```bash
/ledger_set openai 50.00
/ledger_set anthropic 25.00
/ledger_set kimi 100.00
```

### Add Funds

Add money to an existing provider balance:

```bash
/ledger_add openai 20.00
```

### Check Balances

View all provider balances with visual progress bars:

```bash
/ledger_balance
```

**Example output:**
```
┌──────────────┬──────────────┬──────────┬────────────────────┐
│ Provider     │ Balance      │ Spent    │ Progress           │
├──────────────┼──────────────┼──────────┼────────────────────┤
│ OpenAI       │  $42.86      │  $7.14   │ ████░░░░░░░░░░░░░░ │
│ Anthropic    │  $25.00      │  $0.00   │ ░░░░░░░░░░░░░░░░░░░░ │
└──────────────┴──────────────┴──────────┴────────────────────┘
```

### Automatic Tracking

Once configured, the plugin automatically tracks all AI requests and deducts costs from your balances. You'll see log messages like:

```
ai-ledger: openai (gpt-4): -$0.0023 | balance: $42.86
```

## Supported Providers

The plugin automatically detects and supports:

- **OpenAI** - Requires `OPENAI_API_KEY`
- **Anthropic** - Requires `ANTHROPIC_API_KEY`
- **Kimi (Moonshot)** - Requires `MOONSHOT_API_KEY`
- **MiniMax** - Requires `MINIMAX_API_KEY`

## Database

Data is stored locally in SQLite at:
```
~/.config/opencode/ai-ledger/wallet.db
```

The database contains two tables:
- `wallets` - Stores provider balances and metadata
- `transactions` - Stores every AI request with cost details

## Requirements

- OpenCode
- Bun runtime (>= 1.0.0)
- Node.js (>= 18.0.0)
- TypeScript (>= 5.0.0)

## Configuration

No additional configuration required! The plugin automatically detects your API keys from environment variables.

## License

MIT

## Contributing

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

## Support

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/yourusername/ai-ledger/issues).