agent-fuel 0.4.2 → 0.5.0

package/README.md

@@ -45,10 +45,11 @@ AI coding assistants are now integral to developer workflows. Tools like **Claud
 `agent-fuel` is a tiny modern CLI built with TypeScript that:
 
 1. **Dispatches Adapters concurrently** — all adapters run in parallel and each row is printed the moment its adapter resolves; you never wait for the slowest tool.
-2. **Normalises Quota Models** — standardises diverse limits into a uniform `0–100%` score.
-3. **Scrapes TUI output directly** — Codex and AGY quotas are read by spawning the real CLIs via `expect` and parsing terminal output, so the numbers match what the tools themselves show.
-4. **Caches AGY results** — AGY quota is cached for 5 minutes so repeated runs are instant (~1s).
-5. **Renders a clean dashboard** — colour-coded bars with reset times directly in your terminal.
+2. **Streams Consolidated Quota Live** — renders a weighted **Total** bar on top which calculates and updates in real-time as each provider finishes loading, showing the live calculated portion rather than waiting for all adapters to finish.
+3. **Normalises Quota Models** — standardises diverse limits into a uniform `0–100%` score.
+4. **Scrapes TUI output directly** — Codex and AGY quotas are read by spawning the real CLIs via `expect` and parsing terminal output, so the numbers match what the tools themselves show.
+5. **Caches AGY results** — AGY quota is cached for 5 minutes so repeated runs are instant (~1s).
+6. **Renders a clean dashboard** — colour-coded bars with reset times directly in your terminal.
 
 ### Project Architecture
 
@@ -57,6 +58,7 @@ agent-fuel/
   ├── src/
   │   ├── index.ts            # CLI entry point — runs all adapters concurrently
   │   ├── render.ts           # Colour-coded bar dashboard renderer
+  │   ├── config.ts           # Config file manager & config command handler
   │   └── adapters/
   │       ├── index.ts        # Shared UsageSnapshot type & QuotaAdapter interface
   │       ├── claude.ts       # Claude Code (via ccusage blocks)
