Flowclaw

---
name: FlowClaw
description: "Unkillable LLM load balancer for OpenClaw. Monitors usage across Anthropic, Google, OpenAI, GitHub Copilot, and Ollama. Scores accounts by urgency, rotates automatically, and fails over to local models. Your agent never gets stuck."
metadata:
  openclaw:
    emoji: "🦞"
    os:
      - darwin
      - linux
    requires:
      bins:
        - curl
        - python3
---

# FlowClaw — LLM Usage Monitor & Load Balancer

> *Track usage. Balance routing. Never waste a credit.*

Unified dashboard + auto-routing for all your LLM subscriptions. Uses **Earliest Deadline First** scheduling — accounts resetting soonest are prioritized so unused credits aren't wasted.

## Supported Providers

| Provider | Auth | Data Source |
|----------|------|------------|
| **Anthropic Claude Max** | OAuth (unlimited accounts) | `api.anthropic.com/api/oauth/usage` |
| **Google Gemini CLI** | OAuth via OpenClaw | `cloudcode-pa.googleapis.com` |
| **Google Antigravity** | codexbar | codexbar usage API |
| **OpenAI Codex** | OAuth via OpenClaw | `chatgpt.com/backend-api/wham/usage` |
| **GitHub Copilot** | OAuth via OpenClaw | `api.github.com/copilot_internal/user` |
| **Ollama** | Local (auto-detected) | `localhost:11434/api/tags` |

## Commands

```bash
# 📊 Usage Monitoring
flowclaw status [--fresh] [--json]     # Full provider dashboard
flowclaw monitor [--json] [--cached]   # Clean usage report (no scoring)

# 🧠 Load Balancing
flowclaw score [--json]                # Scored ranking of all accounts
flowclaw optimize [--dry-run]          # Reorder OpenClaw model priority
flowclaw auto                          # Optimize silently (for cron jobs)

# 🛠 Utilities
flowclaw test                          # Run scoring engine unit tests
flowclaw history [N]                   # Routing decision history
```

## Setup

### Anthropic (Claude Max) — unlimited accounts
```bash
claude login
bash {baseDir}/scripts/save-account.sh
# Repeat for each account
```

### Google Gemini CLI
```bash
openclaw models auth login --provider google-gemini-cli
```

### Google Antigravity
```bash
openclaw models auth login --provider google-antigravity
brew install --cask steipete/tap/codexbar   # Required for usage metrics
```

### OpenAI Codex
```bash
openclaw models auth login --provider openai-codex
```

### GitHub Copilot
```bash
openclaw models auth login-github-copilot
```

### Ollama
```bash
brew install ollama && ollama pull qwen3:235b
# Auto-detected — no config needed
```

### Cron Automation
```bash
# Optimize routing every 30 minutes
*/30 * * * * bash ~/clawd/skills/flowclaw/scripts/flowclaw.sh auto
```

## Scoring Algorithm

```
score = urgency(0.30) + availability(0.25) + proximity(0.15) + weekly_headroom(0.20) + tier(0.10)
```

| Factor | Formula | Measures |
|--------|---------|----------|
| Urgency | `remaining / hours_to_reset` | Credits wasting per hour |
| Availability | `√(remaining)` | Dampened capacity |
| Proximity | `1 - (hours / window)` | Deadline pressure |
| Weekly headroom | `(100 - weekly%) / 100` | 7-day capacity reserve |
| Tier bonus | Free=+0.8, Sub=0, Local=-0.3 | Cost preference |

**Perishable inventory:** Both 5h session and 7d weekly windows expire. When ≤6h to weekly reset, penalty is removed — burn remaining credits. **Family-aware:** Only swaps within same capability class (Opus↔Opus, not Opus↔Gemini).