AgentLedger - AI Agent Expense Tracking

---

name: agentledger

description: Expense tracking and accounting for AI agents. Log purchases, set budgets, generate spending reports, and manage multi-currency finances — all stored locally. Privacy.com card import, natural language queries, CSV/JSON export. Use when agents make purchases and need a financial audit trail.

metadata: {"openclaw": {"requires": {"bins": ["node"]}}}

---

# 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:

// 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):

# 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

// 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

// 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

// 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:

Account Integration

Privacy.com Cards

The ledger automatically detects Privacy.com card data if available:

// If you have Privacy.com JSON exports in workspace/privacy/
await ledger.importPrivacyTransactions('./privacy/card-1.json');

Manual Account Setup

// 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:

The CLI handles these queries:

node src/cli.js query "API spending this month"
node src/cli.js find "OpenAI" --last-week

Time Periods

Supported natural language time periods:

Data Export

// 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

# 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

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

Data Safety

Example Error Recovery

# 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