\r \r

Agent Money Tracker\r

\r 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.\r \r

Installation\r

\r

npm install agent-money-tracker\r
```\r
\r
---\r
\r
## Usage\r
\r
### Initialize the Budget Tracker\r
\r
```typescript\r
import { clawhub } from 'agent-money-tracker';\r
\r
// Initialize (required before any operations)\r
await clawhub.initialize();\r
\r
// Or with custom storage path\r
await clawhub.initialize('/path/to/data');\r
```\r
\r
### Expense Tracking\r
\r
```typescript\r
// Add an expense\r
await clawhub.addExpense(50, 'Food & Dining', 'Grocery shopping', {\r
  date: '2026-01-31',\r
  tags: ['weekly', 'essentials'],\r
  merchant: 'Whole Foods'\r
});\r
\r
// Natural language input\r
await clawhub.addFromNaturalLanguage('spent $45 on uber yesterday');\r
\r
// Get recent expenses\r
const expenses = clawhub.getExpenses({ limit: 10 });\r
\r
// Filter by category and date range\r
const foodExpenses = clawhub.getExpenses({\r
  category: 'Food & Dining',\r
  startDate: '2026-01-01',\r
  endDate: '2026-01-31'\r
});\r
```\r
\r
### Income Tracking\r
\r
```typescript\r
// Add income\r
await clawhub.addIncome(5000, 'Salary', 'January salary', {\r
  date: '2026-01-15'\r
});\r
\r
// Add freelance income\r
await clawhub.addIncome(500, 'Freelance', 'Website project');\r
\r
// Get all income\r
const income = clawhub.getIncome();\r
```\r
\r
### Budget Management\r
\r
```typescript\r
// Create a monthly budget\r
await clawhub.createBudget('Food Budget', 'Food & Dining', 500, 'monthly', 0.8);\r
\r
// Check budget status\r
const status = clawhub.getBudgetStatus();\r
// Returns: [{ budgetName, spent, limit, remaining, percentageUsed, status }]\r
\r
// Get budget alerts\r
const alerts = clawhub.checkBudgetAlerts();\r
// Returns warnings when threshold or limit exceeded\r
\r
// Get smart budget suggestions\r
const suggestions = clawhub.suggestBudgetLimits();\r
// Returns: [{ category, suggested, average, max }]\r
```\r
\r
### Savings Goals\r
\r
```typescript\r
// Create a savings goal\r
await clawhub.createGoal('Emergency Fund', 10000, {\r
  description: '6 months expenses',\r
  deadline: '2026-12-31',\r
  priority: 'high'\r
});\r
\r
// Add contribution\r
await clawhub.contributeToGoal('goal_abc123', 500, 'January savings');\r
\r
// Check progress\r
const progress = clawhub.getGoalProgress();\r
// Returns: [{ goalName, targetAmount, currentAmount, percentageComplete, daysRemaining, onTrack }]\r
```\r
\r
### Analytics & Reports\r
\r
```typescript\r
// Monthly spending summary\r
const summary = clawhub.getSpendingSummary();\r
// Returns: { totalExpenses, totalIncome, netSavings, expensesByCategory, incomeByCategory }\r
\r
// View monthly trends\r
const trends = clawhub.getMonthlyTrends(12);\r
// Returns: [{ date, expenses, income, netSavings }]\r
\r
// Full monthly report\r
const report = clawhub.generateMonthlyReport(2026, 1);\r
\r
// Compare to last month\r
const comparison = clawhub.compareToLastMonth();\r
// Returns: { expenseChange, incomeChange, topIncreases, topDecreases }\r
```\r
\r
### Smart Insights\r
\r
```typescript\r
// Generate AI-powered insights\r
const insights = await clawhub.generateInsights();\r
// Returns insights like:\r
// - "⚠️ Your dining expenses are 3x higher than usual"\r
// - "💡 Cancel unused subscriptions to save $50/month"\r
// - "🏆 You've tracked expenses for 7 consecutive days!"\r
\r
// Get unread insights\r
const unreadInsights = clawhub.getInsights();\r
```\r
\r
### Recurring Transactions\r
\r
```typescript\r
// Create recurring expense (e.g., Netflix subscription)\r
await clawhub.createRecurring(\r
  'expense', 15.99, 'Subscriptions', 'Netflix', 'monthly',\r
  { startDate: '2026-02-01' }\r
);\r
\r
// Create recurring income (e.g., salary)\r
await clawhub.createRecurring(\r
  'income', 5000, 'Salary', 'Monthly salary', 'monthly'\r
);\r
\r
// Process due recurring transactions\r
await clawhub.processRecurring();\r
```\r
\r
### Data Management\r
\r
```typescript\r
// Get statistics\r
const stats = clawhub.getStats();\r
// Returns: { totalTransactions, totalExpenses, totalIncome, netSavings, avgExpense, topCategory }\r
\r
// Get available categories\r
const categories = clawhub.getCategories();\r
\r
// Export data\r
const jsonData = await clawhub.exportData();\r
\r
// Create backup\r
const backupPath = await clawhub.backup();\r
\r
// Get storage location\r
const dataPath = clawhub.getDataPath();\r
```\r
\r
---\r
\r
## Default Categories\r
\r
### Expense Categories\r
| Category | Icon |\r
|----------|------|\r
| Food & Dining | 🍔 |\r
| Transportation | 🚗 |\r
| Shopping | 🛍️ |\r
| Bills & Utilities | 💡 |\r
| Entertainment | 🎬 |\r
| Health & Fitness | 💪 |\r
| Education | 📚 |\r
| Personal Care | 💄 |\r
| Subscriptions | 📱 |\r
\r
### Income Categories\r
| Category | Icon |\r
|----------|------|\r
| Salary | 💰 |\r
| Freelance | 💻 |\r
| Investments | 📈 |\r
| Gifts | 🎁 |\r
\r
---\r
\r
## Cross-Platform Storage\r
\r
Data is stored in platform-specific locations:\r
\r
| Platform | Default Path |\r
|----------|-------------|\r
| Windows | `%APPDATA%\clawhub` |\r
| macOS | `~/Library/Application Support/clawhub` |\r
| Linux | `~/.local/share/clawhub` |\r
\r
Override with environment variable:\r
```bash\r
export CLAWHUB_DATA_PATH=/custom/path\r
```\r
\r
---\r
\r
## API Reference Summary\r
\r
| Method | Description |\r
|--------|-------------|\r
| `initialize(path?)` | Initialize the budget tracker |\r
| `addExpense(amount, category, description, options?)` | Add expense |\r
| `addIncome(amount, category, description, options?)` | Add income |\r
| `addFromNaturalLanguage(text)` | Parse and add from natural language |\r
| `createBudget(name, category, limit, period, threshold?)` | Create budget |\r
| `getBudgetStatus()` | Get all budget statuses |\r
| `checkBudgetAlerts()` | Get budget warnings/alerts |\r
| `createGoal(name, target, options?)` | Create savings goal |\r
| `contributeToGoal(goalId, amount, note?)` | Add to goal |\r
| `getGoalProgress()` | Get all goal progress |\r
| `getSpendingSummary(start?, end?)` | Get spending breakdown |\r
| `getMonthlyTrends(months?)` | Get monthly trend data |\r
| `generateMonthlyReport(year?, month?)` | Generate full report |\r
| `generateInsights()` | Generate AI insights |\r
| `createRecurring(type, amount, category, desc, freq, options?)` | Create recurring |\r
| `processRecurring()` | Process due recurring transactions |\r
| `getStats()` | Get transaction statistics |\r
| `exportData()` | Export all data as JSON |\r
| `backup()` | Create timestamped backup |\r