Docs

Quick start

One command to install the whole thing. Same flow on Mac and Windows; pick the one that matches your computer.

Mac

Open Terminal (⌘ Space → type "Terminal" → Enter) and paste:

curl -fsSL https://passporttowealth.app/install | bash

The installer takes about 10 minutes on a Mac that already has developer tools installed, up to an hour on a fresh machine. It'll ask for your password once (so it can install system tools via Homebrew) and ask how you sign in to your AI assistant. Everything else is automatic.

Windows

Open PowerShell (Win → type "PowerShell" → Enter) and paste:

irm https://passporttowealth.app/install.ps1 | iex

Tools install via winget (Microsoft's package manager, ships with Windows 10 1809+). Same UX as the Mac flow.

What happens next

1. Type claude in your terminal to open the assistant.
2. Drop your bank statements, payslips, and tax docs into ~/Documents/my-finances/inbox/.
3. Tell the assistant "build my report."
4. The assistant sorts, dedupes, normalizes currencies, fetches exchange rates, categorizes, and shows totals back for you to confirm.
5. Once you approve, the dashboard opens locally in your browser.

What you get

A single workspace folder on your computer. Everything you need lives inside it; nothing else is created on your machine.

~/Documents/my-finances/
├── inbox/                       ← drop new files here
├── 01_bank_transactions/        ← sorted by classify
├── 02_payslips/                 ← never auto-read (sensitive)
├── 03_amazon_orders/
├── 04_reference_docs/
├── 05_other/
├── pipeline/output/             ← intermediate CSVs, error envelopes
├── site/                        ← your rendered dashboard (open in browser)
├── .venv/                       ← isolated Python (uv)
├── config.yaml                  ← editable config
├── rules.yaml                   ← merchant categorization rules
└── .env                         ← passcode + API key (chmod 600)

Re-entry is always claude from any terminal — the skill remembers where the workspace is. To refresh after dropping new files: open the assistant and say "refresh."

Try it with sample data

Don't have your bank exports handy yet? You can run the full pipeline against a fully-synthetic 12-month fixture (deterministic seed-42 generator, fake names and amounts, no real money). It exercises every step the pipeline does on real data.

1. Download the sample files into your inbox

From any terminal:

cd ~/Documents/my-finances/inbox/ \
  && curl -fsSL --remote-name-all \
    "https://passporttowealth.app/demo-data/{demo_checking_2025.csv,demo_brokerage_2025.csv,duplicate_q3_checking.csv,paystub_jan_2025.pdf,tax_assessment_2024.pdf,amazon_orders_2025.pdf,mystery_scan.pdf}"

The seven files together are about 35KB. They cover every code path the pipeline supports:

• demo_checking_2025.csv — 12 months of USD checking, ~400 transactions.
• demo_brokerage_2025.csv — small brokerage with paired transfers (tests the sign convention).
• duplicate_q3_checking.csv — Q3 of the checking file duplicated (the deduper should catch this).
• paystub_jan_2025.pdf — synthetic paystub with a text layer (privacy classifier should route it to 02_payslips/ and not open it).
• tax_assessment_2024.pdf — synthetic tax doc (same: routed but not opened).
• amazon_orders_2025.pdf — synthetic Amazon order summary (OK to read, lands in 03_amazon_orders/).
• mystery_scan.pdf — image-only PDF with no text layer (no-OCR rule routes it to 05_other/).

2. Open the assistant and ask it to build the report

claude

Then in the assistant, say:

build my report

The assistant will sort the files into buckets, dedupe, normalize transactions, fetch FX rates, categorize against the starter rules, run the sanity check, and build the dashboard. Wall time on a warm machine: about 30 seconds.

3. The dashboard opens in your browser

Local file, no third-party server. You can compare it to the live demo dashboard — same data, same layout — to verify your install is producing the right output.

Reset between runs

The pipeline is deterministic, so you can re-run as many times as you want. To start fresh:

rm -rf ~/Documents/my-finances/inbox/* \
       ~/Documents/my-finances/0[1-5]_*/* \
       ~/Documents/my-finances/pipeline/output/*

Then re-download the sample files into inbox/ and run again.

Privacy at a glance

A short summary of what stays on your computer and what doesn't. Full detail in the Privacy Policy.

What stays local by default

• Your source files (bank statements, payslips, tax documents) — the pipeline scripts read them locally and never upload them.
• The categorized transactions and rendered dashboard — opened in your browser via a file:// URL.
• Your AI assistant credentials.

What leaves your computer

• An anonymous install-start ping when the install script finishes the consent gate. Payload: platform (mac or win), UTC timestamp, advisor_id. No IP, no name, no machine ID. Opt out with FCB_NO_ANALYTICS=1.
• Feedback messages you explicitly send (via the "I have feedback" widget on your dashboard). These create GitHub issues; we triage and respond.
• Your dashboard, only if you choose to share it — see Sharing below.
• File contents you ask the assistant to read directly. If you ask Claude "tell me about this paystub," that file goes to Anthropic as part of your conversation, governed by your Anthropic account terms. The default pipeline doesn't ask Claude to read source files; it processes them with local Python scripts.

What this installs

The complete list of packages, URLs, and files the install scripts touch. This section is auto-generated from installer/install.sh and installer/install.ps1 — if a new package appears in the install scripts but isn't documented here, the build fails. So this list cannot drift.

System tools

Installed via your platform's package manager (Homebrew on Mac, winget on Windows). Skipped if already present.

• jqA small command-line tool for reading JSON. Used by the publish flow when talking to the dashboard host. Installed via Homebrew on Mac, winget on Windows.
• nodeNode.js — the JavaScript runtime. Required because Claude Code is distributed via npm and the skill itself is fetched via npx (a Node tool). Installed via Homebrew on Mac, winget on Windows.
• python 3.11The Python version your workspace uses. uv downloads and isolates this; it doesn't replace whatever Python your computer came with.
• uvAstral's Python toolchain. Replaces the older Homebrew + Python + venv + pip chain with a single binary. Manages Python 3.11, the workspace virtual environment, and the Python packages below. Downloaded from astral.sh.

Python packages (workspace virtual environment)

Installed by uv into an isolated environment inside your workspace. They never affect your system Python or any other Python project.

• chardetDetects character encoding on CSV files. Bank exports come in surprising encodings; chardet figures it out.
• openpyxlReads Excel spreadsheets. Used by the categorize step if you have any .xlsx exports.
• pdfplumberReads text-layer PDFs (bank statements, paystubs). Never OCRs image-only PDFs by design — those route to a separate folder for you to review manually.
• pyyamlParses YAML configuration files (rules.yaml, fx_overrides.yaml).
• reportlabGenerates the synthetic PDFs in the demo kit (paystub, tax doc). Only used when regenerating the demo, never on your real data.

URLs the installer fetches

Every URL the install scripts contact, with what we use it for.

• https://api.anthropic.com/v1/messagesAnthropic's API. Hit only if you choose 'Anthropic API key' as your sign-in method, to verify the key works. Never hit if you sign in with a Claude Pro/Max subscription.
• https://api.frankfurter.app/latestFrankfurter latest-rates endpoint. Hit during install pre-flight to verify network reachability.
• https://astral.sh/uv/install.shAstral's official uv installer. Downloads the uv binary.
• https://claude.ai/install.shAnthropic's official Claude Code installer. Downloads the Claude Code CLI. Mac fallback path used when npm isn't available.
• https://passport-feedback.rafaeldf2.workers.dev/installAnonymous install-start telemetry endpoint. Payload: platform (mac or win), build_stamp, advisor_id. NO IP, NO name, NO machine ID. Opt out with FCB_NO_ANALYTICS=1.
• https://passporttowealth.app/installThe branded short URL for the Mac install command. Resolves to a tiny shim that exec-fetches install.sh from GitHub raw — same source code, friendlier domain.
• https://passporttowealth.app/install.ps1Same as above for Windows.
• https://raw.githubusercontent.com/Homebrew/install/HEAD/install.shHomebrew's official installer. Downloads Homebrew, the standard Mac package manager. Only run if jq or Node aren't already on the system.
• https://raw.githubusercontent.com/passporttowealth/passporttowealth/main/installer/install.ps1The canonical Windows install script on this repo's main branch.
• https://raw.githubusercontent.com/passporttowealth/passporttowealth/main/installer/install.shThe canonical Mac install script on this repo's main branch. The install one-liner you ran resolves to this.

Files and folders we create

Everything the installer writes to your machine. Nothing is created outside these locations.

• ~/Documents/my-finances/Your workspace. Created on first install. Holds your inbox, the categorized output, the dashboard, and a config.yaml you can edit. Nothing is created elsewhere on disk.
• ~/Documents/my-finances/.venv/The isolated Python environment uv creates for the pipeline. Lives inside your workspace; can be deleted and recreated anytime.
• ~/Documents/my-finances/.envStores your dashboard passcode (only if you ever publish), your Anthropic API key (only if you chose that sign-in option), and the SITE_URL after first publish. chmod 600 — owner-readable only.
• ~/Library/Logs/passport-to-wealth-install.logMac install log. Plain text. You can read or send it to your advisor for support.
• %LOCALAPPDATA%\PassportToWealth\Logs\passport-to-wealth-install.logWindows install log. Same purpose as above.
• ~/.zshrc / ~/.bashrcYour shell configuration file. We append (idempotently — never twice) one block: an export line for ANTHROPIC_API_KEY, only if you chose API-key sign-in. Otherwise untouched.
• User-scope environment variables (Windows)On Windows, ANTHROPIC_API_KEY is also written as a User-scope environment variable so 'claude' finds it from any new PowerShell window.

What we never touch

• Your IP address, name, machine identifier, or any personally-identifying field. The install-start telemetry deliberately strips all of these.
• Any folder outside ~/Documents/my-finances/ on Mac or %USERPROFILE%\Documents\my-finances\ on Windows.
• Your Desktop. No icon, no shortcut, no app. To re-open the assistant later: open Terminal (Mac) or PowerShell (Windows) and type 'claude'.
• Anything administrative beyond what brew, winget, and uv themselves request when installing their own tools. The install never asks for sudo password directly.
• Your source files (bank statements, paystubs, tax documents) during the install itself. The installer never opens them. After install, if you explicitly ask the assistant to read a specific file, the file content goes to Anthropic's API as part of your Claude conversation, governed by your Anthropic account terms.

Sharing your dashboard

Local-only by default. If you want to share with an advisor or family member, you can opt in per dashboard.

To share, tell the assistant "share my dashboard." The skill:

1. Generates a phone-friendly passcode (4 lowercase words, easy to type).
2. Publishes the rendered site/ directory to a private here.now URL behind that passcode.
3. Reads the URL and passcode back to you, and saves both in ~/Documents/my-finances/.env so you can look them up later.

The published bundle includes the categorized transactions (in JSON embedded in the page and CSV exports under downloads/) and the aggregate summaries shown in the dashboard. It does not include the original source files (PDFs, statements). Anyone with the URL plus the passcode can see the dashboard contents; share them carefully.

To take a published dashboard down: tell the assistant "delete my site" (or run delete-my-site.command from the workspace).

Reference

Environment variables, opt-outs, and other knobs.

Environment variables

Common questions

Where does my data live? In ~/Documents/my-finances/ on Mac, or %USERPROFILE%\Documents\my-finances\ on Windows. Open it like any folder.

How do I uninstall? Delete the workspace folder. To also remove Claude Code, follow Anthropic's uninstall instructions for the CLI. To remove uv, jq, and Node, use your package manager (brew uninstall or winget uninstall).

Does this work offline? The install needs internet (to download tools and fetch packages). Once installed, the pipeline runs offline except for the FX rate fetch (which uses Frankfurter; you can disable by removing the FX step from refresh.sh). The dashboard works fully offline.

What if I find a bug? Click "I have feedback" on your dashboard, or open an issue at github.com/passporttowealth/passporttowealth/issues.