I Built a Skill So Claude Automatically Routes Tasks to Free-Tier AI Providers

Here’s a problem I kept running into: I have free-tier access to Groq, OpenAI, Gemini, and MiniMax — but managing them manually is painful. Wrong tool for the job, accidentally burning through monthly limits, no visibility into what’s been used.

I built agent-hub to fix this. It’s a Claude Code skill that makes Claude the orchestrator — every task is automatically classified, routed to the best provider, tracked against free limits, and shown in a live status bar.

How it works

Claude classifies every incoming message into a task type and routes it:

Classification happens before calling any API — router.py checks token budgets in usage.json, picks the best available provider, calls its API, and returns the response.

Auto-fallback: when a provider drops below 10% of its free tier, traffic automatically shifts to its fallback (Groq→Gemini, Codex→Groq, Gemini→MiniMax, MiniMax→Gemini).

Hard stop: if both primary and fallback are exhausted, the router surfaces it to the user and stops. No silent failures.

The status bar

Every response starts with a live usage bar:

[GROQ ●] Groq: 1,240/14,400 · Codex: 77/500 · Gemini: 108K/1M · MiniMax: 220K/1M

• ● green — above 50% remaining
• ● yellow — 10–50% remaining
• ● red — below 10% (fallback active)
• ○ gray — exhausted

The active provider appears first in brackets. All four counts are always shown.

Free tier limits

Install

SKILL_DIR="$HOME/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.5/skills/agent-hub"
mkdir -p "$SKILL_DIR/tests"
curl -o "$SKILL_DIR/router.py" https://raw.githubusercontent.com/LakshmiSravyaVedantham/agent-hub/main/router.py
curl -o "$SKILL_DIR/SKILL.md" https://raw.githubusercontent.com/LakshmiSravyaVedantham/agent-hub/main/SKILL.md

Then set your keys:

ROUTER="$SKILL_DIR/router.py"
python3 $ROUTER set-key groq gsk_...
python3 $ROUTER set-key codex sk-...
python3 $ROUTER set-key gemini AIza...
python3 $ROUTER set-key minimax ...
python3 $ROUTER set-key minimax-group-id ...

Keys are stored in ~/.claude/agent-hub/.env with chmod 600 — never in code or skill files.

Usage

In any Claude Code session:

superpowers:agent-hub

Claude validates your keys, shows the initial token bar, and from that point every message is classified and routed automatically. You don’t think about providers — Claude does.

Or call router.py directly:

python3 $ROUTER route "explain how transformers work" --type research
python3 $ROUTER status
python3 $ROUTER reset groq

Under the hood

router.py is ~530 lines of Python 3.8+, two dependencies (requests, python-dotenv), 61 tests. Auto-reset logic zeros daily counters at UTC midnight and monthly counters on the 1st. Atomic writes to usage.json via .tmp + rename — no partial writes.

What’s next

• Three-agent coordination — tested with one session, curious how routing behaves when multiple agents compete for the same provider budget
• Claude Code hooks integration — auto-register sessions via hooks so the status bar appears without manually invoking the skill
• File section locks — paired with agent-comms for per-file, per-section coordination

GitHub: LakshmiSravyaVedantham/agent-hub — Python 3.8+, MIT license.