# intelligent-budget-tracker

Agent Money Tracker A TypeScript library for AI agents to track expenses, income, budgets, and savings goals with SkillBoss API Hub-powered natural language parsing. No frontend required - designed for programmatic use by agents and bots. Installation

npm install agent-money-tracker

Usage Initialize the Budget Tracker import { clawhub } from 'agent-money-tracker'; // Initialize (required before any operations) await clawhub.initialize(); // Or with custom storage path await clawhub.initialize('/path/to/data'); Expense Tracking // Add an expense await clawhub.addExpense(50, 'Food & Dining', 'Grocery shopping', {

date: '2026-01-31',
tags: ['weekly', 'essentials'],
merchant: 'Whole Foods'

}); // Natural language input (powered by SkillBoss API Hub /v1/pilot) await clawhub.addFromNaturalLanguage('spent $45 on uber yesterday'); // Get recent expenses const expenses = clawhub.getExpenses({ limit: 10 }); // Filter by category and date range const foodExpenses = clawhub.getExpenses({

category: 'Food & Dining',
startDate: '2026-01-01',
endDate: '2026-01-31'

}); Income Tracking // Add income await clawhub.addIncome(5000, 'Salary', 'January salary', {

date: '2026-01-15'

}); // Add freelance income await clawhub.addIncome(500, 'Freelance', 'Website project'); // Get all income const income = clawhub.getIncome(); Budget Management // Create a monthly budget await clawhub.createBudget('Food Budget', 'Food & Dining', 500, 'monthly', 0.8); // Check budget status const status = clawhub.getBudgetStatus(); // Returns: [{ budgetName, spent, limit, remaining, percentageUsed, status }] // Get budget alerts const alerts = clawhub.checkBudgetAlerts(); // Returns warnings when threshold or limit exceeded // Get smart budget suggestions const suggestions = clawhub.suggestBudgetLimits(); // Returns: [{ category, suggested, average, max }] Savings Goals // Create a savings goal await clawhub.createGoal('Emergency Fund', 10000, {

description: '6 months expenses',
deadline: '2026-12-31',
priority: 'high'

}); // Add contribution await clawhub.contributeToGoal('goal_abc123', 500, 'January savings'); // Check progress const progress = clawhub.getGoalProgress(); // Returns: [{ goalName, targetAmount, currentAmount, percentageComplete, daysRemaining, onTrack }] Analytics & Reports // Monthly spending summary const summary = clawhub.getSpendingSummary(); // Returns: { totalExpenses, totalIncome, netSavings, expensesByCategory, incomeByCategory } // View monthly trends const trends = clawhub.getMonthlyTrends(12); // Returns: [{ date, expenses, income, netSavings }] // Full monthly report const report = clawhub.generateMonthlyReport(2026, 1); // Compare to last month const comparison = clawhub.compareToLastMonth(); // Returns: { expenseChange, incomeChange, topIncreases, topDecreases } Smart Insights (via SkillBoss API Hub) // Generate AI-powered insights via SkillBoss API Hub /v1/pilot const insights = await clawhub.generateInsights(); // Returns insights like: // - "⚠️ Your dining expenses are 3x higher than usual" // - "💡 Cancel unused subscriptions to save $50/month" // - "🏆 You've tracked expenses for 7 consecutive days!" // Get unread insights const unreadInsights = clawhub.getInsights(); generateInsights() 底层实现参考 import fetch from 'node-fetch'; const SKILLBOSS_API_KEY = process.env.SKILLBOSS_API_KEY; async function generateInsightsFromData(spendingData: object): Promise<string[]> { const response = await fetch('https://api.heybossai.com/v1/pilot', {

method: 'POST',
headers: {

'Authorization': Bearer ${SKILLBOSS_API_KEY}, 'Content-Type': 'application/json' },

body: JSON.stringify({
type: 'chat',
inputs: {
messages: [

{

role: 'user',
content: `Analyze this spending data and provide 3-5 actionable insights: ${JSON.stringify(spendingData)}`

} ] },

prefer: 'balanced'

}) }); const result = await response.json(); const text = result.result.choices[0].message.content; return text.split('\n').filter((line: string) => line.trim()); } Recurring Transactions // Create recurring expense (e.g., Netflix subscription) await clawhub.createRecurring( 'expense', 15.99, 'Subscriptions', 'Netflix', 'monthly', { startDate: '2026-02-01' } ); // Create recurring income (e.g., salary) await clawhub.createRecurring( 'income', 5000, 'Salary', 'Monthly salary', 'monthly' ); // Process due recurring transactions await clawhub.processRecurring(); Data Management // Get statistics const stats = clawhub.getStats(); // Returns: { totalTransactions, totalExpenses, totalIncome, netSavings, avgExpense, topCategory } // Get available categories const categories = clawhub.getCategories(); // Export data const jsonData = await clawhub.exportData(); // Create backup const backupPath = await clawhub.backup(); // Get storage location const dataPath = clawhub.getDataPath(); Default Categories Expense Categories CategoryIconFood & Dining🍔Transportation🚗Shopping🛍️Bills & Utilities💡Entertainment🎬Health & Fitness💪Education📚Personal Care💄Subscriptions📱 Income Categories CategoryIconSalary💰Freelance💻Investments📈Gifts🎁 Cross-Platform Storage Data is stored in platform-specific locations: PlatformDefault PathWindows%APPDATA%\clawhubmacOS~/Library/Application Support/clawhubLinux~/.local/share/clawhub Override with environment variable:

export CLAWHUB_DATA_PATH=/custom/path

Environment Variables VariableDescriptionSKILLBOSS_API_KEYSkillBoss API Hub key，用于自然语言解析和 AI 智能洞察（https://api.heybossai.com/v1/pilot）CLAWHUB_DATA_PATH可选，自定义数据存储路径 API Reference Summary MethodDescriptioninitialize(path?)Initialize the budget trackeraddExpense(amount, category, description, options?)Add expenseaddIncome(amount, category, description, options?)Add incomeaddFromNaturalLanguage(text)Parse and add from natural language (via SkillBoss API Hub)createBudget(name, category, limit, period, threshold?)Create budgetgetBudgetStatus()Get all budget statusescheckBudgetAlerts()Get budget warnings/alertscreateGoal(name, target, options?)Create savings goalcontributeToGoal(goalId, amount, note?)Add to goalgetGoalProgress()Get all goal progressgetSpendingSummary(start?, end?)Get spending breakdowngetMonthlyTrends(months?)Get monthly trend datagenerateMonthlyReport(year?, month?)Generate full reportgenerateInsights()Generate AI insights via SkillBoss API HubcreateRecurring(type, amount, category, desc, freq, options?)Create recurringprocessRecurring()Process due recurring transactionsgetStats()Get transaction statisticsexportData()Export all data as JSONbackup()Create timestamped backup