taxtrace

taxtrace

Prepare a US federal and state return from your own documents, on your own machine, with every number traced to the page it came from.

taxtrace does not file anything. It reads a folder of your documents (W-2s, 1099s, 1098s, property manager statements, receipts, foreign bank statements, last year's return) and produces an entry sheet you type into consumer tax software, an FBAR account list, and a list of questions for you: anything it couldn't settle from the documents alone.

Three rules hold everywhere:

1. Nothing is guessed. Every value carries the file, the page and the exact text it was read from, and a deterministic check rejects any value whose quote isn't on that page.
2. Your documents never leave your machine. Where a language model reads them (sorting documents, reading messy receipts), it is a local MLX model on your Mac. The chat can use a cloud model, which only ever sees masked text (see Chat).
3. Nothing is decided silently. A receipt that could be a repair or an improvement, a missing 1099, a rate choice: each is a question for you, with the evidence next to it.

Status

Early. What works today:

• taxtrace redact: masks a document down to its layout, so a layout can be studied (by a person or an AI assistant helping write a parser) without its values, names or places. Every digit becomes #, and every word the IRS's own publications don't use in lowercase becomes *s, so names, streets and towns go without anyone listing them.
• taxtrace import, outline and unlock: sort a preparer's export into the workspace, list the forms in each document, and check passwords kept in the Keychain.
• taxtrace prior: reads a filed return's carryforwards (see Carryforwards).
• taxtrace k1: reads each Schedule K-1 (Form 1065) face, every box and code, its statements, the Schedule K-3, and North Carolina's D-403 NC K-1 (see K-1s).
• taxtrace passive: each passive activity's year and the loss it carries in (see Passive activities).
• taxtrace 1098: reads each Form 1098 mortgage interest statement (see Form 1098).
• taxtrace 1099: reads the 1099-DIVs, 1099-INTs and 1099-Bs on brokers' consolidated 1099 statements (see Forms 1099-DIV and 1099-INT and Stock sales).
• taxtrace rental: puts the rental's Schedule E together, line by line (see Schedule E).
• taxtrace qbi: Form 8995, the qualified business income deduction (see Form 8995).
• taxtrace paystub: reads a pay stub's income tax withheld, and projects the year's (see Estimated tax).
• taxtrace estimates: the year's withholding and estimated payments against the safe harbor, quarter by quarter (see Estimated tax).
• taxtrace ira: each spouse's IRA deduction and the Roth IRA's limit at the year's projected income (see IRAs).
• taxtrace jobchange: the year as the pay stub projects it, against leaving one job and starting another (see A change of job).
• taxtrace sales: the year's stock sales for Schedule D, the wash-sale windows, and the room left for losses (see Stock sales).
• taxtrace moves: the year's tax-saving moves, ranked by the dollars each saves, with deadlines (see The year's moves).
• taxtrace itr: reads India's income tax return (ITR-2): a property sale, the interest, the tax India kept (see India's return).
• taxtrace bank: reads a foreign bank's statement of account: interest, a tax refund, balances (see Bank statements).
• taxtrace entry: the year's entry sheet, to type into a filing site (see Entry sheet).
• taxtrace ui: the workspace in the browser, with a chat (see Chat).

• taxtrace agi: the year's federal adjusted gross income, against the filed return when there is one (see Adjusted gross income).
• taxtrace d400: North Carolina's Form D-400 with Schedules S and A (see Form D-400).
• taxtrace w2: reads Form W-2s into the entry sheet, agi and d400 (see Form W-2).
• taxtrace tax: Form 1040's lines 12e to 24 with Form 1116's credit (see Total tax).
• taxtrace yoy: a year against the one before (see Year over year).

Install

pip install -e ".[dev,mcp]"

taxtrace[chat] adds the chat's Claude SDK and taxtrace[mcp] an MCP server. The chat's model on your own computer is whatever OpenAI-compatible server answers at http://127.0.0.1:8010/v1 (vllm-mlx serve --port 8010, mlx_lm.server, LM Studio; LOCAL_LLM_URL points elsewhere on the same computer). taxtrace never loads a model itself, so one server can hold a single copy for every program, and it refuses a server on another machine, since that model sees your values unmasked.

Use

taxtrace import ~/Downloads/portal-export.zip  # filed returns to prior-returns/, the rest by tax year

taxtrace redact ~/TaxData/prior-returns # writes ~/TaxData/redacted/*.txt

A path that isn't one from where you are is looked up in the workspace: taxtrace k1 2025 reads /2025.

