agent-fuel 0.4.1 → 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,43 +88,67 @@ type UsageSnapshot = {
 ```
 ⚡️ Agent Fuel - CLI Quota Monitor
 
-Claude Code   [███████████████████░░░░░░░░░░░]  64% remaining (resets 01:00 PM)
-Codex         [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]   0% remaining (resets in 4h 33m)
-AGY Gemini    [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]   0% remaining (resets in 3h 16m) [Gemini 3.5 Flash (Medium)]
-AGY Other     [██████████████████░░░░░░░░░░░░]  60% remaining (resets in 4h 47m) [Claude Sonnet 4.6 (Thinking)]
+Total         [████████████████████████░░░░░░]  81% remaining  (tune weights: agent-fuel config)
 
-agent-fuel v0.3.0
+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 109h 12m) [Claude Sonnet 4.6 (Thinking)]
+
+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.
+
+### Managing Settings via the CLI
+
+You can view or update your weights and settings directly using the CLI:
 
-**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).
+* **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.
-
----
-
-## 📦 Changelog
-
-### v0.3.0
-- **Codex TUI scrape**: replaced inaccurate `ccusage` cost estimate with an `expect` wrapper that reads the real Codex quota warning (`"Individual quota reached. Resets in Xh Ym"`) — same pattern as AGY. `ccusage` kept as a labelled `[~est]` fallback when quota has not yet been exhausted.
-- **Streaming render with fixed order**: placeholder rows print immediately; each bar overwrites in-place as its adapter resolves. Row order is always `Claude Code → Codex → AGY Gemini → AGY Other`.
-- **AGY split view**: Gemini and non-Gemini (Claude, etc.) quota buckets shown as separate rows
-- **5-minute disk cache** for AGY quota — repeated runs complete in ~1s instead of ~20s
-- Output size cap, typed `any` removal, env validation hardening
-
-### v0.2.x
-- AGY quota now scraped live from `agy /usage` panel via `expect` wrapper (zero token cost)
-- Claude Code budget corrected to $20 rolling limit
-- Replaced token-consuming `claude -p` calls with offline `ccusage` scraping

package/dist/adapters/codex.js

@@ -1,7 +1,10 @@
 import { exec, execFileSync } from 'node:child_process';
 import { promisify } from 'node:util';
-import { readFileSync, unlinkSync } from 'node:fs';
-import { TuiScraper, sleep } from '../tmux.js';
+import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { TuiScraper, sleep, registerTempFile, unregisterTempFile } from '../tmux.js';
 import { debug } from '../debug.js';
 const execAsync = promisify(exec);
 // Used ONLY as a rough fallback estimate when the TUI scrape cannot determine
@@ -18,6 +21,9 @@ const CODEX_READY = /Tip:/i;
 const CODEX_DIALOG = /Update available|Introducing GPT|Try new model|Use existing model/i;
 const CODEX_EITHER = new RegExp(`(?:${CODEX_READY.source})|(?:${CODEX_DIALOG.source})`, 'i');
 const CODEX_STARTUP_MS = 25_000;
+const CODEX_DIALOG_SETTLE_MS = 1_000; // wait for UI to re-render after dismissing a dialog
+const CODEX_STATUS_REFRESH_MS = 2_000; // first /status just triggers a quota refresh
+const CODEX_STATUS_READY_MS = 4_000; // second /status carries the live quota data
 /**
  * Launches `codex` in a tmux session, pipes all terminal bytes to a temp
  * file, sends /status twice, then reads the file and returns the raw bytes.
@@ -30,11 +36,22 @@ const CODEX_STARTUP_MS = 25_000;
  */
 async function runCodexScrape() {
     const tui = new TuiScraper('codex');
-    const pipePath = `/tmp/af-codex-${Date.now()}.log`;
+    const tmpDir = os.tmpdir();
+    const randomSuffix = crypto.randomBytes(6).toString('hex');
+    const pipePath = path.join(tmpDir, `af-codex-${Date.now()}-${randomSuffix}.log`);
+    registerTempFile(pipePath);
+    // Create the file with restricted permissions before tmux starts writing to it
+    writeFileSync(pipePath, '', { mode: 0o600 });
     try {
         tui.start();
-        // Stream all pane output to a file from the start
-        execFileSync('tmux', ['pipe-pane', '-t', tui.sessionId, `cat >> '${pipePath}'`]);
+        // Stream all pane output to a file from the start.
+        // Single-quote escaping: safe against all shell metacharacters ($, `, \, space, etc.)
+        // Note: pipe-pane executes this command via tmux's `default-shell` (defaults to /bin/sh).
+        // If the user has set default-shell to a non-POSIX shell (e.g. fish), the `'\\''` idiom
+        // will fail — but pipePath is constructed from os.tmpdir() + hex, so single quotes
+        // cannot appear in practice, making the replace a no-op and the quoting sh-compatible.
+        const shellSafePath = "'" + pipePath.replace(/'/g, "'\\''") + "'";
+        execFileSync('tmux', ['pipe-pane', '-t', tui.sessionId, `cat >> ${shellSafePath}`]);
         debug('codex:scrape', `pipe-pane logging to ${pipePath}`);
         // Wait for TUI ready, dismissing any blocking dialogs along the way.
         const dialogDeadline = Date.now() + CODEX_STARTUP_MS;
@@ -42,7 +59,7 @@ async function runCodexScrape() {
         while (!CODEX_READY.test(screen)) {
             debug('codex:scrape', 'blocking dialog detected — sending "2" to dismiss');
             tui.send('2');
-            await sleep(1_000); // wait for dialog to actually clear before re-checking
+            await sleep(CODEX_DIALOG_SETTLE_MS);
             const remaining = dialogDeadline - Date.now(); // compute AFTER sleep
             if (remaining < 500) {
                 throw new Error('Codex TUI never reached ready state after dismissing dialogs');
@@ -51,20 +68,24 @@ async function runCodexScrape() {
         }
         // First /status: panel says "Limits: refresh requested; run /status again shortly"
         tui.send('/status');
-        await sleep(2_000);
+        await sleep(CODEX_STATUS_REFRESH_MS);
         // Second /status: has actual 5h/weekly quota data
         tui.send('/status');
-        await sleep(4_000);
+        await sleep(CODEX_STATUS_READY_MS);
         const raw = readFileSync(pipePath, 'utf-8');
         debug('codex:scrape', `pipe log size: ${raw.length} bytes`);
         return raw;
     }
     finally {
-        tui.kill();
+        try {
+            tui.kill();
+        }
+        catch { /* already dead */ }
+        unregisterTempFile(pipePath); // always remove from registry, regardless of unlink success
         try {
             unlinkSync(pipePath);
         }
-        catch { /* ok */ }
+        catch { /* ok if already gone */ }
     }
 }
 function stripAnsi(str) {
@@ -135,7 +156,8 @@ async function fetchCcusageEstimate(budgetLimit) {
         try {
             ({ stdout } = await execAsync('npx --no-install ccusage codex session --json'));
         }
-        catch {
+        catch (err) {
+            debug('codex:ccusage', 'ccusage exec failed', String(err));
             return unknown();
         }
         debug('codex:ccusage', 'raw stdout', stdout);
@@ -194,7 +216,8 @@ async function fetchCcusageEstimate(budgetLimit) {
             raw: { totalCost, todaySessionsCount: todaySessions.length, isEstimate: true },
         };
     }
-    catch {
+    catch (err) {
+        debug('codex:ccusage', 'unexpected error in ccusage fallback', String(err));
         return unknown();
     }
 }

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/debug.js

@@ -1,10 +1,41 @@
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 const enabled = process.argv.includes('--debug');
+const MAX_DEBUG_LOGS = 10;
+function pruneOldLogs(dir) {
+    try {
+        // Count first — stat only if pruning is actually needed.
+        // Use MAX_DEBUG_LOGS - 1 to reserve a slot for the new log file that is
+        // created after this call, so the total on disk never exceeds MAX_DEBUG_LOGS.
+        const names = readdirSync(dir)
+            .filter(f => f.startsWith('debug-') && f.endsWith('.log'));
+        if (names.length < MAX_DEBUG_LOGS)
+            return;
+        const files = names.map(f => {
+            const p = join(dir, f);
+            return { path: p, time: statSync(p).mtimeMs };
+        });
+        // Sort by modification time, oldest first
+        files.sort((a, b) => a.time - b.time);
+        const toDeleteCount = files.length - (MAX_DEBUG_LOGS - 1);
+        for (let i = 0; i < toDeleteCount; i++) {
+            try {
+                unlinkSync(files[i].path);
+            }
+            catch {
+                // ignore individual deletion failures
+            }
+        }
+    }
+    catch {
+        // ignore directory read/stat errors
+    }
+}
 const logFile = enabled
     ? (() => {
         const dir = join(process.cwd(), '.logs');
         mkdirSync(dir, { recursive: true });
+        pruneOldLogs(dir);
         const ts = new Date().toISOString().replace(/[:.]/g, '-');
         return join(dir, `debug-${ts}.log`);
     })()

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/dist/tmux.d.ts

@@ -1,3 +1,5 @@
+export declare function registerTempFile(filePath: string): void;
+export declare function unregisterTempFile(filePath: string): void;
 export declare class TuiScraper {
     private readonly command;
     private readonly width;

package/dist/tmux.js

@@ -1,5 +1,62 @@
 import { execFileSync } from 'node:child_process';
+import { unlinkSync } from 'node:fs';
+import crypto from 'node:crypto';
 import { debug } from './debug.js';
+// Global registries for active resources
+const activeScrapers = new Set();
+const activeTempFiles = new Set();
+export function registerTempFile(filePath) {
+    activeTempFiles.add(filePath);
+}
+export function unregisterTempFile(filePath) {
+    activeTempFiles.delete(filePath);
+}
+function cleanupAll() {
+    if (activeScrapers.size === 0 && activeTempFiles.size === 0)
+        return;
+    process.stderr.write(`\n\x1b[33m[agent-fuel] Clean up triggered. Cleaning up resources...\x1b[0m\n`);
+    for (const scraper of activeScrapers) {
+        try {
+            scraper.kill();
+        }
+        catch {
+            // ignore
+        }
+    }
+    activeScrapers.clear();
+    for (const file of activeTempFiles) {
+        try {
+            unlinkSync(file);
+        }
+        catch {
+            // ignore
+        }
+    }
+    activeTempFiles.clear();
+}
+// Register signal handlers eagerly at module load time so that any temp files
+// registered before TuiScraper.start() (e.g. between registerTempFile and start())
+// are still cleaned up on SIGINT/SIGTERM/SIGHUP.
+let signalsRegistered = false;
+function registerSignalHandlers() {
+    if (signalsRegistered)
+        return;
+    signalsRegistered = true;
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    for (const sig of signals) {
+        process.on(sig, () => {
+            cleanupAll();
+            const code = sig === 'SIGINT' ? 130 : sig === 'SIGTERM' ? 143 : 129;
+            process.exit(code);
+        });
+    }
+    process.on('uncaughtException', (err) => {
+        process.stderr.write(`\x1b[31mUncaught Exception:\x1b[0m ${err.stack || err}\n`);
+        cleanupAll();
+        process.exit(1);
+    });
+}
+registerSignalHandlers(); // called at import time — guarded by signalsRegistered flag
 export class TuiScraper {
     command;
     width;
@@ -9,11 +66,11 @@ export class TuiScraper {
         this.command = command;
         this.width = width;
         this.height = height;
-        this.sessionId = `af-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+        this.sessionId = `af-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
     }
     start() {
         try {
-            execFileSync('which', ['tmux'], { stdio: 'ignore' });
+            execFileSync('which', ['tmux'], { stdio: 'ignore', timeout: 5000 });
         }
         catch {
             throw new Error('tmux not found — install with: brew install tmux');
@@ -23,7 +80,8 @@ export class TuiScraper {
             'new-session', '-d', '-s', this.sessionId,
             '-x', String(this.width), '-y', String(this.height),
             this.command,
-        ]);
+        ], { stdio: 'ignore', timeout: 5000 });
+        activeScrapers.add(this);
     }
     // historyLines > 0 → include that many lines of scrollback above the visible screen.
     // This catches transient overlays that rendered and then re-rendered away.
@@ -31,18 +89,18 @@ export class TuiScraper {
         const args = historyLines > 0
             ? ['capture-pane', '-t', this.sessionId, '-S', `-${historyLines}`, '-p']
             : ['capture-pane', '-t', this.sessionId, '-p'];
-        const text = execFileSync('tmux', args).toString();
+        const text = execFileSync('tmux', args, { timeout: 5000 }).toString();
         debug('tmux:capture', `[${this.sessionId}] captured ${text.length} chars (history=${historyLines})`);
         return text;
     }
     send(text) {
         debug('tmux:send', `[${this.sessionId}] sending: ${JSON.stringify(text)}`);
-        execFileSync('tmux', ['send-keys', '-t', this.sessionId, text, 'Enter']);
+        execFileSync('tmux', ['send-keys', '-t', this.sessionId, text, 'Enter'], { stdio: 'ignore', timeout: 5000 });
     }
     // Send a named key (Tab, Escape, Up, Down, etc.) without appending Enter.
     sendKey(key) {
         debug('tmux:send', `[${this.sessionId}] sendKey: ${key}`);
-        execFileSync('tmux', ['send-keys', '-t', this.sessionId, key]);
+        execFileSync('tmux', ['send-keys', '-t', this.sessionId, key], { stdio: 'ignore', timeout: 5000 });
     }
     async waitFor(pattern, timeoutMs, historyLines = 500) {
         const deadline = Date.now() + timeoutMs;
@@ -62,9 +120,10 @@ export class TuiScraper {
     kill() {
         debug('tmux', `killing session ${this.sessionId}`);
         try {
-            execFileSync('tmux', ['kill-session', '-t', this.sessionId], { stdio: 'ignore' });
+            execFileSync('tmux', ['kill-session', '-t', this.sessionId], { stdio: 'ignore', timeout: 3000 });
         }
         catch { /* already dead */ }
+        activeScrapers.delete(this); // delete after kill attempt so a concurrent signal doesn't see a half-killed scraper
     }
 }
 export function sleep(ms) {

package/package.json

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