free-agents

Agent Smith

An intelligent financial management skill for Claude Code

Agent Smith provides comprehensive PocketSmith API integration with advanced AI-powered analysis, rule management, tax intelligence, and scenario planning.

Project Status

✅ Implementation Complete - All 8 phases implemented and tested

📦 Version: 1.3.8

📋 Design Document: docs/design/2025-11-20-agent-smith-design.md

👥 Contributing: CONTRIBUTING.md

Distribution

Agent Smith is distributed as a Claude Code plugin/skill via the marketplace system:

• Plugin Configuration: .claude-plugin/marketplace.json and .claude-plugin/plugin.json
• Skill Source: agent-smith-plugin/skills/agent-smith/ - Complete skill definition
• Installation: Users install via Claude Code marketplace or plugin commands

The skill includes all Python scripts, documentation, rule templates, and configuration files needed to run Agent Smith within Claude Code.

For Contributors

Development Setup: See CONTRIBUTING.md for complete development setup instructions.

Key Points:

• Main source code is in scripts/ directory
• Skill source is in agent-smith-plugin/skills/agent-smith/
• Scripts are synced from scripts/ to skill location (gitignored copy)
• Use marketplace.json/plugin.json for distribution (not packaged .skill files)

What is Agent Smith?

Agent Smith transforms PocketSmith from a passive tracking tool into an active financial intelligence system. Named after the Matrix AI agent, it serves as your intelligent assistant for managing your financial matrix.

Key Features

• Hybrid Rule Engine - Platform-native + enhanced local rules with performance tracking
• 3-Tier Tax Intelligence - Reference, Smart, and Full compliance modes (Australian ATO)
• Scenario Analysis - Historical analysis, projections, optimization, tax planning
• Multi-Format Reports - Markdown, CSV/JSON, HTML dashboards, Excel
• Smart Orchestration - Context-preserving subagent architecture
• Proactive Insights - Automated alerts, optimization recommendations
• Health Checks - Comprehensive PocketSmith setup evaluation

Repository Structure

agent-smith/
├── README.md                    # This file
├── CONTRIBUTING.md              # Development setup and contribution guide
├── CHANGELOG.md                 # Version history
├── .gitignore                   # Git ignore rules
├── .env                         # API configuration (not committed)
├── pyproject.toml               # Python dependencies (uv)
├── uv.lock                      # Dependency lock file
├── pytest.ini                   # Test configuration
│
├── .claude-plugin/              # Claude Code plugin configuration
│   ├── marketplace.json         # Marketplace metadata
│   └── plugin.json              # Plugin definition
│
├── agent-smith-plugin/          # Marketplace distribution
│   ├── .claude-plugin/          # Plugin configuration
│   │   └── plugin.json          # Plugin definition
│   ├── commands/                # Slash command definitions
│   └── skills/agent-smith/      # Skill source
│       ├── SKILL.md             # Skill definition
│       ├── README.md            # Skill documentation
│       ├── scripts/             # Python code (synced from ../../../scripts/)
│       ├── references/          # Documentation (loaded on-demand)
│       ├── assets/              # Templates and seed data
│       └── .env.sample          # Configuration template
│
├── backups/                     # Timestamped backups (30-day retention)
│   └── INDEX.md
│
├── data/                        # Working data and state
│   ├── INDEX.md
│   ├── config.json              # User preferences
│   └── templates/               # Rule templates
│
├── docs/                        # Documentation
│   ├── INDEX.md
│   ├── design/                  # Design specifications
│   ├── guides/                  # User guides
│   └── operations/              # Operation logs
│
├── ai_docs/                     # AI agent documentation
│   ├── INDEX.md
│   └── pocketsmith-api-documentation.md
│
├── logs/                        # Execution logs (14-day retention)
│   └── INDEX.md
│
├── reports/                     # Generated reports (90-day retention)
│   └── INDEX.md
│
├── scripts/                     # Python code (source)
│   ├── INDEX.md
│   ├── core/                    # Core libraries
│   │   ├── api_client.py        # PocketSmith API wrapper ✓
│   │   ├── rule_engine.py       # Hybrid rule engine ✓
│   │   └── index_updater.py     # INDEX.md manager ✓
│   ├── analysis/                # Analysis modules
│   │   ├── spending.py          # Spending analysis ✓
│   │   └── trends.py            # Trend detection ✓
│   ├── reporting/               # Reporting modules
│   │   └── formatters.py        # Multi-format reports ✓