tokus

Ollama Cloud token usage manager - multi-account, live TUI, opencode integration, auto-switching API keys

Features

• 🔐 Multi-account management - Add, list, verify, and switch between Ollama Cloud accounts
• 📊 Live TUI dashboard - Real-time token usage with tokus watch
• 🔄 Auto-switching circular queue - Automatically switches to next API key when any account hits >90% daily limit
• 🔗 opencode integration - Detects active account, provides drop-in TUI components
• 🔒 Secure key storage - OS Keychain (macOS Keychain, Windows Credential Manager, Linux libsecret)
• ⚙️ Configurable - Poll intervals, thresholds, cooldowns
• 🐚 Shell completions - Bash, Zsh, Fish

Installation

npm (recommended)

npm install -g tokus

Go install

go install github.com/SoulBreaker9/tokus@latest

Download binary

Download from GitHub Releases

Quick Start

# Initialize (detects opencode, sets up completions)
tokus init

# Add an account
tokus account add --email you@gmail.com --api-key ollama_cloud_sk_...

# View status
tokus status

# Live dashboard
tokus watch

# opencode integration
tokus opencode detect

Commands

Command	Description
tokus / tokus status	Show all accounts with usage
tokus watch	Live TUI dashboard (60s updates)
tokus account add	Add new account (interactive or flags)
tokus account list	List all accounts
tokus account remove <email>	Remove account
tokus account use <email>	Set default account
tokus account verify <email>	Verify API key
tokus account sync	Sync with opencode config
tokus provider list	List supported providers
tokus config get/set/show	Manage configuration
tokus init	First-run wizard
tokus opencode detect	Show opencode's active account
tokus opencode install	Print integration code for opencode
tokus completion <shell>	Generate shell completions

Auto-Switching Queue

When any account reaches 90% daily limit (configurable), tokus automatically switches to the next healthy account in the queue:

Account A (95% used) → Auto-switch → Account B (healthy) → Request succeeds

Features:

• Circular queue across all configured accounts
• Configurable threshold (default 90%)
• Cooldown period between switches (default 5 min)
• Health tracking (marks unhealthy after 3 consecutive failures)
• Background polling updates usage in real-time

opencode Integration

tokus provides a drop-in slider component for opencode's editor area:

// In opencode's editor.go
import "github.com/SoulBreaker9/tokus/tui"

tokenBar := tui.NewTokenUsageBar()
editorContainer = layout.NewContainer(
    layout.WithTopPanel(tokenBar),
    layout.WithBottomPanel(textarea),
)

The slider:

• Only appears when opencode uses an Ollama Cloud model
• Shows session % + weekly indicator + chevron
• Click/Enter expands to show session + weekly + daily breakdown
• Auto-updates every 60 seconds

Run tokus opencode install for complete integration code.

Configuration

Config file: ~/.config/tokus/accounts.json

{
  "accounts": {
    "work@gmail.com": {
      "email": "work@gmail.com",
      "alias": "work",
      "provider": "ollama",
      "apiKeyRef": "work@gmail.com",
      "addedAt": "2026-01-15T10:00:00Z",
      "verified": true,
      "accountId": "ollama_acc_123",
      "plan": "pro"
    }
  },
  "activeAlias": "work",
  "pollInterval": 60,
  "queue": {
    "enabled": true,
    "thresholdPercent": 90,
    "cooldownSeconds": 300,
    "maxRetries": 3
  }
}

API keys are stored in OS Keychain, not in config file.

Development

# Clone
git clone https://github.com/SoulBreaker9/tokus
cd tokus

# Install deps
go mod tidy

# Build
make build

# Test
make test

# Run
./bin/tokus status

Cross-Platform Builds

Built with GoReleaser for:

• Linux (amd64, arm64)
• macOS (amd64, arm64)
• Windows (amd64, arm64)

License

MIT License - see LICENSE

Contributing

1. Fork the repository
2. Create feature branch
3. Make changes with tests
4. Run make check
5. Submit PR

Related

• opencode - The AI coding agent tokus integrates with
• Ollama Cloud - The service tokus monitors