FinDash

A Claude Code plugin for turning personal finance documents into an accurate SQLite-backed dashboard.

FinDash is a Claude Code plugin (findash) bundling a set of skills plus a small deterministic toolchain:

• Skills reason over messy real-world records — bank statements, payslips, brokerage screenshots, deposits, transfers, card charges.
• Scripts do the mechanics — parse files, update SQLite, fetch prices, render HTML, send to Telegram.

The core loop: drop source documents in a Google Drive vault → ask Claude to sync them into SQLite → render a self-contained dashboard. Telegram delivery and automatic bank/card fetch are both optional; the dashboard is always written locally as HTML.

[!NOTE] Built for Israel. FinDash ships tuned for Israeli personal finance: automatic fetch covers Bank Hapoalim and Cal (via israeli-bank-scrapers), money reports in ₪ (ILS), the dashboard applies the 25% Israeli capital-gains tax to securities profit, and the schema models Israeli payslips (income tax, Bituach Leumi) and retirement vehicles (pension + training fund / קרן השתלמות). Dates parse as DD/MM and Hebrew/RTL text is handled throughout. Many docs, prompts, and examples assume this locale.

Living elsewhere? Nothing is locked in — fork it and swap the locale-specific pieces. See Adapting to another country.

What It Does

How It Works

   +----------------------+          +----------------------+
   | Google Drive vault   |          | fetch-bank-data      |
   | dump/ (human drops:  |          | Hapoalim + Cal via   |
   | statements/PDF/XLSX) |          | israeli-bank-scrapers|
   +----------+-----------+          +----------+-----------+
              | best-effort pull                | local write
              v                                 v
   +---------------------------------------------------------+
   |            inbox/staging/  (local handoff)              |
   |      drive/<driveId>__file         fetched/pairs        |
   +----------------------------+----------------------------+
                                |                +-----------------+
                                v                | fetch-investments|
                     +----------------------+    | IBKR connector   |
                     | sync-finance-data    |    | (best-effort)    |
                     | AI interpretation    |    +--------+---------+
                     | audited inserts      |             |
                     +----------+-----------+             |
                                |     +-------------------+
                                v     v
                     +----------------------+
                     | SQLite (truth)       |----> weekly backup
                     | deterministic math   |      to Drive (best-effort)
                     +----------+-----------+
                                |
                                v
                     +----------------------+
                     | render dashboard     |
                     | HTML + Telegram      |
                     | (+ ⚠️ warnings)      |
                     +----------------------+

fetch-bank-data stages fresh bank data locally — it never writes to Drive; Drive is your territory (manual drops) plus the weekly database backup. sync-finance-data pulls new Drive drops into staging (best-effort — Drive being down just becomes a ⚠️ Telegram warning), reasons through everything staged, inserts rows with source links into SQLite, deletes staged files after commit, and files your dump/ drops into their vault folders. render-finance-dashboard reads SQLite, fetches live prices/FX, fills the template, and writes one portable HTML file.

The dashboard is self-contained: CSS, fonts, Chart.js, chart data, and markup are inlined into output/dashboard.html.

The Skills

FinDash is operated through the plugin's namespaced skills. The two new entry points wrap the rest, so most days you only run one:

Skills live in skills/ and the plugin manifest in .claude-plugin/. Claude Code loads them when you run claude --plugin-dir . from the repo root.

Privacy Model

This repo is designed so the public code can be shared while private financial state stays local or in your Drive vault.

Secrets live in a single local INI file, .secrets/findash (chmod 600), with one section per integration. Omit any section you don't use:

# .secrets/findash — chmod 600. Omit any section you don't use.
[drive]
root_folder_id=<from your vault folder's Drive URL: drive.google.com/drive/folders/<ID>>

[hapoalim]
user_code=<your hapoalim user code>
password=<your hapoalim password>

[cal]
username=<your cal username>
password=<your cal password>

[telegram]
bot_token=<from @BotFather>
chat_id=<your numeric id, from @userinfobot>

[pdf-passwords]
<payslip-filename-pattern>=<password>

rclone.conf stays a separate file — it is rclone's own OAuth config, passed via --config ./rclone.conf.

The committed docs use placeholders for account suffixes, card suffixes, Drive IDs, balances, transaction IDs, and example amounts. Concrete mappings belong in the private SQLite DB or source documents, not in git.