@@ -86,28 +88,67 @@ type UsageSnapshot = {
 ```
 ⚡️ Agent Fuel - CLI Quota Monitor
 
-Claude Code   [██████████████████████░░░░░░░░]  72% remaining (resets 23:10 (Europe/Copenhagen))
-Codex         [█████████████████████░░░░░░░░░]  69% remaining (resets 23:37)
+Total         [████████████████████████░░░░░░]  81% remaining  (tune weights: agent-fuel config)
+
+Claude Code   [██████████████████████░░░░░░░░]  74% remaining (resets 13:19 (Europe/Copenhagen))
+Codex         [██████████████████████████████]  99% remaining (resets 13:56)
 AGY Gemini    [██████████████████████████████] 100% remaining ✓ quota available [Gemini 3.5 Flash (Medium)]
-AGY Other     [████████████░░░░░░░░░░░░░░░░░░]  40% remaining (resets in 122h 53m) [Claude Sonnet 4.6 (Thinking)]
+AGY Other     [████████████░░░░░░░░░░░░░░░░░░]  40% remaining (resets in 109h 12m) [Claude Sonnet 4.6 (Thinking)]
 
-agent-fuel v0.x.y
+agent-fuel v0.5.0
 ```
 
-Rows appear as each adapter resolves — Claude Code (instant) prints first, Codex and AGY follow as their TUI scrapes complete.
+- **Total** bar prints on top (in TTY interactive mode) showing the weighted consolidated remaining quota. As adapters load, the bar fills up in real-time. When fully loaded, a helpful CLI reminder is displayed alongside the Total percentage.
+- Rows appear as each adapter resolves — Claude Code (instant) prints first, Codex and AGY follow as their TUI scrapes complete.
+- **AGY Gemini** shows the worst-case remaining across all `Gemini *` model tiers.  
+- **AGY Other** shows the worst-case across Claude and other non-Gemini models.  
+- **Codex** row tagged `[~est]` when quota has not been reached and the percentage is estimated from local session cost data (see fallback note below).
+
+---
+
+## ⚙️ Configuration & Custom Weights
+
+Different developers operate under different quota sizes. By default, `agent-fuel` weights each provider bucket as standard proxies for monthly dollar subscription amounts:
+- Claude Code (`claude-code`): `20`
+- Codex CLI (`codex`): `20`
+- AGY Gemini (`agy-gemini`): `10`
+- AGY Other (`agy-other`): `10`
+
+If a provider is completely unused or fails to return a quota percentage, its weight is **dynamically excluded** from the calculation, ensuring that missing/unused services don't break the consolidated bar.
 
-**AGY Gemini** shows the worst-case remaining across all `Gemini *` model tiers.  
-**AGY Other** shows the worst-case across Claude and other non-Gemini models.  
-**Codex** row tagged `[~est]` when quota has not been reached and the percentage is estimated from local session cost data (see fallback note below).
+### Managing Settings via the CLI
+
+You can view or update your weights and settings directly using the CLI:
+
+* **View Active Configuration**:
+  ```bash
+  agent-fuel config
+  ```
+* **Change Provider Weight**:
+  ```bash
+  agent-fuel config set claude-code 50
+  ```
+* **Disable/Enable Total Bar**:
+  ```bash
+  agent-fuel config set show-total false
+  ```
+
+Settings are persistently saved to `~/.config/agent-fuel/config.json`.
 
 ---
 
 ## ⚙️ Environment Overrides
 
+Environment variables take highest precedence and override any values saved in the config JSON file:
+
 | Variable | Default | Description |
 |---|---|---|
 | `AGENT_FUEL_CLAUDE_BUDGET` | `20.0` | Claude Code rolling budget in USD |
 | `AGENT_FUEL_CODEX_BUDGET` | `20.0` | **Fallback estimate only** — Codex rolling budget in USD |
+| `AGENT_FUEL_WEIGHT_CLAUDE` | `20` | Weight size ratio of the Claude Code quota pool |
+| `AGENT_FUEL_WEIGHT_CODEX` | `20` | Weight size ratio of the Codex quota pool |
+| `AGENT_FUEL_WEIGHT_AGY_GEMINI` | `10` | Weight size ratio of the AGY Gemini quota pool |
+| `AGENT_FUEL_WEIGHT_AGY_OTHER` | `10` | Weight size ratio of the AGY Other quota pool |
+| `AGENT_FUEL_SHOW_TOTAL` | `true` | Show or hide the consolidated Total quota bar (`true`/`false`) |
 
 > **Note on `AGENT_FUEL_CODEX_BUDGET`:** Codex quota is read directly from the Codex TUI via `expect` scraping. This variable is only used as a rough fallback estimate (shown as `[~est]`) when the TUI reports no quota warning and a percentage cannot be determined. It is a guess based on local session cost data — not an official Codex quota signal. The TUI scrape is always preferred.
-

package/dist/adapters/index.d.ts

@@ -1,9 +1,10 @@
 export interface UsageSnapshot {
-    tool: 'codex' | 'claude-code' | 'agy-gemini' | 'agy-other';
+    tool: 'codex' | 'claude-code' | 'agy-gemini' | 'agy-other' | 'total';
     remainingPercent: number | null;
     usedPercent?: number | null;
     resetAt?: string | null;
     source: 'official-cli' | 'ccusage' | 'local-state' | 'provider-api' | 'cache' | 'unknown';
+    isLoading?: boolean;
     raw?: unknown;
 }
 export interface QuotaAdapter {

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+export interface Config {
+    weights: {
+        'claude-code': number;
+        'codex': number;
+        'agy-gemini': number;
+        'agy-other': number;
+    };
+    showTotal: boolean;
+}
+export declare const CONFIG_DIR: string;
+export declare const CONFIG_FILE: string;
+export declare const DEFAULT_CONFIG: Config;
+export declare function loadConfig(): Config;
+export declare function saveConfig(config: Config): void;
+export declare function handleConfigCommand(args: string[]): boolean;

package/dist/config.js

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export const CONFIG_DIR = path.join(os.homedir(), '.config', 'agent-fuel');
+export const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+export const DEFAULT_CONFIG = {
+    weights: {
+        'claude-code': 20,
+        'codex': 20,
+        'agy-gemini': 10,
+        'agy-other': 10,
+    },
+    showTotal: true,
+};
+function ensureDir(dir) {
+    try {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    }
+    catch {
+        // Ignore, let write fail if it must
+    }
+}
+export function loadConfig() {
+    const config = { ...DEFAULT_CONFIG, weights: { ...DEFAULT_CONFIG.weights } };
+    // 1. Read from config file
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            const content = fs.readFileSync(CONFIG_FILE, 'utf8');
+            const parsed = JSON.parse(content);
+            if (parsed && typeof parsed === 'object') {
+                if (parsed.weights && typeof parsed.weights === 'object') {
+                    for (const key of ['claude-code', 'codex', 'agy-gemini', 'agy-other']) {
+                        const w = parsed.weights[key];
+                        if (typeof w === 'number' && Number.isFinite(w) && w >= 0) {
+                            config.weights[key] = w;
+                        }
+                    }
+                }
+                if (typeof parsed.showTotal === 'boolean') {
+                    config.showTotal = parsed.showTotal;
+                }
+            }
+        }
+    }
+    catch {
+        // Fail silently, use defaults
+    }
+    // 2. Read from Environment Variables
+    const envClaude = process.env.AGENT_FUEL_WEIGHT_CLAUDE_CODE ?? process.env.AGENT_FUEL_WEIGHT_CLAUDE;
+    if (envClaude) {
+        const val = Number(envClaude);
+        if (Number.isFinite(val) && val >= 0)
+            config.weights['claude-code'] = val;
+    }
+    const envCodex = process.env.AGENT_FUEL_WEIGHT_CODEX;
+    if (envCodex) {
+        const val = Number(envCodex);
+        if (Number.isFinite(val) && val >= 0)
+            config.weights['codex'] = val;
+    }
+    const envGemini = process.env.AGENT_FUEL_WEIGHT_AGY_GEMINI ?? process.env.AGENT_FUEL_WEIGHT_GEMINI;
+    if (envGemini) {
+        const val = Number(envGemini);
+        if (Number.isFinite(val) && val >= 0)
+            config.weights['agy-gemini'] = val;
+    }
+    const envOther = process.env.AGENT_FUEL_WEIGHT_AGY_OTHER ?? process.env.AGENT_FUEL_WEIGHT_OTHER;
+    if (envOther) {
+        const val = Number(envOther);
+        if (Number.isFinite(val) && val >= 0)
+            config.weights['agy-other'] = val;
+    }
+    const envShowTotal = process.env.AGENT_FUEL_SHOW_TOTAL;
+    if (envShowTotal) {
+        if (envShowTotal.toLowerCase() === 'true')
+            config.showTotal = true;
+        if (envShowTotal.toLowerCase() === 'false')
+            config.showTotal = false;
+    }
+    return config;
+}
+export function saveConfig(config) {
+    ensureDir(CONFIG_DIR);
+    try {
+        fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not write config file ${CONFIG_FILE}: ${msg}`);
+    }
+}
+export function handleConfigCommand(args) {
+    if (args.length === 0)
+        return false;
+    const firstArg = args[0].toLowerCase();
+    if (firstArg !== 'config')
+        return false;
+    const BOLD = '\x1b[1m';
+    const CYAN = '\x1b[36m';
+    const RED = '\x1b[31m';
+    const GREEN = '\x1b[32m';
+    const R = '\x1b[0m';
+    const GRAY = '\x1b[90m';
+    const config = loadConfig();
+    const subCommand = args[1]?.toLowerCase();
+    if (!subCommand || subCommand === 'list') {
+        console.log(`\n${BOLD}${CYAN}⚡️ Agent Fuel Configuration${R}`);
+        console.log(`${GRAY}Config file: ${CONFIG_FILE}${R}\n`);
+        console.log(`${BOLD}Weights:${R}`);
+        console.log(`  claude-code : ${config.weights['claude-code']}`);
+        console.log(`  codex       : ${config.weights['codex']}`);
+        console.log(`  agy-gemini  : ${config.weights['agy-gemini']}`);
+        console.log(`  agy-other   : ${config.weights['agy-other']}`);
+        console.log();
+        console.log(`${BOLD}Settings:${R}`);
+        console.log(`  show-total  : ${config.showTotal}`);
+        console.log();
+        console.log(`${BOLD}Examples:${R}`);
+        console.log(`  agent-fuel config set claude-code 50`);
+        console.log(`  agent-fuel config set show-total false`);
+        console.log();
+        return true;
+    }
+    if (subCommand === 'set') {
+        const key = args[2]?.toLowerCase();
+        const rawVal = args[3];
+        if (!key || !rawVal) {
+            console.error(`\n${BOLD}${RED}Error:${R} Usage: agent-fuel config set <key> <value>`);
+            console.error(`Keys: claude, claude-code, codex, gemini, agy-gemini, other, agy-other, show-total\n`);
+            process.exit(1);
+        }
+        if (key === 'show-total') {
+            const lowerVal = rawVal.toLowerCase();
+            if (lowerVal !== 'true' && lowerVal !== 'false') {
+                console.error(`\n${BOLD}${RED}Error:${R} show-total must be true or false\n`);
+                process.exit(1);
+            }
+            config.showTotal = lowerVal === 'true';
+            saveConfig(config);
+            console.log(`\n${BOLD}${GREEN}✓${R} Set show-total to ${config.showTotal}\n`);
+            return true;
+        }
+        // Handle weights keys
+        let targetKey = null;
+        if (key === 'claude' || key === 'claude-code') {
+            targetKey = 'claude-code';
+        }
+        else if (key === 'codex') {
+            targetKey = 'codex';
+        }
+        else if (key === 'gemini' || key === 'agy-gemini') {
+            targetKey = 'agy-gemini';
+        }
+        else if (key === 'other' || key === 'agy-other') {
+            targetKey = 'agy-other';
+        }
+        if (!targetKey) {
+            console.error(`\n${BOLD}${RED}Error:${R} Unknown key "${key}".`);
+            console.error(`Valid keys: claude, claude-code, codex, gemini, agy-gemini, other, agy-other, show-total\n`);
+            process.exit(1);
+        }
+        const val = Number(rawVal);
+        if (!Number.isFinite(val) || val < 0) {
+            console.error(`\n${BOLD}${RED}Error:${R} Weight must be a positive number or 0.\n`);
+            process.exit(1);
+        }
+        config.weights[targetKey] = val;
+        saveConfig(config);
+        console.log(`\n${BOLD}${GREEN}✓${R} Set weight.${targetKey} to ${val}\n`);
+        return true;
+    }
+    console.error(`\n${BOLD}${RED}Error:${R} Unknown config sub-command "${subCommand}".`);
+    console.error(`Usage: agent-fuel config [list|set]\n`);
+    process.exit(1);
+}

package/dist/index.js

@@ -3,23 +3,78 @@ import { debugEnabled, debugLogFile } from './debug.js';
 import { ClaudeQuotaAdapter } from './adapters/claude.js';
 import { CodexQuotaAdapter } from './adapters/codex.js';
 import { AgyQuotaAdapter } from './adapters/agy.js';
-import { printHeader, printFooter, formatRow, getDisplayName } from './render.js';
+import { printHeader, printFooter, formatRow, getDisplayName, SHADE_CHAR } from './render.js';
+import { loadConfig, handleConfigCommand } from './config.js';
 // Fixed display order — never changes regardless of which adapter resolves first
 const SLOT_ORDER = ['claude-code', 'codex', 'agy-gemini', 'agy-other'];
 const BOLD = '\x1b[1m';
 const DIM = '\x1b[2m';
 const R = '\x1b[0m';
 const GRAY = '\x1b[90m';
+const CYAN = '\x1b[36m';
 const isTTY = Boolean(process.stdout.isTTY);
 const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 let spinnerTick = 0;
+const config = loadConfig();
 function spinnerLine(tool) {
     const frame = SPINNER[spinnerTick % SPINNER.length];
     return `${BOLD}${getDisplayName(tool).padEnd(13)}${R} ${DIM}${GRAY}${frame} loading...${R}\x1b[K`;
 }
+function calculateTotalLine(snapshots) {
+    let totalWeight = 0;
+    let totalRemainingWeight = 0;
+    let hasActive = false;
+    let isAnyLoading = false;
+    for (const tool of SLOT_ORDER) {
+        const snap = snapshots.get(tool);
+        if (snap === undefined || snap === null) {
+            isAnyLoading = true;
+            continue;
+        }
+        if (snap.remainingPercent !== null) {
+            const w = config.weights[tool] ?? 0;
+            totalWeight += w;
+            totalRemainingWeight += (snap.remainingPercent / 100) * w;
+            hasActive = true;
+        }
+    }
+    if (!hasActive) {
+        if (isAnyLoading) {
+            const frame = SPINNER[spinnerTick % SPINNER.length];
+            return `${BOLD}${CYAN}Total${R}         [${GRAY}${SHADE_CHAR.repeat(30)}${R}] ${DIM}${GRAY}${frame} loading...${R}\x1b[K`;
+        }
+        const totalSnap = {
+            tool: 'total',
+            remainingPercent: null,
+            usedPercent: null,
+            source: 'unknown',
+            isLoading: true
+        };
+        return formatRow(totalSnap);
+    }
+    const pct = totalWeight > 0
+        ? Math.max(0, Math.min(100, Math.round((totalRemainingWeight / totalWeight) * 100)))
+        : null;
+    const totalSnap = {
+        tool: 'total',
+        remainingPercent: pct,
+        usedPercent: pct !== null ? 100 - pct : null,
+        source: 'local-state',
+        isLoading: isAnyLoading
+    };
+    let formatted = formatRow(totalSnap);
+    if (isAnyLoading) {
+        const frame = SPINNER[spinnerTick % SPINNER.length];
+        formatted += ` ${DIM}${GRAY}${frame} loading...${R}`;
+    }
+    else {
+        formatted += `  ${DIM}${GRAY}(tune weights: agent-fuel config)${R}`;
+    }
+    return formatted;
+}
 // In TTY mode: restore cursor to saved position and repaint all slots.
 // In pipe mode: emit each newly-resolved line exactly once (tracked via emitted set).
-function redraw(slots, emitted) {
+function redraw(slots, emitted, snapshots) {
     if (!isTTY) {
         for (const tool of SLOT_ORDER) {
             const line = slots.get(tool);
@@ -28,9 +83,20 @@ function redraw(slots, emitted) {
                 emitted.add(tool);
             }
         }
+        if (config.showTotal && emitted.size === SLOT_ORDER.length && !emitted.has('total')) {
+            const totalLine = calculateTotalLine(snapshots);
+            process.stdout.write('\n' + totalLine + '\n');
+            emitted.add('total');
+        }
         return;
     }
     process.stdout.write('\x1b8'); // DEC restore-cursor — teleports back to saved position
+    if (config.showTotal) {
+        process.stdout.write('\x1b[2K\r');
+        const totalLine = calculateTotalLine(snapshots);
+        process.stdout.write(totalLine + '\n');
+        process.stdout.write('\x1b[2K\r\n'); // spacer line
+    }
     for (const tool of SLOT_ORDER) {
         process.stdout.write('\x1b[2K\r');
         const line = slots.get(tool);
@@ -38,6 +104,10 @@ function redraw(slots, emitted) {
     }
 }
 async function main() {
+    const args = process.argv.slice(2);
+    if (handleConfigCommand(args)) {
+        return;
+    }
     const claudeAdapter = new ClaudeQuotaAdapter();
     const codexAdapter = new CodexQuotaAdapter();
     const agyAdapter = new AgyQuotaAdapter();
@@ -46,24 +116,30 @@ async function main() {
     printHeader();
     // Save cursor before the placeholder rows so redraw() can teleport back and overwrite them
     const slots = new Map(SLOT_ORDER.map(t => [t, null]));
+    const snapshots = new Map(SLOT_ORDER.map(t => [t, null]));
     const emitted = new Set(); // pipe-mode: tracks which lines have been printed
-    if (isTTY)
+    if (isTTY) {
         process.stdout.write('\x1b7'); // DEC save-cursor
+        if (config.showTotal) {
+            process.stdout.write(calculateTotalLine(snapshots) + '\n\n');
+        }
+    }
     for (const tool of SLOT_ORDER) {
         process.stdout.write(spinnerLine(tool) + '\n');
     }
     // Animate spinner at 80ms while any slot is still loading
     const spinnerTimer = isTTY
-        ? setInterval(() => { spinnerTick++; redraw(slots, emitted); }, 80)
+        ? setInterval(() => { spinnerTick++; redraw(slots, emitted, snapshots); }, 80)
         : null;
     // Each adapter fills its slot(s) and triggers a redraw; order is always fixed
     function fill(snaps) {
         for (const snap of snaps) {
             if (SLOT_ORDER.includes(snap.tool)) {
+                snapshots.set(snap.tool, snap);
                 slots.set(snap.tool, formatRow(snap));
             }
         }
-        redraw(slots, emitted);
+        redraw(slots, emitted, snapshots);
     }
     await Promise.allSettled([
         claudeAdapter.fetchSnapshots().then(fill),
@@ -72,7 +148,7 @@ async function main() {
     ]);
     if (spinnerTimer)
         clearInterval(spinnerTimer);
-    redraw(slots, emitted); // final clean repaint with all data
+    redraw(slots, emitted, snapshots); // final clean repaint with all data
     printFooter();
 }
 main().catch((error) => {

package/dist/render.d.ts

@@ -1,4 +1,5 @@
 import { UsageSnapshot } from './adapters/index.js';
+export declare const SHADE_CHAR = "\u2591";
 export declare function getDisplayName(tool: string): string;
 export declare function formatRow(snap: UsageSnapshot): string;
 export declare function printHeader(): void;

package/dist/render.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ── Constants ──────────────────────────────────────────────────────────────
 const BLOCK_CHAR = '█';
-const SHADE_CHAR = '░';
+export const SHADE_CHAR = '░';
 const BAR_WIDTH = 30;
 // ── ANSI colour helpers ────────────────────────────────────────────────────
 const R = '\x1b[0m';
@@ -21,10 +21,13 @@ export function getDisplayName(tool) {
         case 'claude-code': return 'Claude Code';
         case 'agy-gemini': return 'AGY Gemini';
         case 'agy-other': return 'AGY Other';
+        case 'total': return 'Total';
         default: return tool;
     }
 }
-function pickColour(remaining) {
+function pickColour(remaining, isLoading) {
+    if (isLoading)
+        return CYAN;
     if (remaining < 20)
         return RED;
     if (remaining < 50)
@@ -69,7 +72,7 @@ export function formatRow(snap) {
         percentStr = `${GRAY}unknown${R}`;
     }
     else {
-        const colour = pickColour(remaining);
+        const colour = pickColour(remaining, snap.isLoading);
         const filled = Math.max(0, Math.min(BAR_WIDTH, Math.round((remaining * BAR_WIDTH) / 100)));
         const empty = BAR_WIDTH - filled;
         barStr = `${colour}${BLOCK_CHAR.repeat(filled)}${R}${GRAY}${SHADE_CHAR.repeat(empty)}${R}`;
@@ -89,7 +92,9 @@ export function formatRow(snap) {
         parts.push(`${DIM}${GRAY}[~est]${R}`);
     }
     const detailStr = parts.length > 0 ? ` ${parts.join(' ')}` : '';
-    return `${BOLD}${displayName.padEnd(13)}${R} [${barStr}] ${percentStr}${detailStr}`;
+    const isTotal = snap.tool === 'total';
+    const labelPrefix = isTotal ? `${BOLD}${CYAN}` : BOLD;
+    return `${labelPrefix}${displayName.padEnd(13)}${R} [${barStr}] ${percentStr}${detailStr}`;
 }
 // ── Public render functions ────────────────────────────────────────────────
 export function printHeader() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-fuel",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Sleek term-based dashboard for AI coding CLI quotas",
   "type": "module",
   "main": "dist/index.js",