منصوبے کے بارے میں

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 کے لیے مقامی اسٹورز — اور انہیں ایک واحد اسکیم میں نارملائز کرتا ہے۔ سب کچھ مقامی طور پر چلتا ہے: کوئی اسکریپنگ نہیں، کوئی کلاؤڈ APIs نہیں، کوئی لاگ ان نہیں، اور کوئی پرامپٹ یا ٹول مواد اسٹور نہیں کیا جاتا۔ صرف نوٹیفیکیشنز کی اختیاری اجازت مانگی جاتی ہے تاکہ کسی اہم واقعے کی صورت میں الرٹ مل سکے۔ سپورٹڈ ٹولز اور فिडیلٹی پالیسی ٹولز کے لحاظ سے کوریج مختلف ہے: Claude Code اور OpenCode درست ٹوکنز اور لاگت فراہم کرتے ہیں؛ Codex CLI اور Grok CLI درست ٹوکنز فراہم کرتے ہیں لیکن ان کی کوئی شائع شدہ شرح (rate) نہیں ہے؛ Cursor، Devin اور Antigravity مقامی طور پر ٹوکنز ریکارڈ نہیں کرتے اور اس لیے انہیں صرف سرگرمی کے طور پر کور کیا جاتا ہے۔ پروجیکٹ کے مطابق پالیسی میں کوئی "تخمینہ شدہ" (estimated) درجہ نہیں ہے — ٹوکن کاؤنٹ یا تو ٹول کے اپنے لاگز سے لفظ بہ لفظ پڑھا جاتا ہے یا پھر وہ موجود نہیں ہوتا، اور ٹوکنز کے بغیر قطاریں اب بھی کالز کے طور پر گنی جاتی ہیں لیکن انہیں ٹوکن اور لاگت کے مجموعوں سے نکال دیا جاتا ہے۔ کوڈ کی لائنوں سے Cursor ٹوکنز کا تخمینہ لگانے پر غور کیا گیا تھا لیکن اسے واضح طور پر مسترد کر دیا گیا۔ ایپ ایک مینو-بار آئٹم لائیو ٹوکنز، لاگت یا صرف آئیکن دکھاتا ہے، جو کسی واقعے کے کھلا ہونے پر رنگین ہو جاتا ہے۔ اس پر کلک کرنے سے ایک پینل کھلتا ہے جس میں اہم اعداد و شمار، ایک sparkline اور فی ٹول بارز ہوتے ہیں؛ ایک ڈیش بورڈ مکمل منظر فراہم کرتا ہے۔ اس کا خاص عنصر ایک واقعے سے لیس ٹائم لائن ہے جو فی ٹول ٹوکنز کو اسٹیک کرتی ہے اور ہوور کرنے پر بکیٹ کا نام، اس کے ٹوکنز اور وہاں ہونے والے کسی بھی واقعے کی نشاندہی کرتی ہے۔ ایپ اپنا کلیکٹر خود شامل کرتی ہے، اسے خود شروع کرتی ہے، اور اپنی جگہ اپ ڈیٹ ہوتی ہے: ایک checksummed archive کی ریلیز ون-کلک انسٹالیشن فراہم کرتی ہے جو بنڈل کو تبدیل کرنے سے پہلے شائع شدہ SHA-256 کی تصدیق کرتی ہے، اور ایسی ریلیز جس میں checksum نہ ہو وہ کبھی خاموشی سے انسٹال نہیں ہوتی۔ کمانڈ لائن اور 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) کے قوانین پانچ قوانین فراہم کیے گئے ہیں: billable_burn_spike (ایک 10 منٹ کی ونڈو جس کی لاگت اس سیشن کی عام ونڈو سے 3 گنا زیادہ ہو)، repeat_call_loop (5 منٹ میں 45+ کالز جبکہ آؤٹ پٹ ساکن رہے)، error_storm (15 منٹ میں کم از کم 5 غلطیوں کے ساتھ 20% سے زیادہ ایرر ریشو)، rate_limit_pressure (Codex 80% سے زیادہ کوٹہ استعمال ہونے کی رپورٹ کرے) اور context_pressure (ایک کال میں ماڈل کی سیاق و سباق ونڈو کا کم از کم 80% حصہ ہو)۔ بیس لائنز leave-one-out ہیں، جو ایک ونڈو کا موازنہ تمام دیگر ونڈوز کے میڈین سے کرتی ہیں، اور لوپ کی شناخت کے لیے دو سگنلز درکار ہوتے ہیں تاکہ کالز کے ایک پیداواری رش کو لوپ نہ سمجھ لیا جائے۔ لاگت کا ماڈل لاگت لسٹ قیمت پر مساوی API ویلیو ہے — یعنی API کے ذریعے استعمال کی لاگت کیا ہوتی — اور UI میں یہ نوٹ کیا گیا ہے کہ سبسکرپشن پلانز فی ٹوکن بل نہیں کیے جاتے۔ نرخ packages/core/src/data/pricing.json میں موجود ہیں، جنہیں effective_from کے ساتھ ورژن کیا گیا ہے، اور ایک فی-انسٹالیشن ~/.vole/pricing.json اس کے اوپر مرج ہوتا ہے تاکہ ریلیز کے بغیر ماڈل شامل کیا جا سکے؛ کسی ماڈل کی شرح آنے سے پہلے اسٹور کی گئی قطاروں کی قیمت بعد میں درست کی جاتی ہے۔ نامعلوم ماڈلز NULL واپس کرتے ہیں، کبھی 0 نہیں۔ تصدیق اور ٹیسٹنگ پروجیکٹ قوانین، کوئریز، بکیٹنگ اور کانفیڈنس انویرینٹس کے یونٹ ٹیسٹ کے لیے pnpm test، اور pnpm verify فراہم کرتا ہے، جو ایک آزادانہ طور پر دوبارہ نافذ کردہ لاگت فارمولے کا استعمال کرتے ہوئے ہر اسٹور شدہ قطار کا اس کے اپنے سورس ریکارڈ کے ساتھ مفاہمت کرتا ہے۔ تصدیق مجموعی کے بجائے فی ریکارڈ موازنہ کرتی ہے اور خالی اسٹور پر ناکام ہو جاتی ہے تاکہ کوئی کھوکھلی کامیابی حاصل نہ ہو۔ ایک pnpm seed کمانڈ 30 دنوں کی مصنوعی تاریخ لکھتی ہے جسے source='seed' کے طور پر ٹیگ کیا جاتا ہے اور لائیو ڈیٹا سے الگ چارٹ کیا جاتا ہے۔ بلڈنگ اور حدود سورس سے بلڈ کرنے کے لیے Node 22+، pnpm اور Xcode 26 درکار ہے، جسے macOS 26 arm64 پر ٹیسٹ کیا گیا ہے؛ pnpm app:bundle ایپ کو بلڈ اور اوپن کرتا ہے، یا کلیکٹر اور ایپ کو الگ سے چلایا جا سکتا ہے۔ دستاویزی حدود میں ان ٹولز کے لیے کم کوریج شامل ہے جو مقامی ٹوکنز ریکارڈ نہیں کرتے، is_error صرف API ایررز کو کور کرتا ہے جس سے error_storm کی تعداد کم ہو سکتی ہے، کچھ ٹولز کے لیے جنریشن اسپیڈز نچلی حد (lower bounds) ہوتی ہیں، سیاق و سباق کی ونڈوز صرف فرسٹ پارٹی ماڈل IDs کے لیے حل ہوتی ہیں، اور Antigravity کے لیے فائل mtimes پر مبنی تخمینی ٹائمنگ شامل ہے۔ پروجیکٹ MIT لائسنس کے تحت ہے اور تعاون کا خیرمقدم کرتا ہے، جس کے دو جائزہ قوانین ہیں: کبھی کوئی نمبر ایجاد نہ کریں، اور ہر کلیکٹر idempotent ہو۔