इस प्रोजेक्ट के बारे में

Vole AI कोडिंग एजेंटों के लिए एक local-first उपयोग, लागत और विसंगति (anomaly) मॉनिटर है। यह उन स्थितियों को लक्षित करता है जहाँ कई एजेंट साथ-साथ चलते हैं, जिनमें से प्रत्येक स्वतंत्र रूप से टोकन खर्च करता है और कोई भी यह संकेत नहीं देता कि कुछ गलत हो गया है — जैसे कि टूल लूप में फंसना, टूटे हुए API के खिलाफ पुनः प्रयास करना, या बार-बार एक ही बड़े संदर्भ (context) को पढ़ना। जहाँ अन्य उपकरण यह उत्तर देते हैं कि "मैंने कितना खर्च किया?", Vole यह पूछता है कि "क्या अभी कुछ गलत हो रहा है?" और खर्च की रिपोर्ट एक साइड इफेक्ट के रूप में देता है। डेटा हैंडलिंग Vole उन लॉग फाइलों को पढ़ता है जिन्हें उपकरण पहले से ही डिस्क पर लिखते हैं — उदाहरण के लिए Claude Code के लिए ~/.claude/projects/**/*.jsonl, OpenCode के लिए ~/.local/share/opencode/opencode.db, Codex CLI के लिए ~/.codex/sessions/**/rollout-*.jsonl, Grok CLI के लिए ~/.grok/logs/unified.jsonl, साथ ही Cursor, Devin और Antigravity के लिए स्थानीय स्टोर — और उन्हें एक एकल स्कीमा में सामान्य (normalize) करता है। सब कुछ स्थानीय रूप से चलता है: कोई स्क्रैपिंग नहीं, कोई क्लाउड API नहीं, कोई लॉगिन नहीं, और कोई प्रॉम्प्ट या टूल सामग्री संग्रहीत नहीं की जाती है। केवल वैकल्पिक अनुमति नोटिफिकेशन के लिए मांगी जाती है, ताकि गंभीर घटना होने पर अलर्ट मिल सके। समर्थित उपकरण और फिडेलिटी पॉलिसी कवरेज उपकरण के अनुसार भिन्न होता है: Claude Code और OpenCode सटीक टोकन और लागत प्रदान करते हैं; Codex CLI और Grok CLI सटीक टोकन प्रदान करते हैं लेकिन उनकी कोई प्रकाशित दर नहीं है; Cursor, Devin और Antigravity स्थानीय रूप से कोई टोकन रिकॉर्ड नहीं करते हैं और इसलिए केवल गतिविधि के रूप में कवर किए जाते हैं। प्रोजेक्ट की नीति है कि कोई "अनुमानित" स्तर नहीं होगा — टोकन काउंट या तो उपकरण के अपने लॉग से शब्दशः पढ़ा जाता है या वास्तव में अनुपस्थित होता है, और बिना टोकन वाली पंक्तियाँ अभी भी कॉल के रूप में गिनी जाती हैं लेकिन उन्हें टोकन और लागत समुच्चय (aggregates) से बाहर रखा जाता है। कोड की लाइनों से Cursor टोकन का अनुमान लगाने पर विचार किया गया था और इसे स्पष्ट रूप से खारिज कर दिया गया था। ऐप एक menu-bar आइटम लाइव टोकन, लागत या केवल आइकन दिखाता है, जो घटना (incident) खुले होने पर रंगीन हो जाता है। इस पर क्लिक करने से मुख्य आंकड़े, एक स्पार्कलाइन और प्रति-उपकरण बार वाला पैनल खुलता है; एक डैशबोर्ड पूर्ण दृश्य प्रदान करता है। इसका मुख्य तत्व एक घटना-एनोटेटेड टाइमलाइन है जो प्रति उपकरण टोकन को स्टैक करता है और होवर करने पर बकेट का नाम, उसके टोकन और वहां हुई किसी भी घटना को बताता है। ऐप अपना स्वयं का कलेक्टर एम्बेड करता है, इसे स्वयं शुरू करता है, और यथास्थान अपडेट करता है: चेकसम वाला आर्काइव प्रकाशित करने वाला रिलीज़ एक-क्लिक इंस्टॉल प्रदान करता है जो बंडल बदलने से पहले प्रकाशित SHA-256 को सत्यापित करता है, और बिना चेकसम वाला रिलीज़ कभी भी साइलेंट-इंस्टॉल नहीं होता है। कमांड लाइन और MCP ऐप के साथ, Vole उसी डेटा पर टर्मिनल कमांड उपलब्ध कराता है: pnpm top (लाइव सत्र, संदर्भ बनाम विंडो, टोकन प्रति मिनट, कैश काउंटडाउन), pnpm digest (रेंज और JSON विकल्पों के साथ एक मार्कडाउन एजेंट-उपयोग सारांश), pnpm pr (PR विवरण के लिए वर्तमान ब्रांच पर उपयोग), pnpm statusline, और pnpm mcp, एक stdio MCP सर्वर। MCP सर्वर vole_summary, vole_live_sessions, vole_session, vole_incidents, vole_breakdown, vole_whatif और vole_digest को एक्सपोज़ करता है, ताकि एक एजेंट पूछ सके कि उसके अपने सत्र की लागत क्या रही है या Vole ने उसे चिह्नित किया है या नहीं। सर्वर स्थानीय डेटाबेस को पढ़ता है और stdout पर उत्तर देता है। विसंगति नियम (Anomaly rules) पाँच नियम दिए गए हैं: billable_burn_spike (एक 10-मिनट की विंडो जिसकी लागत उस सत्र की विशिष्ट विंडो से 3 गुना अधिक हो), repeat_call_loop (आउटपुट स्थिर रहने पर 5 मिनट में 45+ कॉल), error_storm (कम से कम 5 त्रुटियों के साथ 15 मिनट में 20% से अधिक त्रुटि अनुपात), rate_limit_pressure (Codex द्वारा कोटा के 80% से अधिक खपत की रिपोर्ट) और context_pressure (एक कॉल जिसमें मॉडल की संदर्भ विंडो का कम से कम 80% हिस्सा हो)। बेसलाइन 'leave-one-out' हैं, जो एक विंडो की तुलना अन्य सभी विंडो के माध्यिका (median) से करती हैं, और लूप डिटेक्शन के लिए दो संकेतों की आवश्यकता होती है ताकि कॉल के उत्पादक विस्फोट को लूप समझने की गलती न हो। लागत मॉडल लागत सूची मूल्य पर समकक्ष API मूल्य है — यानी API के माध्यम से उपयोग की लागत क्या होती — और UI यह नोट करता है कि सब्सक्रिप्शन प्लान प्रति टोकन बिल नहीं किए जाते हैं। दरें packages/core/src/data/pricing.json में रहती हैं, जिन्हें effective_from के साथ वर्जन किया गया है, और एक प्रति-इंस्टॉलेशन ~/.vole/pricing.json इसके ऊपर मर्ज होता है ताकि बिना रिलीज़ के एक मॉडल जोड़ा जा सके; जिस मॉडल की दर होने से पहले संग्रहीत पंक्तियों को रेट्रोएक्टिव रूप से फिर से मूल्यित किया जाता है। अज्ञात मॉडल NULL लौटाते हैं, कभी 0 नहीं। सत्यापन और परीक्षण प्रोजेक्ट नियमों, क्वेरीज़, बकेटिंग और कॉन्फिडेंस इनवेरिएंट्स के यूनिट टेस्ट के लिए pnpm test, और pnpm verify प्रदान करता है, जो स्वतंत्र रूप से पुन: कार्यान्वित लागत सूत्र का उपयोग करके प्रत्येक संग्रहीत पंक्ति का उसके अपने स्रोत रिकॉर्ड के साथ मिलान करता है। सत्यापन कुल के बजाय प्रति रिकॉर्ड तुलना करता है और खाली स्टोर पर विफल हो जाता है ताकि शून्य पास (vacuous pass) न हो सके। एक pnpm seed कमांड source='seed' टैग के साथ 30 दिनों का सिंथेटिक इतिहास लिखता है, जिसे लाइव डेटा से अलग चार्ट किया जाता है। बिल्डिंग और सीमाएं सोर्स से बिल्ड करने के लिए Node 22+, pnpm और Xcode 26 की आवश्यकता होती है, जिसे macOS 26 arm64 पर टेस्ट किया गया है; pnpm app:bundle ऐप को बिल्ड और ओपन करता है, या कलेक्टर और ऐप को अलग से चलाया जा सकता है। प्रलेखित सीमाओं में उन उपकरणों के लिए उथला कवरेज शामिल है जो कोई स्थानीय टोकन रिकॉर्ड नहीं करते हैं, is_error केवल API त्रुटियों को कवर करता है जिससे error_storm कम गणना कर सकता है, कुछ उपकरणों के लिए जनरेशन स्पीड लोअर बाउंड होती है, संदर्भ विंडो केवल फर्स्ट-पार्टी मॉडल आईडी के लिए रिज़ॉल्व होती है, और Antigravity के लिए फाइल mtimes पर आधारित अनुमानित समय होता है। प्रोजेक्ट MIT लाइसेंस प्राप्त है और योगदान का स्वागत करता है, जिसमें दो समीक्षा नियम बताए गए हैं: कभी कोई संख्या न गढ़ें, और प्रत्येक कलेक्टर इडेम्पोटेंट (idempotent) होना चाहिए।