Introduction
# AgentLedger - AI Agent Expense Tracking
## Overview AgentLedger is an accounting skill that logs every transaction you make, tracks spending across multiple accounts, and provides detailed reports. Use this to maintain a complete financial record of your purchases.
**Important**: Always log transactions immediately after making purchases. This skill is designed for AI agents to track their own expenses (API costs, tool subscriptions, etc.).
## Core Functions
### 1. Log a Transaction When you make any purchase, immediately log it:
```javascript // In Node.js context, require the ledger const AgentLedger = require('./src/ledger.js'); const ledger = new AgentLedger();
// Log a transaction await ledger.logTransaction({ amount: 29.99, currency: 'USD', vendor: 'OpenAI', description: 'GPT-4 API credits', category: 'API/Services', account: 'privacy-card-1', context: 'Needed additional tokens for user project analysis', receiptUrl: 'https://platform.openai.com/receipts/xyz', confirmationId: 'sub_1234567890' }); ```
**CLI Usage** (supports both positional and named parameters): ```bash # Positional style node src/cli.js log 29.99 "OpenAI" "GPT-4 API credits" --category="API/Services"
# Named parameter style node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="GPT-4 API credits" --category="API/Services" --context="Monthly API refill" ```
### 2. Check Current Spending ```javascript // Get spending summary const summary = await ledger.getSummary('this-month'); console.log(`Total spent this month: $${summary.total}`);
// Check specific category const apiSpending = await ledger.getCategorySpending('API/Services', 'this-month'); ```
### 3. Generate Reports ```javascript // Monthly report const report = await ledger.generateReport('monthly', { month: '2024-01' });
// Custom date range const customReport = await ledger.generateReport('custom', { startDate: '2024-01-01', endDate: '2024-01-31' }); ```
### 4. Budget Management ```javascript // Set monthly budget for API services await ledger.setBudget('API/Services', 500, 'monthly');
// Check budget status const budgetStatus = await ledger.checkBudget('API/Services'); if (budgetStatus.isNearLimit) { console.log(`Warning: ${budgetStatus.percentUsed}% of API budget used`); } ```
## Categories Use these predefined categories for consistent tracking: - **API/Services** - API credits, SaaS subscriptions - **Infrastructure** - Hosting, domains, CDN - **Marketing** - Ads, social media tools - **Tools** - Software licenses, utilities - **Subscriptions** - Recurring monthly/yearly services - **Other** - Miscellaneous expenses
## Account Integration
### Privacy.com Cards The ledger automatically detects Privacy.com card data if available: ```javascript // If you have Privacy.com JSON exports in workspace/privacy/ await ledger.importPrivacyTransactions('./privacy/card-1.json'); ```
### Manual Account Setup ```javascript // Register a new payment method await ledger.addAccount({ id: 'stripe-main', name: 'Main Stripe Account', type: 'credit_card', currency: 'USD' }); ```
## Natural Language Queries
Ask questions like: - "How much did I spend on API keys this month?" - "What was that $20 charge from yesterday?" - "Show me all infrastructure costs from last quarter" - "Am I over budget on marketing spend?"
The CLI handles these queries: ```bash node src/cli.js query "API spending this month" node src/cli.js find "OpenAI" --last-week ```
## Time Periods Supported natural language time periods: - `today`, `yesterday` - `this-week`, `last-week` - `this-month`, `last-month` - `this-quarter`, `last-quarter` - `this-year`, `last-year` - `last-30-days`, `last-90-days`
## Data Export ```javascript // Export to CSV await ledger.exportTransactions('csv', './exports/transactions.csv');
// Export to JSON await ledger.exportTransactions('json', './exports/transactions.json'); ```
## CLI Quick Reference
### Essential Commands for AI Agents
```bash # Initialize (run once) node src/cli.js init
# Log transactions (supports both styles) node src/cli.js log 29.99 "OpenAI" "API credits" --category="API/Services" node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="API credits" --category="API/Services"
# Check current spending node src/cli.js summary # This month node src/cli.js summary --period="today" # Today only node src/cli.js summary --period="this-week" # This week
# Set and check budgets node src/cli.js budget set "API/Services" 500 # Set monthly budget node src/cli.js budget status # Check all budgets
# Generate detailed reports node src/cli.js report monthly node src/cli.js report --type=category node src/cli.js report --type=vendor
# Search transactions node src/cli.js find "OpenAI" # Search by vendor node src/cli.js find "API" --category="API/Services" # Search by category node src/cli.js find --min-amount=50 # Find large expenses
# Export data node src/cli.js export csv # Export to CSV node src/cli.js export --format=json # Export to JSON
# Natural language queries node src/cli.js query "How much did I spend on APIs this month?" node src/cli.js query "What was that $25 charge?"
# Import from Privacy.com node src/cli.js import privacy ./privacy-export.json ```
## File Storage - Transactions: `workspace/ledger/transactions.json` - Accounts: `workspace/ledger/accounts.json` - Budgets: `workspace/ledger/budgets.json` - Settings: `workspace/ledger/settings.json`
## Best Practices 1. **Log immediately** - Don't wait, log every purchase as it happens 2. **Add context** - Explain why the purchase was necessary 3. **Use consistent categories** - Stick to the predefined categories 4. **Include receipts** - Store confirmation numbers and receipt URLs 5. **Set budgets** - Establish spending limits for each category 6. **Review regularly** - Generate monthly reports to track spending patterns
## Error Handling & Edge Cases
The ledger handles common errors gracefully:
### Input Validation - **Negative amounts**: Rejected (use positive amounts only) - **Missing required fields**: Clear error messages with usage examples - **Invalid currency**: Accepted (no validation - assumes user knows what they're doing) - **Very long descriptions**: Handled without truncation
### Data Safety - **Automatic backups**: Created before each save operation - **Corrupted data recovery**: Automatic recovery from `.backup` files - **Empty periods**: Gracefully shows $0.00 totals - **Multi-currency**: Properly separated in summaries and reports
### Example Error Recovery ```bash # If you see "Could not load transactions" message: # The system automatically tries to recover from backup # Your data should be restored automatically
# Manual backup check ls workspace/ledger/*.backup # Check if backups exist ```
## Security & Privacy - **Local storage only**: All data stays in `workspace/ledger/` JSON files - **No external API calls**: Core functionality works offline - **No sensitive data**: Never store actual card numbers or passwords - **Account aliases**: Use descriptive IDs like `privacy-card-1` or `company-amex` - **Receipt URLs**: Store links to receipts, not receipt content itself