--- name: agentledger-a86dd0f5da64 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: ```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 --- Source attribution: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/c-goro/agentledger/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 clawdbot Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/c-goro/agentledger/SKILL.md Attribution basis: Source repository record Fields of work: Finance & Accounting, Sales Roles: Accountant, Business Development, CFO / FP&A, Customer Success Manager, Financial Analyst Specialties: API, Database Tools: Csv, Json, Privacy.Com Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 7f35af84c612656ce06680d6ad1429f26b2dcda46e1963028ad2ba75e062101c