When you run the Claude skills, Claude reads the documents needed for the task. That is the point of the system: Claude supplies the judgment layer, while SQLite and scripts provide the audit trail and repeatable math.

Repo Map

.claude-plugin/       plugin + marketplace manifests
skills/               plugin skills: daily-run, setup, fetch, sync, render, doctor
docs/                 project docs: schema, Drive layout, source document types
scripts/              mechanical parsers, scrapers, renderers, daily runner
templates/            dashboard shell, CSS, and chart code
.secrets/findash      single local INI of credentials, gitignored
data/                 local SQLite database, gitignored
inbox/staging/        local fetch→sync handoff (deleted after ingest), gitignored
output/               rendered dashboard, gitignored

Quickstart

For the full setup, read docs/setup.md. The short version:

1. Install and authenticate Claude Code and the local tools:

qpdf --version          # payslip PDFs
rclone version          # Drive sync
node --version          # bank fetch, needs >=22.13.0
python3 --version
sqlite3 --version

2. Clone this repo and load the plugin from its root:

git clone https://github.com/ya5huk/findash.git
cd findash
claude --plugin-dir .

3. Run the guided onboarding — it auto-fixes the safe pieces and walks you through the rest:

/findash:setup

4. Create .secrets/findash (chmod 600) from the single block in Privacy Model. Omit any section you don't use. rclone.conf stays separate; see Drive + rclone setup and Drive layout.

5. Run the whole flow with one command:

/findash:daily-run

This fetches, syncs, renders, and delivers to Telegram. To run pieces by hand, use /findash:fetch-bank-data, /findash:fetch-investments, /findash:sync-finance-data, and /findash:render-finance-dashboard.

For unattended (cron/launchd) daily runs, schedule the wrapper — it loads the plugin and runs /findash:daily-run:

CLAUDE_BIN="$(command -v claude)" scripts/run_daily.sh

If you want unattended runs to fetch from Hapoalim or Cal, seed the browser profiles once before scheduling:

node scripts/fetch_bank.js --company=hapoalim --setup
node scripts/fetch_bank.js --company=visaCal --setup

In each browser window, log in, complete OTP/CAPTCHA, trust the device if offered, wait for the account page, then press Enter in the terminal. If a bank sends an OTP during a later unattended run, rerun the matching --setup command; the run will continue with stale fetched data until the profile is refreshed.

Install as a plugin (for others)

You don't have to clone to use FinDash. From any Claude Code session:

/plugin marketplace add ya5huk/findash
/plugin install findash@findash

Optional Integrations

• Telegram: sends output/dashboard.html as a bot attachment. Without Telegram, rendering still writes the local dashboard. See Telegram setup.
• Automatic bank/card fetch: pulls Hapoalim and Cal data through israeli-bank-scrapers. Unattended fetch requires a one-time interactive --setup per source to seed trusted-device cookies. Without it, manually upload statements or exports into Drive dump/. See Bank fetch setup.
• Password-protected payslips: requires qpdf and a [pdf-passwords] section in .secrets/findash. Without it, skip payslip PDFs or add the passwords later.
• Interactive Brokers: ingests your IBKR trade history onto a mapped account (so you stop screenshotting trades), plus a reconciliation snapshot, via Anthropic's official IBKR connector — added through Claude's connector directory, not findash config. The daily run attempts it best-effort; the connector authenticates only in hands-on sessions, so unattended runs skip it with a warning — run /findash:fetch-investments by hand (then re-render) for fresh holdings any time. See IBKR setup.

Adapting to another country

FinDash is Israel-first, not Israel-only. The data model, scripts, and dashboard are generic; the locale-specific assumptions are concentrated in a handful of places, so a fork can re-point them without rewriting the core:

Most interpretation lives in the skills' prompts rather than hard-coded rules, so re-pointing those plus the constants above gets you most of the way. PRs that generalize these are welcome — see Contributing.

Docs

• Setup — Claude, rclone, Drive vault, Telegram, bank fetch, daily runs.
• Drive layout — vault folders and filename conventions.
• Document types — what each source document contains and how Claude should interpret it.
• SQLite schema — tables, money conventions, and audit rules.
• Design system — dashboard visual rules.

License

No open-source license is currently granted. All rights are reserved by the repository owner.