Agent Smith

3. Transaction Categorization

• Batch Processing: Categorize uncategorized transactions with AI assistance
• Merchant Intelligence: Automatic payee normalization and variation detection
• AI Fallback: LLM-powered categorization when rules don't match
• Dry-Run Mode: Preview categorization before applying

4. Financial Analysis & Reporting

• Spending Analysis: By category, merchant, time period
• Trend Detection: Increasing/decreasing categories, anomaly detection
• Multi-Format Reports: Markdown, CSV/JSON, HTML dashboards, Excel
• Comparative Analysis: YoY, QoQ, MoM comparisons

5. Scenario Analysis

• Historical: What-if replays ("What if I cut dining by 30% last year?")
• Projections: Spending forecasts, affordability analysis, goal modeling
• Optimization: Subscription analysis, expense rationalization, tax optimization
• Tax Planning: Purchase timing, income deferral, CGT scenarios

6. Health Check System

• 6 Health Dimensions: Data Quality, Category Structure, Rule Engine, Tax Readiness, Automation, Budget Alignment
• Automated Monitoring: Weekly checks, EOFY prep, post-operation validation
• Prioritized Recommendations: Top 3 highest-impact improvements

7. Advanced Features

• Smart Alerts: Budget overruns, tax thresholds, pattern detection
• Document Tracking: Receipt requirements ($300 ATO threshold)
• Multi-User: Shared expense tracking and settlement
• Audit Trail: Complete activity log with undo capability

Quick Start

First-Time Setup

1. Prerequisites:

   • PocketSmith account with API access
   • Developer API key from PocketSmith (Settings > Security)
   • Python 3.9+ with uv package manager

2. Configuration:

   • Copy .env.sample to .env
   • Add POCKETSMITH_API_KEY=<your_key>
   • Set TAX_INTELLIGENCE_LEVEL=smart (reference|smart|full)
   • Set DEFAULT_INTELLIGENCE_MODE=smart (conservative|smart|aggressive)

3. Installation:

   # From the skill directory
   uv sync
   

4. Guided Onboarding:

   # Launch integrated onboarding (8 stages)
   /agent-smith:install
   

The onboarding process will:

• Discover your PocketSmith account structure
• Recommend and apply a rule template
• Help customize rules for your needs
• Configure intelligence modes
• Incrementally categorize transactions
• Show measurable improvement with health scores
• Provide ongoing usage guidance
• Generate intelligent suggestions

Time required: 30-60 minutes for first-time setup

Daily Usage

Two Usage Modes:

1. Guided Journey Mode - When you start Claude Code, Agent Smith displays a status dashboard with:

   • Your health score
   • Uncategorized transaction count
   • Conflicts awaiting review
   • Suggested next steps with both natural language and command options

2. Power User Mode - Use slash commands directly for specific operations.

Slash Commands (7 specialized commands):

• /smith:install - Installation and onboarding wizard
• /smith:categorize [--mode] [--period] - Transaction categorization
• /smith:review-conflicts - Review transactions flagged for review
• /smith:health [--full|--quick] - Health check and recommendations
• /smith:insights <spending|trends|scenario|report> - Financial analysis and reports
• /smith:tax <deductions|cgt|bas|eofy> - Tax intelligence (ATO)
• /smith:schedule [--setup|--status|--remove] - Automated categorization scheduling

Python Scripts

All Python scripts are in scripts/ directory. Always run with uv run python -u for proper dependency resolution and unbuffered output.

Core Operations

# Categorize transactions
uv run python -u scripts/operations/batch_categorize.py --mode=smart --period=2025-11

# Run health check
uv run python -u scripts/health/check.py --full

# Generate spending report
uv run python -u scripts/reporting/generate.py --period=2025 --format=all

# Tax deduction analysis
uv run python -u scripts/tax/deduction_detector.py --period=2024-25

Script Organization

• scripts/core/ - API client, rule engine, unified rules
• scripts/operations/ - Categorization, batch processing, transaction updates
• scripts/analysis/ - Spending analysis, trend detection
• scripts/reporting/ - Multi-format report generation
• scripts/tax/ - ATO mappings, deductions, CGT, BAS preparation
• scripts/scenarios/ - Historical, projections, optimization, tax scenarios
• scripts/status/ - Status dashboard for SessionStart hook
• scripts/scheduled/ - Automated scheduled tasks (cron/launchd)
• scripts/health/ - Health check engine, recommendations, monitoring
• scripts/workflows/ - Interactive categorization workflows
• scripts/utils/ - Backup, validation, logging, merchant normalization

Unified Rule System

Agent Smith uses a YAML-based unified rule system for transaction categorization and labeling.

Quick Start with Rules

# 1. Choose a template for your household type
uv run python scripts/setup/template_selector.py

# 2. Customize rules in data/rules.yaml

# 3. Test with dry run
uv run python scripts/operations/batch_categorize.py --mode=dry_run --period=2025-11

# 4. Apply to transactions
uv run python scripts/operations/batch_categorize.py --mode=apply --period=2025-11

Example Rule