Private beta · Mac installation

Install PFIC Catch-Up and try it safely.

Start with the entirely fictional demo. Once that works, create a separate private workspace and bring in your broker’s transaction CSV.

The instructions are public; the application is private. You need access to the private GitHub repository. The application runs locally and the hosted pages never receive your financial records.

← Back to the PFIC Catch-Up walkthrough

Before you start

Allow roughly 10–15 minutes. You need a Mac, a GitHub account that has been granted access to the private repository, and Python 3.12 or later. You do not need an LLM, a local AI model, administrator access, or a cloud account for the calculations.

Use invented data first. Do not put real statements, CSVs, names, addresses, account numbers, or tax identifiers in the application folder. The demo below contains only fictional information.

1. Get the private application

Sign in to GitHub, then open the private repository:

Open the private PFIC Catch-Up repository

If GitHub shows a 404 page, first check that you are signed in with the account that received access. If it still fails, ask the project owner to add that GitHub account as a collaborator.

Easiest option: download a ZIP

  1. On the repository page, select Code, then Download ZIP.
  2. Open the downloaded ZIP.
  3. Move the resulting pfic-catchup folder somewhere stable, such as your Documents folder.
Git users: clone instead

If your GitHub SSH access is already configured, open Terminal and run:

git clone git@github.com:daaronr/pfic-catchup.git
cd pfic-catchup

2. Check Python and install locally

Check Python

Open Terminal (Applications → Utilities → Terminal) and run:

python3 --version

You need Python 3.12 or later. If it is missing or older, install a current stable Python 3 from the official Python macOS page, open a new Terminal window, and check again.

Move Terminal into the application folder

Type cd followed by a space, drag the pfic-catchup folder from Finder into Terminal, then press Return. This avoids having to type the folder path.

Preview the installation

This reports what would be installed and writes nothing:

python3 install.py --dry-run --demo ~/Documents/PFIC-Catchup-Demo

Install and create the fictional demo

python3 install.py --demo ~/Documents/PFIC-Catchup-Demo

The installer copies the local command to ~/.local/bin/pfic, creates the fictional demo, and verifies its output. It does not use administrator access or send anything online.

3. Open and use the synthetic demo

At the end of installation, Terminal prints an Open next: command. Copy and run that exact command. It will resemble:

open ~/Documents/PFIC-Catchup-Demo/exports/2024/audit_bundle.html

This opens a local file in your browser. It is not uploading the demo to a website. If you have Excel or LibreOffice, also open workpapers.xlsx in the same export folder.

What success looks like

To see the guided next-step page for the fictional workspace:

~/.local/bin/pfic continue ~/Documents/PFIC-Catchup-Demo 2024 ~/Documents/PFIC-Catchup-Demo/private-continue-2024.html
open ~/Documents/PFIC-Catchup-Demo/private-continue-2024.html
Stop here if the demo does not work. Do not move on to real records until the fictional bundle is created, verified, and readable.

4. Start a separate workspace for real records

Keep three things separate:

Use pseudonymous labels such as TP1, ACCT1, and FUND1. Names, addresses, SSNs, and full account numbers are not needed for the calculation stage.

Create the first local Continue page with:

~/.local/bin/pfic continue ~/Documents/My-PFIC-Workspace 2024 ~/Documents/private-pfic-continue-2024.html
open ~/Documents/private-pfic-continue-2024.html

Replace 2024 with the tax year you are working on. The workspace does not need to exist yet. The Continue page begins with setup questions and then shows one current task at a time. After completing a task, use the next Continue command shown on the page.

5. Bring in the UK broker CSV

The broker transaction export is the main input. Statements and contract notes are used to check it and resolve gaps.

  1. Download the broker’s transaction history as CSV if available (XLSX is also supported).
  2. Save it unchanged in your private records folder.
  3. Use the tool to inspect its structure. Transaction values are not printed to Terminal.
  4. Create an AJ Bell or generic mapping, then open the private mapping-review page.
  5. Confirm every column and transaction label. The tool will not guess unfamiliar meanings.
  6. Normalize the reviewed table and import it into the PFIC workspace.
  7. Use cash records, year-end statements, and contract notes to reconcile and confirm the imported rows.
Show the AJ Bell CSV commands

These examples assume the setup page created account ID ACCT1 and your CSV is named transaction-history.csv:

~/.local/bin/pfic inspect-table ~/Documents/PFIC-Records/transaction-history.csv

~/.local/bin/pfic make-ajbell-map ~/Documents/PFIC-Records/transaction-history.csv ~/Documents/PFIC-Records/ajbell-map.json --account-id ACCT1 --currency GBP

~/.local/bin/pfic mapping-review ~/Documents/PFIC-Records/ajbell-map.json ~/Documents/PFIC-Records/private-mapping-review.html

open ~/Documents/PFIC-Records/private-mapping-review.html

Complete the page and save reviewed-broker-map.json. Move that downloaded file into the private records folder, then run:

chmod 600 ~/Documents/PFIC-Records/reviewed-broker-map.json

~/.local/bin/pfic normalize-table ~/Documents/PFIC-Records/transaction-history.csv ~/Documents/PFIC-Records/reviewed-broker-map.json ~/Documents/PFIC-Records/normalized-transactions.csv

~/.local/bin/pfic import-csv ~/Documents/My-PFIC-Workspace ~/Documents/PFIC-Records/normalized-transactions.csv

The imported rows remain unresolved until they are checked against the source records. Run Continue again to see the next review task.

If something stops

GitHub shows 404 for the private repository

Sign in with the GitHub account that received access. If it still shows 404, that account has not yet been added as a collaborator.

Python is missing or older than 3.12

Install a current stable Python 3 from the official macOS page, open a new Terminal window, and run python3 --version again.

Terminal says it cannot find install.py

Terminal is in the wrong folder. Type cd followed by a space, drag the application folder into Terminal, and press Return.

Terminal says pfic: command not found

Use the complete command path shown in this guide: ~/.local/bin/pfic.

The demo folder is not empty

Choose a new folder name. The installer deliberately refuses to overwrite an existing demo.

I have only PDFs, not a CSV

The current release can preserve PDFs and extract or OCR their text locally, but it does not automatically turn an arbitrary statement into confirmed transactions. A PDF-only history requires manual entry or help preparing a standard transaction CSV.

Authorized users can also open the complete private quickstart on GitHub.