The fuel gauge for your AI coding subscriptions - and one interface for spending them.
You pay for Claude Code, Codex, Copilot, Antigravity, Devin... aifuel answers the two questions that matter: which limit runs out first? and which subscription should take this prompt?
- Know what's left. Reads each provider's own usage endpoint and shows the quota you have left in one dashboard, ranked by soonest reset, with a live countdown to every refill.
- Spend it deliberately.
aifuel runsends a prompt through any installed provider CLI - explicit model and permission selection, resumable sessions, local approvals,text|json|jsonloutput for scripts. - Wire it into your agents. Three MCP servers expose quota status, run management, and a gateway that fronts your external MCP servers - so every host gets the same tools from one config.
One native binary. Windows, Linux, macOS - browser, terminal, or MCP host.
Linux / macOS (Windows via WSL or Git Bash):
./scripts/install.sh # installs `aifuel` into ~/.local/bin
./scripts/install.sh --uninstall # remove itWindows (PowerShell):
.\scripts\install.ps1 # installs aifuel.exe into ~\.local\bin (+ PATH)
.\scripts\install.ps1 -Uninstall # remove itOverride the target dir with BIN_DIR=/usr/local/bin (or -BinDir on Windows). The installers need Rust and Cargo; the installed command has no runtime requirement. Or build directly: cargo build --release -p aifuel.
| Command | What you get |
|---|---|
aifuel |
Web dashboard at http://127.0.0.1:8787 (opens a browser; optional auto-refresh) |
aifuel --no-browser |
Dashboard without opening a browser; --host/--port change the bind (a non-loopback --host also exposes the Connect form's key submission to clients that can reach the port) |
aifuel --text |
Compact colored terminal summary (great over SSH) |
aifuel --json |
Normalized JSON for scripts, status bars, and piping |
aifuel run --provider ID --prompt "..." |
One explicit prompt through an installed provider CLI |
aifuel run --provider auto --prompt "..." |
Route the prompt to the discovered provider with the most quota headroom, then to keyed API-key integrations |
aifuel profile list|save|remove |
Named defaults for run (provider, model, effort, access, timeout) |
aifuel model list|refresh |
Cached provider model catalog, refreshed on demand |
aifuel auth list|set-key|set-session|remove |
Stored API keys for API-key integrations and browser-session credentials for *:web integrations (also via the dashboard's Connect section); repeated set-key builds a key pool that rotates past rate limits |
aifuel auth set-admin|remove-admin |
The dashboard admin password - required before --host binds a non-loopback address, and once set it gates every dashboard page and /api/* route behind a sign-in |
aifuel approve --run ID --input ID --decision accept|decline|cancel |
Answer a pending permission request for a local run |
aifuel mcp [--http [--host H] [--port P]] |
Read-only MCP status server over stdio, or streamable HTTP |
aifuel mcp execution [--http [--host H] [--port P]] |
MCP server that manages Agent Runs over stdio, or streamable HTTP |
aifuel mcp gateway --agent HOST [--tool T ...] [--http [--host H] [--port P]] |
Selected external MCP servers, served to one agent |
aifuel mcp setup --agent HOST [--dry-run] [--remove] |
Apply or remove the gateway entry in an agent's own config |
aifuel mcp servers ... |
Manage the gateway's external server catalog |
aifuel runtime |
JSON-RPC stdio bridge for embedding agent runs in a host process |
--json is a stable structured feed - it drops cleanly into a tmux / polybar / Sketchybar / starship status line.
The same listener already fronts an OpenAI/Anthropic-compatible endpoint (/v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings, /v1/models) with per-key model allowlists - deploy it on a VPS and apps consume your configured integrations through aifuel-gw-* keys. A non-loopback --host switches to remote mode: an admin password (aifuel auth set-admin or AIFUEL_ADMIN_PASSWORD) is required, the dashboard and /api/* sit behind a sign-in, and /v1 refuses to answer until at least one gateway key exists. Put Caddy or nginx in front for TLS, or use the Docker image - see docs/deploy-vps.md.
| Provider | Source | Reads credentials from |
|---|---|---|
| Claude Code | live | ~/.claude/.credentials.json |
| Codex CLI | live | ~/.codex/auth.json |
| GitHub Copilot | live | ~/.copilot/config.json |
| Antigravity CLI | live | Code Assist OAuth token |
| Devin CLI | live | credentials.toml key |
live = pulled from the provider's own API; a provider that cannot return live usage shows as an error, never a guess. API-key integrations for OpenRouter (/key credits), Z.AI (coding-plan quota windows), DeepSeek, and SiliconFlow (account balance) also report live when their key is set. A pinned catalog covers 75 provider IDs and flags documented free tiers (has_free/free_note in --json, free: in aifuel auth list) - catalog-only entries report as unsupported.
The claude-web:web integration monitors a claude.ai browser session - the five_hour, seven_day, and per-model usage windows - through a session credential you paste yourself: aifuel auth set-session claude-web:web --stdin accepts a bare session token or a copied Cookie header line (sent as Cookie, never a Bearer token), or export CLAUDE_WEB_SESSION. It never executes prompts, so it never appears in run --provider auto; nothing reads a browser profile or an OS keyring.
Gemini CLI is no longer a built-in integration or MCP Host. When upgrading, remove or update any providers.json instances and chains that reference gemini or a Gemini instance: an unknown integration reference prevents the provider registry from loading. Update saved profiles and defaults that select Gemini too. AI Fuel leaves existing configuration files untouched; Antigravity and Gemini model IDs offered by other integrations remain available.
aifuel run --provider codex --model gpt-5-codex --prompt "Explain Rust ownership"Integration IDs (--provider is an alias for --integration): claude, codex, copilot, antigravity, devin, opencode, cursor, ollama:local, lmstudio:local, and the API-key integrations openai:api-key, openrouter:api-key, anthropic:api-key, cerebras:api-key, cohere:api-key, deepinfra:api-key, deepseek:api-key, fireworks:api-key, groq:api-key, huggingface:api-key, mistral:api-key, moonshot:api-key, nvidia:api-key, perplexity:api-key, siliconflow:api-key, together:api-key, xai:api-key, zai:api-key. Each *:api-key reads its provider's conventional env var (for example GROQ_API_KEY or ANTHROPIC_API_KEY; Hugging Face uses HF_TOKEN) or a key stored with aifuel auth set-key. anthropic:api-key speaks the Anthropic Messages API (x-api-key auth); the rest are OpenAI-compatible. The claude-web:web integration binds a pasted browser session for monitoring only - it is not a run target. Options:
--prompt TEXT/--prompt-file PATH- or omit both to pipe the prompt on stdin--model ID/--effort LEVEL- explicit model and effort--profile NAME- apply a saved profile (aifuel profile save NAME --provider ID --model ID [--effort LEVEL] [--access MODE] [--timeout SECONDS])--account ID- explicit account--access read-only|workspace-write|full- permission profile (default: read-only)--working-directory PATH(or--cwd) - project directory for the run--resume SESSION_ID- continue a known session (session_idorlocal_session_idfrom a run's output); explicit--model/--effortoverride stored values--external-tool NAME- allow one exact gateway tool (repeatable)--output text|json|jsonl- result format (default: text)--timeout 30s|10m|1h- optional deadline;0means none
--provider auto is a reserved routing alias, never a literal provider id: auto ranks the discovered providers by the same quota evidence aifuel status shows (most remaining allowance first, soonest reset breaks ties), then any *:api-key integration whose credential is present (declared env var or a stored managed credential - providers with a documented free tier ahead of paid keys), and providers with exhausted or unmeasured quota last. It runs the prompt on the best one and starts a new run on the next candidate only when the previous attempt failed before execution - a missing integration, a launch/request error, or provider-reported quota exhaustion. A timeout or a mid-run failure ends the chain. --model narrows the candidates to providers whose cached catalog advertises that model (API-key integrations carry no catalog advertisement), and --resume pins auto to the session's owning provider without fallback. The json/jsonl result carries a routing object listing the ranked candidates - each with its basis (quota, free_tier, api_key, or session) and, for quota candidates, the measured remaining_percent - and every attempt's provider, outcome, and reason.
Exit codes: 0 succeeded, 2 request or launch error, 3 provider has no verified agent integration, 4 run failed, 5 timed out.
Permission requests are never auto-approved: a run that asks for one prints the pending request - answer it with aifuel approve --run RUN_ID --input INPUT_ID --decision accept|decline|cancel. Ordinary provider questions answer interactively during aifuel run, or through answer_input for runs owned by aifuel mcp execution.
Three servers, each available over stdio (default) or streamable HTTP:
| Server | Purpose |
|---|---|
aifuel mcp |
Read-only status: get_status tool and aifuel://status resource |
aifuel mcp execution |
Owns Agent Runs: list_agents, list_models, resolve_run, start_run, resume_session, answer_input, get_run, get_result, cancel_run, read_events |
aifuel mcp gateway --agent HOST |
Serves your external MCP servers' tools, resources, and prompts to one agent |
Register the status server on any host over stdio:
{ "mcpServers": { "aifuel": { "command": "aifuel", "args": ["mcp"] } } }Permission approvals stay local-only through aifuel approve - the execution server cannot grant them.
Pass --http to any of the three servers to serve remote MCP Hosts over HTTP instead of stdio. The server listens on /mcp at 127.0.0.1:8788 by default; --host and --port override the bind address:
aifuel mcp --http # http://127.0.0.1:8788/mcp
aifuel mcp execution --http --port 8789 # a different port per server
aifuel mcp gateway --agent HOST --http --host 0.0.0.0 --port 8788A remote host then registers the URL directly:
{ "mcpServers": { "aifuel": { "url": "http://127.0.0.1:8788/mcp" } } }Each HTTP session is a full MCP connection (session id via MCP-Session-Id, GET /mcp for server events, DELETE /mcp to end it), so the gateway's progress notifications and the execution server's per-connection run ownership behave exactly as over stdio. There is no authentication layer: binding anything beyond loopback exposes the server's full MCP surface on that interface, and doing so is the operator's responsibility. aifuel mcp setup still writes stdio entries into host configs; configure HTTP entries by URL instead.
Servers are configured once in aifuel/mcp.json in your user config directory (%APPDATA%/aifuel on Windows, ~/Library/Application Support/aifuel on macOS, $XDG_CONFIG_HOME/aifuel or ~/.config/aifuel on Linux):
{
"servers": {
"local-docs": { "transport": "stdio", "command": "/absolute/path/to/mcp-server", "args": [] },
"remote-docs": { "transport": "streamable-http", "url": "https://mcp.deepwiki.com/mcp" }
},
"defaults": [],
"agents": {
"codex": { "servers": ["remote-docs"] }
}
}A host with no agents entry inherits defaults. Manage the catalog without editing JSON:
aifuel mcp servers list|validate
aifuel mcp servers add SERVER_ID --definition FILE | remove SERVER_ID
aifuel mcp servers select --defaults [SERVER_ID ...] | --agent HOST [SERVER_ID ...] | --agent HOST --inheritTrust rules: remote endpoints must use HTTPS (plain HTTP only on loopback) and speak MCP 2025-11-25. bearerTokenEnv and secretHeaders name environment variables only - values resolve once at startup (a missing or empty value fails that server), are sent only to the configured endpoint, and are never written to mcp.json or logs. Redirects are rejected, so configure the final URL. For stdio servers, env sets literals and envFrom names variables read at startup; children get a small platform allowlist plus what you configure.
Then connect an agent: aifuel mcp setup --agent HOST writes the managed entry into the host's config (backup and --dry-run supported, --remove detaches). Host IDs: codex, claude, copilot, antigravity, devin. Restart the host after changing its registration. Repeatable --tool NAME on mcp gateway restricts which tools a host sees.
Each collection (dashboard refresh, --json, --text, MCP get_status) can POST events to configured endpoints - useful for Slack, Discord, or any HTTPS receiver. Configure webhooks.json in the same aifuel user config directory as mcp.json:
{
"webhooks": [
{ "url": "https://hooks.slack.com/services/...", "events": ["threshold_crossed", "quota_reset"], "threshold_percent": 90 }
],
"defaults": { "events": ["threshold_crossed", "quota_reset"], "threshold_percent": 90 }
}threshold_crossed fires when a quota window's consumed share reaches threshold_percent (default 90); quota_reset fires when a window that was over threshold comes back under it - the window reset or quota was replenished. events and threshold_percent fall back to defaults, then to the built-ins. Payloads look like:
{ "event": "threshold_crossed", "provider": "antigravity", "provider_name": "Antigravity CLI", "window": "gemini-3.5-flash", "window_period": "unknown", "authoritative": true, "percent_used": 95.0, "percent_remaining": 5.0, "threshold_percent": 90, "reset_at": 1893456000.0, "checked_at": 1790879303.8 }reset_at and checked_at are Unix seconds. Endpoints must use HTTPS, or HTTP only on loopback - the same trust rule as the MCP gateway. Each crossing notifies once per window and threshold; the state lives in webhook-state.json so restarts don't re-announce. Delivery is at-most-once with short timeouts, and failures are logged to stderr without affecting collection.
- Credentials are read locally only - the same files your CLIs already use. Tokens are never printed and are sent only to their own provider's usage endpoint.
- Discovery is filesystem-only: it never calls an API, refreshes a token, or writes credentials. One provider's failure doesn't block the rest - JSON reports it in
discovery_errors. - Results cache in-process for 300s unless a refresh is requested; the dashboard's 5-minute auto-refresh is opt-in and countdowns tick every second.
- Providers rank by their authoritative weekly/monthly window, else soonest reset; depleted providers sort last.
Does this send my tokens anywhere? No. It reads the same local credential files your CLIs use, calls each provider's own usage endpoint, and shows the result. No server, no telemetry, no third party.
Do I need API keys? Not for monitoring - it reuses the OAuth/logins your AI coding CLIs already set up. aifuel run through an API-key integration (any *:api-key id listed above) does need one via aifuel auth set-key, the dashboard's Connect section, or the provider's env var. A general GitHub CLI login does not count as a GitHub Copilot login.
It only shows some providers. Those are the ones with local credentials. Log in to that provider's AI coding CLI, then refresh.
Why not just check each dashboard? Five tabs don't tell you which limit you'll hit first - aifuel does, at a glance.
