agent-fuel 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# ⚡️ Agent Fuel (`agent-fuel`)
+
+A sleek, unified CLI dashboard to monitor your AI coding assistant quotas, credits, and token usage in real-time.
+
+---
+
+## 🚀 Quick Start
+
+Get **Agent Fuel** installed, globally linked, and running on your system with a single one-liner command:
+
+```bash
+npm install && npm run build && npm link && agent-fuel
+```
+
+Once globally linked, you can run the dashboard at any time from **any directory** on your machine by simply typing:
+
+```bash
+agent-fuel
+```
+
+---
+
+## 💡 The Motivation
+
+AI coding assistants are now integral to developer workflows. Tools like **Claude Code**, **Codex CLI**, and **AGY (Google Antigravity CLI)** supercharge productivity but operate under tight, separate quota bounds. Whether it is a daily dollar limit, token ceilings, or monthly credits, developers are forced to jump through interactive prompts or scrape configuration screens just to answer a simple question:
+
+> **"How much agent fuel do I have left before starting this massive refactor?"**
+
+Because each CLI exposes quota information differently (some via strict JSON, others through human-readable prompts, and some in local state files), there is no centralized way to monitor your resource consumption. 
+
+**Agent Fuel** solves this by acting as a lightweight, adapter-based abstraction layer that normalizes all coding agent quotas into a single metric: **Percent Remaining**.
+
+---
+
+## 🎯 The Idea
+
+`agent-fuel` is a tiny, modern local CLI built with TypeScript that:
+1. **Dispatches Adapters**: Queries each configured AI coding tool (Claude Code, Codex, AGY) using native CLI calls, helper utilities (like `ccusage`), or local config parsing.
+2. **Normalizes Quota Models**: Standardizes diverse limits into a uniform percentage score (`0` to `100%`).
+3. **Renders an Elegant CLI Dashboard**: Displays a high-fidelity 3-bar ASCII progress dashboard directly in your terminal.
+
+### Proposed Architecture
+
+```text
+agent-fuel/
+  ├── src/
+  │   ├── index.ts          # CLI entry point
+  │   ├── render.ts         # Beautiful 3-bar dashboard renderer
+  │   └── adapters/
+  │       ├── claude.ts     # Adapter for Claude Code (ccusage/native)
+  │       ├── codex.ts      # Adapter for Codex (local session/status)
+  │       ├── agy.ts        # Adapter for AGY (Antigravity config parser)
+  │       └── ccusage.ts    # Shared JSON parser helper
+  ├── package.json
+  └── README.md
+```
+
+### High-Fidelity API Type Shape
+
+```typescript
+type UsageSnapshot = {
+  tool: 'codex' | 'claude-code' | 'agy';
+  remainingPercent: number | null; // Unified 0-100 scale
+  usedPercent?: number | null;
+  resetAt?: string | null;
+  source: 'official-cli' | 'ccusage' | 'local-state' | 'provider-api' | 'unknown';
+  raw?: unknown;
+};
+```
+
+---
+
+## 📊 Terminal Dashboard Preview
+
+Running `agent-fuel` will immediately output a clean, colored visual summary of your current agent capacity:
+
+```text
+⚡️ Agent Fuel - CLI Quota Monitor
+
+Codex        [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] unknown
+Claude Code  [██████████████████████████░░░░]  86% remaining (resets 01:00 PM)
+AGY          [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] unknown
+```
+
+

package/dist/adapters/agy.d.ts

@@ -0,0 +1,6 @@
+import { QuotaAdapter, UsageSnapshot } from './index.js';
+export declare class AgyQuotaAdapter implements QuotaAdapter {
+    private configDir;
+    constructor();
+    fetchSnapshot(): Promise<UsageSnapshot>;
+}

package/dist/adapters/agy.js

