agentledger

# 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
```ja...

# AgentLedger

**AI Agent Expense Tracking & Accounting for OpenClaw**

AgentLedger is a comprehensive expense tracking skill that helps AI agents maintain detailed financial records of purchases and spending. Perfect for tracking API costs, subscription services, infrastructure expenses, and any other purchases made by AI agents.

## 🌟 Features

### Core Functionality
- **Transaction Logging** - Log every purchase with amount, vendor, description, category, and context
- **Multi-Currency Support** - Track spending in different currencies
- **Account Management** - Manage multiple payment methods and cards
- **Budget Tracking** - Set spending limits and get alerts when approaching them
- **Natural Language Queries** - Ask questions like "How much did I spend on API keys this month?"
- **Detailed Reports** - Generate monthly, category, vendor, and trend reports
- **Data Export** - Export transactions to CSV or JSON formats
- **Receipt Storage** - Store receipt URLs and confirmation numbers

### Categories
Pre-defined spending categories for consistent tracking:
- **API/Services** - API credits, SaaS subscriptions
- **Infrastructure** - Hosting, domains, CDN
- **Marketing** - Advertising, social media tools  
- **Tools** - Software licenses, utilities
- **Subscriptions** - Recurring services
- **Other** - Miscellaneous expenses

### Smart Features
- **Privacy.com Integration** - Import transactions from Privacy card exports
- **Budget Alerts** - Automatic warnings when approaching spending limits
- **Trend Analysis** - Track spending patterns over time
- **Vendor Analysis** - See spending patterns by vendor
- **Time Period Filtering** - Support for natural language time periods

## 🚀 Quick Start

### Installation
```bash
# Clone or copy the skill to your workspace
cp -r agentledger /home/claw/.openclaw/workspace/

# Initialize the ledger
cd /home/claw/.openclaw/workspace/agentledger
node src/cli.js init
```

### Basic Usage

#### Log a Transaction
```bash
# Command...