taxtrace outline lists each page's masked heading: which forms a document holds, in order (--match '1116|4562' lists only the pages naming them). taxtrace words --page 2 --rows shows a page's words, masked, with where each one sits (--x 300:450 and --top 70:240 narrow it to a region): the geometry of a printed form, for writing a reader of it. --marks adds the drawn shapes, so a checkbox ticked with a drawn mark shows. --page 19-20,69, --page all and several files take one run, so files that share a Keychain entry cost one approval. taxtrace show 'prior-returns/2025*' --page 19 opens a document in Chrome at a page, for you to read yourself. A scanned PDF (pictures of pages, no text) is read through ocrmypdf on your machine (brew install ocrmypdf), once: the searchable copy is kept under the original's sha256 in /ocr-cache, so the text values are quoted from never shifts. A picture (.jpg, .png: a phone's photo or screenshot of a statement, as one arrives in a chat) goes the same way. A chat app shrinks what it sends, though, and a blurred table's rows may not read: bank then saves nothing for that account, and a PDF from the bank (or the picture sent as a document, uncompressed) is the better copy.

import takes a folder or a zip, such as a tax preparer's portal export with one folder per year. It skips identity documents (driver's licenses, Social Security cards, passports) and anything already imported, and records every file it places, with its sha256, in imports.jsonl.

Your documents and everything derived from them live in a workspace folder, ~/TaxData or $TAXTRACE_HOME, which taxtrace refuses to place inside a git repository. Names that are also ordinary words (Will, Grace) go in /redact-terms.txt, one per line.

A password-protected PDF is read with a password kept in the macOS Keychain, never in a file or on a command line. One default entry covers every return that shares a password; an entry under a file's name wins for that file, and one under the name before its first - covers a bank's monthly statements (quillbank for quillbank-4410-2026-01.pdf, quillbank-4410-2026-02.pdf, ...). security asks for it without echoing, and -T "" trusts no app, so macOS asks you (Allow / Deny) each time anything reads it, taxtrace included:

security add-generic-password -s taxtrace -a default -T "" -w

security add-generic-password -s taxtrace -a "2024 Return.pdf" -T "" -w # just this file security add-generic-password -s taxtrace -a quillbank -T "" -w # quillbank-*.pdf

Click Allow, not Always Allow: that would add the reader to the trusted list and end the prompts.

That prompt only takes the typed password. To approve each read with Apple Watch or Touch ID instead:

taxtrace keychain setup                              # the default entry and the chat's key

taxtrace keychain setup --account "2024 Return.pdf" # and a file's own entry

setup builds a small helper (taxtrace/macos/keychain_gate.swift, compiled with the Xcode command line tools) and moves each entry over to it. macOS asks for the entry the old way one last time, and the secret is never retyped or shown. From then on the entry trusts only the helper, and the helper releases it only after macOS's own approval: Apple Watch, Touch ID, or the password where neither is set up. Every read is still yours to allow. Only the entries setup moved go through the helper; any other is read the classic way, with its one prompt. If you deny the classic prompt during setup, it says so and leaves that entry as it was: run setup again. Once the helper is built, store a new password with taxtrace keychain store (a file's name, its issuer's such as quillbank, or default): security asks for it unechoed, then the helper moves it over the way setup does, with one classic prompt. An entry stored with a bare security add-generic-password -T stays security's: macOS adds its own prompt to every read the helper makes, on top of Apple Watch or Touch ID. taxtrace reads each entry at most once per command, so a folder of returns sharing the default password costs one prompt. taxtrace unlock says which entry opens each locked file, and how each stored password is shaped (aaaa99999), never what it is. A password pdfminer turns down is tried once more with qpdf (brew install qpdf), which gets it on stdin and decrypts a copy into a temporary folder for the read: when qpdf turns it down too, the stored password is wrong, not the reader.

Another tool can read an entry setup moved, such as an API key it shares with the chat, without the entry trusting that tool too:

taxtrace keychain read anthropic --for jobwatch   # the secret on stdout, once approved

The prompt names the item and the tool. The secret goes to the program that runs the command, never to a terminal, and an entry setup didn't move isn't read this way.

A tool that reads the key unattended (a background service after a restart) has nobody there to approve, and the approval times out. For a key that guards little, such as one with a spend limit, taxtrace keychain release anthropic moves it back for good: one approval, then security saves it again (the secret on its stdin, never in a command line) and it reads without any prompt, taxtrace's chat included. The document passwords can't be released.

When a read asks for the password instead of Apple Watch or Touch ID (a Watch out of range, asleep or locked falls back to it), taxtrace keychain check says which ways macOS offers right now and why not, and check --try shows one Watch / Touch ID prompt and prints what came back. Neither rebuilds the helper or touches an entry.

Besides PDFs and text files (.txt, .csv), Word documents (.docx: one line per paragraph and per table row) and Excel workbooks (.xlsx: a page per sheet, one line per row) are read, with Python's own zip and XML modules. A password-protected Office file isn't read: save an unprotected copy into the workspace.

redact, outline and unlock with no paths read the whole workspace, leaving out what taxtrace wrote there itself (redacted/, ocr-cache/).

Carryforwards

taxtrace prior            # every return in <workspace>/prior-returns

taxtrace prior --layout # also each line a value came from, masked taxtrace prior --words 23-26,71 # also those pages' masked words, in the same run