75 tools across 7 extensions for banking, investing, tax optimization, market intelligence, social sentiment, and financial analysis — built for the Agent Skills Protocol.
Connect your bank accounts • Monitor your portfolio • Trade stocks • Optimize taxes • Track market intel • Detect anomalies
All through natural language, with deterministic calculations, policy guardrails, and approval gates.
Install • Architecture • Tools • Workflows • Docs
Most AI finance tools hallucinate numbers. This one doesn't.
- Deterministic math — Tax liability, P/L, net worth always computed by tools, never by LLM arithmetic
- Policy engine — Every trade, transfer, and tax move passes
finance_policy_checkbefore execution - Multi-provider — Plaid (banking) + Alpaca (trading) + IBKR (portfolio) + IRS tax forms + Finnhub/SEC/FRED/BLS (market data) + StockTwits/X (sentiment) in one unified model
- Approval gates — No live trades without explicit human confirmation, ever
- Canonical data model — All providers normalize into shared types (Account, Transaction, Position, Liability)
- Works with 40+ AI agents — Claude Code, Cursor, Codex, OpenClaw, Windsurf, and more via the Agent Skills Protocol
npx skills add <owner>/personal-finance-skillOr install for specific agents:
npx skills add <owner>/personal-finance-skill -a claude-code -a cursor -a codex+---------------------------------------------------+
| Intelligence Layer |
| tax-engine (23) market-intel (10) |
| social-sentiment (6) |
+---------------------------------------------------+
| Data Source Adapters |
| plaid-connect (8) | alpaca-trading (10) |
| ibkr-portfolio (9) | |
+---------------------------------------------------+
| Foundation Layer |
| finance-core (9 tools) |
| Canonical models, storage, normalization, |
| policy checks, anomaly detection, briefs |
+---------------------------------------------------+
Data flow: Adapters fetch provider data → finance-core normalizes & stores → intelligence layer analyzes → policy engine gates actions.
| Extension | Tools | What It Does |
|---|---|---|
| finance-core | 9 | Canonical data models, snapshot storage, normalization, policy engine, anomaly detection, financial briefs |
| plaid-connect | 8 | Plaid Link flow, bank accounts, transactions, investments, liabilities, recurring charges, webhooks |
| alpaca-trading | 10 | Brokerage account, positions, orders, market data, trading with safety limits |
| ibkr-portfolio | 9 | IBKR Client Portal, portfolio allocation, performance, market snapshots, session management |
| tax-engine | 23 | 15 form parsers (1040, Schedules A-E/SE, 8949, 6251, W-2, 1099-B/DIV/INT, K-1, state returns) + 8 calculators (liability, TLH, wash sales, lots, quarterly, Schedule D, state tax, AMT) |
| market-intel | 10 | Company news, SEC filings, economic data (FRED, BLS), analyst recommendations, news sentiment via Finnhub, SEC EDGAR, FRED, BLS, Alpha Vantage |
| social-sentiment | 6 | Social media sentiment via StockTwits, X/Twitter, congressional trading via Quiver Quantitative |
| Tool | Description | Risk |
|---|---|---|
finance_upsert_snapshot |
Store normalized financial data snapshot (idempotent) | LOW |
finance_get_state |
Get current financial state (accounts, positions, etc.) | READ |
finance_get_transactions |
Query transactions with filters and pagination | READ |
finance_get_net_worth |
Calculate net worth breakdown by category/account | READ |
finance_detect_anomalies |
Scan for unusual transactions, balance drops, fee spikes | READ |
finance_cash_flow_summary |
Income vs expenses by category with savings rate | READ |
finance_subscription_tracker |
Identify recurring charges and subscription patterns | READ |
finance_generate_brief |
Create structured financial summary with action items | READ |
finance_policy_check |
Validate proposed action against policy rules | READ |
| Tool | Description | Risk |
|---|---|---|
plaid_create_link_token |
Initialize Plaid Link for account connection | LOW |
plaid_exchange_token |
Exchange public token for permanent access | MED |
plaid_get_accounts |
List connected accounts with balances | READ |
plaid_get_transactions |
Fetch transactions via cursor-based sync | READ |
plaid_get_investments |
Fetch holdings, securities, investment transactions | READ |
plaid_get_liabilities |
Fetch credit, student loan, and mortgage data | READ |
plaid_get_recurring |
Identify recurring inflow/outflow streams | READ |
plaid_webhook_handler |
Process incoming Plaid webhook events | LOW |
| Tool | Description | Risk |
|---|---|---|
alpaca_get_account |
Get account balances, buying power, status | READ |
alpaca_list_positions |
List all open positions | READ |
alpaca_get_position |
Get single position by symbol | READ |
alpaca_list_orders |
List orders with status/date filters | READ |
alpaca_create_order |
Submit buy/sell order with safety checks | HIGH |
alpaca_cancel_order |
Cancel a pending order | MED |
alpaca_portfolio_history |
Historical equity and P/L over time | READ |
alpaca_get_assets |
Search tradable assets by class/exchange | READ |
alpaca_market_data |
Get snapshots, bars, or quotes for symbols | READ |
alpaca_clock |
Check if market is open, next open/close | READ |
| Tool | Description | Risk |
|---|---|---|
ibkr_auth_status |
Check gateway authentication status | READ |
ibkr_tickle |
Keep gateway session alive (~1 min interval) | LOW |
ibkr_list_accounts |
List accounts (must call first) | READ |
ibkr_get_positions |
Get positions for an account (paginated) | READ |
ibkr_portfolio_allocation |
Allocation by asset class, sector, group | READ |
ibkr_portfolio_performance |
NAV time series and returns | READ |
ibkr_search_contracts |
Search contracts by symbol/name/type | READ |
ibkr_market_snapshot |
Real-time market data for contracts | READ |
ibkr_get_orders |
Get current live orders | READ |
| Tool | Description | Risk |
|---|---|---|
tax_parse_1099b |
Parse 1099-B (proceeds, cost basis, wash sales) | READ |
tax_parse_1099div |
Parse 1099-DIV (dividends, capital gains) | READ |
tax_parse_1099int |
Parse 1099-INT (interest, bond premiums) | READ |
tax_parse_w2 |
Parse W-2 (wages, withholding, SS/Medicare) | READ |
tax_parse_k1 |
Parse Schedule K-1 (partnership pass-through) | READ |
tax_parse_1040 |
Parse Form 1040 (main individual return) | READ |
tax_parse_schedule_a |
Parse Schedule A (itemized deductions, SALT cap) | READ |
tax_parse_schedule_b |
Parse Schedule B (interest/dividends, foreign accounts) | READ |
tax_parse_schedule_c |
Parse Schedule C (self-employment, 23 expense categories) | READ |
tax_parse_schedule_d |
Parse Schedule D (capital gains netting) | READ |
tax_parse_schedule_e |
Parse Schedule E (rental/partnership income) | READ |
tax_parse_schedule_se |
Parse Schedule SE (self-employment tax) | READ |
tax_parse_form_8949 |
Parse Form 8949 (capital asset dispositions) | READ |
tax_parse_state_return |
Parse generic state income tax return | READ |
tax_parse_form_6251 |
Parse Form 6251 (AMT) | READ |
tax_estimate_liability |
Calculate federal/state tax with brackets | READ |
tax_find_tlh_candidates |
Identify tax-loss harvesting opportunities | READ |
tax_check_wash_sales |
Validate wash sale rule compliance (61-day window) | READ |
tax_lot_selection |
Compare FIFO/LIFO/specific ID for a proposed sale | READ |
tax_quarterly_estimate |
Quarterly estimated payments with safe harbor | READ |
tax_compute_schedule_d |
Schedule D computation with $3K loss cap and carryover | READ |
tax_compute_state_tax |
State income tax (8 states: CA, NY, NJ, IL, PA, MA, TX, FL) | READ |
tax_compute_amt |
Alternative Minimum Tax with 2025 parameters | READ |
| Tool | Description | Risk |
|---|---|---|
intel_company_news |
Company-specific news articles by ticker (Finnhub) | READ |
intel_market_news |
General/forex/crypto/merger market news (Finnhub) | READ |
intel_stock_fundamentals |
Financial statements, annual/quarterly (Finnhub) | READ |
intel_analyst_recommendations |
Analyst buy/hold/sell recommendations (Finnhub) | READ |
intel_sec_filings |
SEC filing history by company CIK (SEC EDGAR) | READ |
intel_sec_search |
Full-text search of SEC filings (SEC EDGAR) | READ |
intel_fred_series |
Economic data series observations (FRED) | READ |
intel_fred_search |
Search for economic data series (FRED) | READ |
intel_bls_data |
Bureau of Labor Statistics time series (BLS) | READ |
intel_news_sentiment |
News sentiment analysis by ticker/topic (Alpha Vantage) | READ |
| Tool | Description | Risk |
|---|---|---|
social_stocktwits_sentiment |
Sentiment aggregation (bullish/bearish) for a ticker | READ |
social_stocktwits_trending |
Trending symbols on StockTwits | READ |
social_x_search |
Search recent tweets with financial query | READ |
social_x_user_timeline |
Fetch a user's recent tweets | READ |
social_x_cashtag |
Cashtag search ($AAPL) with basic sentiment | READ |
social_quiver_congress |
Congressional stock trading activity (Quiver Quantitative) | READ |
plaid_create_link_token(products: ["transactions", "investments", "liabilities"])
-> User completes Plaid Link
-> plaid_exchange_token(publicToken)
-> plaid_get_accounts -> finance_upsert_snapshot(source: "plaid")
-> plaid_get_transactions -> finance_upsert_snapshot
-> plaid_get_investments -> finance_upsert_snapshot
-> finance_get_net_worth -> present baseline to user
plaid_get_transactions(cursor) -> finance_upsert_snapshot
alpaca_list_positions -> finance_upsert_snapshot(source: "alpaca")
ibkr_auth_status -> ibkr_get_positions -> finance_upsert_snapshot(source: "ibkr")
-> finance_detect_anomalies(lookbackDays: 7)
-> Alert on medium/high severity findings
finance_get_state(include: ["positions"])
-> tax_find_tlh_candidates(positions, marginalRate)
-> tax_check_wash_sales(proposedSales, recentPurchases)
-> tax_lot_selection(symbol, qty, lots)
-> finance_policy_check(actionType: "tax_move")
-> [If approved] alpaca_create_order(side: "sell", ...)
tax_parse_w2 + tax_parse_1099b + tax_parse_1099div + tax_parse_1099int
+ tax_parse_1040 + tax_parse_schedule_c + tax_parse_schedule_se
-> tax_estimate_liability(filingStatus, income)
-> tax_compute_state_tax(stateCode, taxableIncome, filingStatus)
-> tax_compute_amt(amtInput) [if ISO/high-income]
-> tax_quarterly_estimate(projectedIncome, priorYearTax, paymentsMade)
-> finance_generate_brief(period: "quarterly")
alpaca_list_positions + ibkr_get_positions
-> finance_upsert_snapshot (both sources)
-> ibkr_portfolio_allocation (check drift)
-> alpaca_portfolio_history (performance trend)
-> finance_detect_anomalies
-> finance_generate_brief(period: "weekly")
- Node.js 18+ and npm
- TypeScript 5+
- API credentials for at least one provider (see below)
The onboard script builds all extensions, registers them as OpenClaw plugins, and installs the skill:
git clone https://github.com/6missedcalls/personal-finance-skill.git
cd personal-finance-skill
# Build, symlink plugins, and install skill in one command
./scripts/onboard.shThe script will:
- Install deps and build all 7 extensions
- Register each as an OpenClaw plugin (dev-linked via
openclaw plugins install -l) - Symlink the skill into
~/.openclaw/skills/ - Verify everything is reachable
Options:
--copyto copy instead of symlink,--uninstallto remove everything.
Set credentials for the providers you plan to use (you don't need all of them):
# Plaid — https://dashboard.plaid.com
export PLAID_CLIENT_ID="your-client-id"
export PLAID_SECRET="your-secret"
export PLAID_ENV="sandbox" # sandbox | development | production
# Alpaca — https://app.alpaca.markets
export ALPACA_API_KEY="your-key"
export ALPACA_API_SECRET="your-secret"
export ALPACA_ENV="paper" # paper | live
# IBKR — https://www.interactivebrokers.com
export IBKR_BASE_URL="https://localhost:5000/v1/api"
# Market Intelligence
export FINNHUB_API_KEY="your-key" # https://finnhub.io
export FRED_API_KEY="your-key" # https://fred.stlouisfed.org
export BLS_API_KEY="your-key" # https://data.bls.gov
export ALPHA_VANTAGE_API_KEY="your-key" # https://www.alphavantage.co
# Social Sentiment
export X_API_BEARER_TOKEN="your-token" # https://developer.x.com
export QUIVER_API_KEY="your-key" # https://www.quiverquant.comopenclaw gateway restart
openclaw plugins list # should show all 7 extensionsfor ext in extensions/*/; do
echo "Testing $ext..."
(cd "$ext" && npm test)
done612 tests across 55+ test files, all passing.
personal-finance-skill/
SKILL.md # Agent Skills Protocol entry point
README.md # This file
LICENSE # MIT
scripts/
onboard.sh # Build + register + verify (one command)
extensions/
finance-core/ # Foundation: models, storage, policy
plaid-connect/ # Adapter: Plaid banking API
alpaca-trading/ # Adapter: Alpaca brokerage API
ibkr-portfolio/ # Adapter: IBKR Client Portal API
tax-engine/ # Intelligence: tax parsing + strategy (23 tools)
market-intel/ # Intelligence: news, filings, economic data (10 tools)
social-sentiment/ # Intelligence: social sentiment (6 tools)
references/
ext-finance-core.md # 9 tool schemas + storage layer
ext-plaid-connect.md # 8 tool schemas + Link flow
ext-alpaca-trading.md # 10 tool schemas + order lifecycle
ext-ibkr-portfolio.md # 9 tool schemas + session mgmt
ext-tax-engine.md # 23 tool schemas + calculators
ext-market-intel.md # 10 tool schemas (Finnhub, SEC, FRED, BLS, Alpha Vantage)
ext-social-sentiment.md # 6 tool schemas (StockTwits, X, Quiver)
data-models-and-schemas.md # Canonical types + enums
risk-and-policy-guardrails.md # Policy engine + approval tiers
api-plaid.md # Plaid API reference
api-alpaca-trading.md # Alpaca API reference
api-ibkr-client-portal.md # IBKR API reference
api-openclaw-framework.md # OpenClaw architecture
api-openclaw-extension-patterns.md # Extension patterns
api-irs-tax-forms.md # IRS form schemas
Set up recurring scans with your agent runtime:
Weekly Financial Brief — Mondays at 8 AM PT
openclaw cron add \
--name "Finance Weekly Brief" \
--cron "0 8 * * 1" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Sync all providers, compute net worth delta, top spend changes, upcoming bills, tax posture, portfolio drift. Send concise brief with action queue."Daily Anomaly Scan — Every day at 7:15 AM PT
openclaw cron add \
--name "Finance Daily Anomaly" \
--cron "15 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Sync latest transactions, run finance_detect_anomalies. Alert on medium/high/critical findings only."Quarterly Tax Check — Jan, Apr, Jun, Sep 1st at 9 AM PT
openclaw cron add \
--name "Quarterly Tax Review" \
--cron "0 9 1 1,4,6,9 *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Estimate liability, check withholding gap, find TLH opportunities, assess quarterly payment risk."Portfolio Drift Monitor — Every 30 min during market hours
openclaw cron add \
--name "Portfolio Drift Monitor" \
--cron "*/30 13-21 * * 1-5" \
--tz "America/New_York" \
--session isolated \
--message "Check portfolio allocation vs target bands. Alert if drift exceeds threshold for 2 consecutive scans."These rules are enforced for all AI agents using this skill:
| # | Rule |
|---|---|
| 1 | Always run finance_policy_check before any trade, transfer, or tax move |
| 2 | Never bypass approval requirements — halt and request confirmation |
| 3 | Deterministic math only — never use LLM arithmetic for money |
| 4 | State data freshness — every recommendation includes when data was last synced |
| 5 | Never expose credentials — no API keys or tokens in outputs |
| 6 | No auto-execution — live trades always require explicit human confirmation |
| 7 | Include disclaimers — investment outputs state "not financial advice" |
| 8 | Flag stale data — warn before advising on outdated information |
| Concept | Description |
|---|---|
| Canonical Models | All provider data normalizes into shared types: Account, Transaction, Position, Liability |
| Snapshot Storage | Append-only, content-hashed, idempotent storage with point-in-time queries |
| Policy Engine | Configurable rules with approval tiers (none / user / advisor) gate all side effects |
| Deterministic Calculators | Tax, P/L, net worth computed by tools — zero LLM math |
| Progressive Disclosure | SKILL.md has the overview, references/ has full schemas, api-*.md has upstream docs |
| Audience | Start Here |
|---|---|
| AI agents | SKILL.md — tool catalog, workflows, guardrails |
| Developers | CLAUDE.md — build instructions, architecture, rules |
| Tool schemas | references/ext-*.md — full input/output schemas per extension |
| Data models | references/data-models-and-schemas.md |
| Policy rules | references/risk-and-policy-guardrails.md |
This skill follows the Agent Skills Protocol and works with 40+ AI coding agents including:
Claude Code • Cursor • Codex • OpenClaw • Windsurf • Cline • Roo Code • Goose • Continue • Kilo • Amp • and more
Contributions are welcome! Please:
- Fork the repo
- Create a feature branch (
git checkout -b feat/my-feature) - Write tests first (TDD)
- Ensure all 612 tests pass
- Submit a PR
See CLAUDE.md for coding conventions and architecture guidelines.
This software is for informational and educational purposes only. It is not financial advice. Always consult a qualified financial advisor before making investment or tax decisions. The authors assume no liability for financial losses incurred through the use of this software.