@@ -0,0 +1,108 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+export class AgyQuotaAdapter {
+    configDir;
+    constructor() {
+        // Default to the standard AGY CLI config directory
+        this.configDir = path.join(os.homedir(), '.gemini/antigravity-cli');
+    }
+    async fetchSnapshot() {
+        try {
+            const settingsPath = path.join(this.configDir, 'settings.json');
+            const historyPath = path.join(this.configDir, 'history.jsonl');
+            let activeModel = 'Gemini 3.5 Flash';
+            // 1. Read active model from settings.json if it exists
+            try {
+                const settingsContent = await fs.readFile(settingsPath, 'utf-8');
+                const settings = JSON.parse(settingsContent);
+                if (settings && settings.model) {
+                    activeModel = settings.model;
+                }
+            }
+            catch {
+                // Fallback to default model name if reading or parsing settings failed
+            }
+            // 2. Read history.jsonl to detect active prompts today
+            let todayPromptsCount = 0;
+            let latestPromptTimestamp = null;
+            // Construct local todayPrefix in YYYY-MM-DD format (timezone aware)
+            const now = new Date();
+            const year = now.getFullYear();
+            const month = String(now.getMonth() + 1).padStart(2, '0');
+            const day = String(now.getDate()).padStart(2, '0');
+            const todayPrefix = `${year}-${month}-${day}`;
+            try {
+                const historyContent = await fs.readFile(historyPath, 'utf-8');
+                const historyLines = historyContent.trim().split('\n');
+                for (const line of historyLines) {
+                    if (!line.trim())
+                        continue;
+                    const entry = JSON.parse(line);
+                    if (entry && entry.timestamp) {
+                        // Get local date YYYY-MM-DD for the entry's timestamp
+                        const entryDateObj = new Date(entry.timestamp);
+                        const eYear = entryDateObj.getFullYear();
+                        const eMonth = String(entryDateObj.getMonth() + 1).padStart(2, '0');
+                        const eDay = String(entryDateObj.getDate()).padStart(2, '0');
+                        const entryDate = `${eYear}-${eMonth}-${eDay}`;
+                        if (entryDate === todayPrefix) {
+                            todayPromptsCount++;
+                            if (!latestPromptTimestamp || entry.timestamp > latestPromptTimestamp) {
+                                latestPromptTimestamp = entry.timestamp;
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // Fallback if reading or parsing history failed (e.g. file doesn't exist)
+            }
+            // 3. Calculate remaining percent based on active usage and model tier
+            // Support dynamic overrides using AGENT_FUEL_AGY_PERCENT environment variable
+            let remainingPercent = 100;
+            const isProModel = activeModel.toLowerCase().includes('pro');
+            const limit = isProModel ? 3 : 5; // Pro models have a tighter limit of 3, Flash has 5
+            const costPerPrompt = 100 / limit;
+            const calculatedPercent = Math.max(0, Math.round(100 - (todayPromptsCount * costPerPrompt)));
+            if (process.env.AGENT_FUEL_AGY_PERCENT) {
+                const envVal = Number(process.env.AGENT_FUEL_AGY_PERCENT);
+                remainingPercent = !isNaN(envVal) ? Math.max(0, Math.min(100, envVal)) : calculatedPercent;
+            }
+            else {
+                remainingPercent = calculatedPercent;
+            }
+            // 4. Calculate rolling reset time (5 hours rolling or resets in 4h 37m from latest prompt, giving ~01:30 PM resets)
+            let resetAt = null;
+            if (latestPromptTimestamp) {
+                try {
+                    const lastActivityDate = new Date(latestPromptTimestamp);
+                    // Roll forward 5 hours (refreshes in ~4h 37m from active run)
+                    const resetDate = new Date(lastActivityDate.getTime() + 5 * 60 * 60 * 1000);
+                    resetAt = resetDate.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+                }
+                catch {
+                    resetAt = null;
+                }
+            }
+            return {
+                tool: 'agy',
+                remainingPercent,
+                usedPercent: 100 - remainingPercent,
+                resetAt,
+                source: 'local-state',
+                raw: { activeModel, todayPromptsCount }
+            };
+        }
+        catch (error) {
+            return {
+                tool: 'agy',
+                remainingPercent: null,
+                usedPercent: null,
+                resetAt: null,
+                source: 'unknown',
+                raw: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+}

package/dist/adapters/claude.d.ts

@@ -0,0 +1,6 @@
+import { QuotaAdapter, UsageSnapshot } from './index.js';
+export declare class ClaudeQuotaAdapter implements QuotaAdapter {
+    private budgetLimit;
+    constructor();
+    fetchSnapshot(): Promise<UsageSnapshot>;
+}

package/dist/adapters/claude.js

@@ -0,0 +1,72 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+export class ClaudeQuotaAdapter {
+    budgetLimit;
+    constructor() {
+        // Default to $10.00 for the rolling 5-hour window, allow env override
+        this.budgetLimit = Number(process.env.AGENT_FUEL_CLAUDE_BUDGET) || 10.0;
+    }
+    async fetchSnapshot() {
+        try {
+            // Execute ccusage to get billing block information in JSON format
+            // We run npx --no-install first to see if it's already cached/available, otherwise fall back to regular npx
+            let stdout;
+            try {
+                const result = await execAsync('npx --no-install ccusage blocks --json');
+                stdout = result.stdout;
+            }
+            catch {
+                throw new Error('ccusage package is not installed or available locally. Please run "npm install -g ccusage" to use this tool.');
+            }
+            const data = JSON.parse(stdout);
+            const blocks = data && Array.isArray(data.blocks) ? data.blocks : data;
+            if (!blocks || !Array.isArray(blocks)) {
+                throw new Error('Invalid JSON format returned from ccusage blocks');
+            }
+            // Find the active billing block
+            const activeBlock = blocks.find((block) => block.isActive === true);
+            if (!activeBlock) {
+                return {
+                    tool: 'claude-code',
+                    remainingPercent: null,
+                    usedPercent: null,
+                    resetAt: null,
+                    source: 'unknown'
+                };
+            }
+            const cost = activeBlock.costUSD || 0.0;
+            const usedPercent = (cost / this.budgetLimit) * 100;
+            const remainingPercent = Math.max(0, Math.min(100, Math.round(100 - usedPercent)));
+            let resetAt = null;
+            if (activeBlock.endTime) {
+                try {
+                    const endDate = new Date(activeBlock.endTime);
+                    resetAt = endDate.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+                }
+                catch {
+                    resetAt = activeBlock.endTime;
+                }
+            }
+            return {
+                tool: 'claude-code',
+                remainingPercent,
+                usedPercent: Math.round(usedPercent),
+                resetAt,
+                source: 'ccusage',
+                raw: activeBlock
+            };
+        }
+        catch (error) {
+            // Fallback in case of execution errors
+            return {
+                tool: 'claude-code',
+                remainingPercent: null,
+                usedPercent: null,
+                resetAt: null,
+                source: 'unknown',
+                raw: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+}

package/dist/adapters/codex.d.ts

@@ -0,0 +1,6 @@
+import { QuotaAdapter, UsageSnapshot } from './index.js';
+export declare class CodexQuotaAdapter implements QuotaAdapter {
+    private budgetLimit;
+    constructor();
+    fetchSnapshot(): Promise<UsageSnapshot>;
+}

package/dist/adapters/codex.js

@@ -0,0 +1,105 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+export class CodexQuotaAdapter {
+    budgetLimit;
+    constructor() {
+        // Default budget limit of $20.00 for the rolling 5h window (Standard Team/Plus limit)
+        // Allows dynamic override using environment variable AGENT_FUEL_CODEX_BUDGET
+        this.budgetLimit = Number(process.env.AGENT_FUEL_CODEX_BUDGET) || 20.0;
+    }
+    async fetchSnapshot() {
+        try {
+            // Execute ccusage to get Codex session data
+            let stdout;
+            try {
+                const result = await execAsync('npx --no-install ccusage codex session --json');
+                stdout = result.stdout;
+            }
+            catch {
+                throw new Error('ccusage package is not installed or available locally. Please run "npm install -g ccusage" to use this tool.');
+            }
+            const data = JSON.parse(stdout);
+            const sessions = data && Array.isArray(data.sessions) ? data.sessions : (data && Array.isArray(data.session) ? data.session : data);
+            if (!sessions || !Array.isArray(sessions)) {
+                throw new Error('Invalid JSON format returned from ccusage codex session');
+            }
+            // Filter sessions for today's date in local time
+            const now = new Date();
+            const year = now.getFullYear();
+            const month = String(now.getMonth() + 1).padStart(2, '0');
+            const day = String(now.getDate()).padStart(2, '0');
+            const todayPrefix = `${year}-${month}-${day}`;
+            const todaySessions = sessions.filter((s) => {
+                if (!s.lastActivity)
+                    return false;
+                try {
+                    const dateObj = new Date(s.lastActivity);
+                    const sYear = dateObj.getFullYear();
+                    const sMonth = String(dateObj.getMonth() + 1).padStart(2, '0');
+                    const sDay = String(dateObj.getDate()).padStart(2, '0');
+                    const sLocalDate = `${sYear}-${sMonth}-${sDay}`;
+                    return sLocalDate === todayPrefix;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (todaySessions.length === 0) {
+                // No activity today, so 100% fuel remaining
+                return {
+                    tool: 'codex',
+                    remainingPercent: 100,
+                    usedPercent: 0,
+                    resetAt: null,
+                    source: 'ccusage'
+                };
+            }
+            // Sum today's cost
+            const totalCost = todaySessions.reduce((acc, s) => acc + (s.costUSD || 0.0), 0.0);
+            const usedPercent = (totalCost / this.budgetLimit) * 100;
+            // Calculate remaining percentage
+            let remainingPercent = 100 - usedPercent;
+            if (usedPercent > 0 && remainingPercent > 99) {
+                // Micro-interaction: if they burned any credits, show 99% instead of rounding to 100%
+                remainingPercent = 99;
+            }
+            else {
+                remainingPercent = Math.max(0, Math.min(100, Math.round(remainingPercent)));
+            }
+            // Calculate rolling 5-hour reset time based on the most recent session's activity
+            let resetAt = null;
+            const sortedSessions = [...todaySessions].sort((a, b) => new Date(b.lastActivity).getTime() - new Date(a.lastActivity).getTime());
+            const latestSession = sortedSessions[0];
+            if (latestSession && latestSession.lastActivity) {
+                try {
+                    const lastActivityDate = new Date(latestSession.lastActivity);
+                    // Roll forward 5 hours for the rolling limit window
+                    const resetDate = new Date(lastActivityDate.getTime() + 5 * 60 * 60 * 1000);
+                    resetAt = resetDate.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+                }
+                catch {
+                    resetAt = null;
+                }
+            }
+            return {
+                tool: 'codex',
+                remainingPercent,
+                usedPercent: Math.round(usedPercent),
+                resetAt,
+                source: 'ccusage',
+                raw: { totalCost, todaySessionsCount: todaySessions.length }
+            };
+        }
+        catch (error) {
+            return {
+                tool: 'codex',
+                remainingPercent: null,
+                usedPercent: null,
+                resetAt: null,
+                source: 'unknown',
+                raw: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+}

package/dist/adapters/index.d.ts

@@ -0,0 +1,11 @@
+export interface UsageSnapshot {
+    tool: 'codex' | 'claude-code' | 'agy';
+    remainingPercent: number | null;
+    usedPercent?: number | null;
+    resetAt?: string | null;
+    source: 'official-cli' | 'ccusage' | 'local-state' | 'provider-api' | 'unknown';
+    raw?: unknown;
+}
+export interface QuotaAdapter {
+    fetchSnapshot(): Promise<UsageSnapshot>;
+}

package/dist/adapters/index.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { ClaudeQuotaAdapter } from './adapters/claude.js';
+import { CodexQuotaAdapter } from './adapters/codex.js';
+import { AgyQuotaAdapter } from './adapters/agy.js';
+import { renderDashboard } from './render.js';
+async function main() {
+    const claudeAdapter = new ClaudeQuotaAdapter();
+    const codexAdapter = new CodexQuotaAdapter();
+    const agyAdapter = new AgyQuotaAdapter();
+    try {
+        // Run all adapters concurrently to minimize startup latency
+        const [claudeSnap, codexSnap, agySnap] = await Promise.all([
+            claudeAdapter.fetchSnapshot(),
+            codexAdapter.fetchSnapshot(),
+            agyAdapter.fetchSnapshot()
+        ]);
+        // Render the beautiful 3-bar ASCII progress dashboard
+        renderDashboard([
+            codexSnap,
+            claudeSnap,
+            agySnap
+        ]);
+    }
+    catch (error) {
+        console.error('\x1b[31mFatal error orchestrating Agent Fuel CLI:\x1b[0m', error);
+        process.exit(1);
+    }
+}
+main();

package/dist/render.d.ts

@@ -0,0 +1,2 @@
+import { UsageSnapshot } from './adapters/index.js';
+export declare function renderDashboard(snapshots: UsageSnapshot[]): void;

package/dist/render.js

@@ -0,0 +1,61 @@
+export function renderDashboard(snapshots) {
+    const reset = '\x1b[0m';
+    const bold = '\x1b[1m';
+    const dim = '\x1b[2m';
+    const cyan = '\x1b[36m';
+    const green = '\x1b[32m';
+    const yellow = '\x1b[33m';
+    const red = '\x1b[31m';
+    const gray = '\x1b[90m';
+    console.log(`\n${bold}${cyan}⚡️ Agent Fuel - CLI Quota Monitor${reset}\n`);
+    for (const snap of snapshots) {
+        const displayName = getDisplayName(snap.tool);
+        const remaining = snap.remainingPercent;
+        const width = 30;
+        let barStr = '';
+        let percentStr = '';
+        if (remaining === null || remaining === undefined) {
+            // Unknown/Unconfigured quota
+            barStr = `${gray}${'░'.repeat(width)}${reset}`;
+            percentStr = `${gray}unknown${reset}`;
+        }
+        else {
+            const filled = Math.max(0, Math.min(width, Math.round((remaining * width) / 100)));
+            const empty = width - filled;
+            // Color scheme based on remaining percentage
+            let color = green;
+            if (remaining < 20) {
+                color = red;
+            }
+            else if (remaining < 50) {
+                color = yellow;
+            }
+            const blockChar = '█';
+            const shadeChar = '░';
+            barStr = `${color}${blockChar.repeat(filled)}${reset}${gray}${shadeChar.repeat(empty)}${reset}`;
+            percentStr = `${bold}${color}${remaining.toString().padStart(3)}% remaining${reset}`;
+        }
+        // Add metadata/reset times if available
+        let detailStr = '';
+        if (snap.resetAt) {
+            detailStr = ` ${dim}${gray}(resets ${snap.resetAt})${reset}`;
+        }
+        if (snap.tool === 'agy' && snap.raw && typeof snap.raw === 'object' && 'activeModel' in snap.raw) {
+            detailStr += ` ${dim}${gray}[${snap.raw.activeModel}]${reset}`;
+        }
+        console.log(`${bold}${displayName.padEnd(12)}${reset} [${barStr}] ${percentStr}${detailStr}`);
+    }
+    console.log('');
+}
+function getDisplayName(tool) {
+    switch (tool) {
+        case 'codex':
+            return 'Codex';
+        case 'claude-code':
+            return 'Claude Code';
+        case 'agy':
+            return 'AGY';
+        default:
+            return tool;
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "agent-fuel",
+  "version": "0.1.0",
+  "description": "Sleek term-based dashboard for AI coding CLI quotas",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agent-fuel": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "quota",
+    "dashboard",
+    "claude",
+    "codex",
+    "agy"
+  ],
+  "author": "Pedro Rodrigues",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "typescript": "^5.3.3"
+  }
+}