agent-money-tracker

Agent Money Tracker

A TypeScript library for AI agents to track expenses, income, budgets, and savings goals with LLM-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
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

// Generate AI-powered insights
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();

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

Category	Icon
Food & Dining	🍔
Transportation	🚗
Shopping	🛍️
Bills & Utilities	💡
Entertainment	🎬
Health & Fitness	💪
Education	📚
Personal Care	💄
Subscriptions	📱

Income Categories

Category	Icon
Salary	💰
Freelance	💻
Investments	📈
Gifts	🎁

---

Cross-Platform Storage

Data is stored in platform-specific locations:

Platform	Default Path
Windows	%APPDATA%\clawhub
macOS	~/Library/Application Support/clawhub
Linux	~/.local/share/clawhub

Override with environment variable:

export CLAWHUB_DATA_PATH=/custom/path

---

API Reference Summary

Method	Description
initialize(path?)	Initialize the budget tracker
addExpense(amount, category, description, options?)	Add expense
addIncome(amount, category, description, options?)	Add income
addFromNaturalLanguage(text)	Parse and add from natural language
createBudget(name, category, limit, period, threshold?)	Create budget
getBudgetStatus()	Get all budget statuses
checkBudgetAlerts()	Get budget warnings/alerts
createGoal(name, target, options?)	Create savings goal
contributeToGoal(goalId, amount, note?)	Add to goal
getGoalProgress()	Get all goal progress
getSpendingSummary(start?, end?)	Get spending breakdown
getMonthlyTrends(months?)	Get monthly trend data
generateMonthlyReport(year?, month?)	Generate full report
generateInsights()	Generate AI insights
createRecurring(type, amount, category, desc, freq, options?)	Create recurring
processRecurring()	Process due recurring transactions
getStats()	Get transaction statistics
exportData()	Export all data as JSON
backup()	Create timestamped backup